# check proxy access
Source: https://docs.ankra.ai/api-reference/access-gate/check-proxy-access

https://platform.ankra.app/openapi.json post /api/v1/access/check
Validate the host-bound opaque session and check live organisation membership, SSO verification and exact organisation-wide role grants.

# exchange proxy access
Source: https://docs.ankra.ai/api-reference/access-gate/exchange-proxy-access

https://platform.ankra.app/openapi.json post /api/v1/access/exchange
Consume a one-time sign-in code with its verifier and current policy. Current organisation membership and roles are checked again.

# Sign in to an organisation service using the Platform session and SSO
Source: https://docs.ankra.ai/api-reference/access-gate/sign-in-to-an-organisation-service-using-the-platform-session-and-sso

https://platform.ankra.app/openapi.json get /oauth/access/authorize
Require the existing personal Platform browser session and MFA, then authorise against the organisation registered by the trusted relay.

# start proxy access
Source: https://docs.ankra.ai/api-reference/access-gate/start-proxy-access

https://platform.ankra.app/openapi.json post /api/v1/access/requests
Register an exact-host private service sign-in using a dedicated trusted relay credential. The browser cannot supply the policy or callback host.

# Create an API token
Source: https://docs.ankra.ai/api-reference/account-tokens/create-an-api-token

https://platform.ankra.app/openapi.json post /api/v1/org/account/tokens
Creates an API token for the calling user in the current organisation. The token value is returned only in this response; `expires_at` defaults to 90 days from now, and an empty `scopes` list creates a token without scope restriction. Returns 409 when a token with the same name already exists.

# Delete an API token
Source: https://docs.ankra.ai/api-reference/account-tokens/delete-an-api-token

https://platform.ankra.app/openapi.json delete /api/v1/org/account/tokens/{token_id}
Deletes one of the calling user's API tokens. The token must be revoked first (409 otherwise); returns 404 when it does not exist.

# Exchange a GitHub Actions identity token
Source: https://docs.ankra.ai/api-reference/account-tokens/exchange-a-github-actions-identity-token

https://platform.ankra.app/openapi.json post /api/v1/oidc/github/token
Exchanges a verified GitHub Actions identity token matching an organisation trust policy for a short-lived Ankra token. The subject token is the credential; no Ankra authentication is required. Repository IDs, issuer, audience and policy restrictions are verified. Rate limited per client and organisation.

# List API tokens
Source: https://docs.ankra.ai/api-reference/account-tokens/list-api-tokens

https://platform.ankra.app/openapi.json get /api/v1/org/account/tokens
Lists the calling user's API tokens in the current organisation with name, scopes, expiry, creation, last-used and revocation times. The token secret is never returned.

# Renew an API token
Source: https://docs.ankra.ai/api-reference/account-tokens/renew-an-api-token

https://platform.ankra.app/openapi.json post /api/v1/org/account/tokens/{token_id}/rotate
Mints a replacement for one of the calling user's API tokens with the same name, scopes, project pin and lifetime, returns the new value once, and keeps the old token valid for overlap_hours (default 24, 0 to 168) before it stops by itself. The old token is renamed with a -replaced- suffix. Its expiry notices close.

# Revoke an API token
Source: https://docs.ankra.ai/api-reference/account-tokens/revoke-an-api-token

https://platform.ankra.app/openapi.json post /api/v1/org/account/tokens/{token_id}/revoke
Revokes one of the calling user's API tokens so it can no longer authenticate, and returns the revocation time.

# Confirm your contact email
Source: https://docs.ankra.ai/api-reference/account/confirm-your-contact-email

https://platform.ankra.app/openapi.json post /org/account/contact-email/verify
Checks the code mailed to the pending address and, when it matches, stores that address as your confirmed contact email. Attempts per code are limited.

# Get your contact email
Source: https://docs.ankra.ai/api-reference/account/get-your-contact-email

https://platform.ankra.app/openapi.json get /org/account/contact-email
The address Ankra sends alerts and invoices to when it differs from the one you sign in with, when it was confirmed, and any address waiting for its code.

# Remove your contact email
Source: https://docs.ankra.ai/api-reference/account/remove-your-contact-email

https://platform.ankra.app/openapi.json delete /org/account/contact-email
Takes the contact address off your account, so mail goes to the address you sign in with again. Any code still waiting is cancelled.

# Send a contact email code
Source: https://docs.ankra.ai/api-reference/account/send-a-contact-email-code

https://platform.ankra.app/openapi.json post /org/account/contact-email
Mails a six-digit code to the address you want to use. The address is stored only once the code comes back through the verify route; sends are rate limited per account.

# Cancel an agent run
Source: https://docs.ankra.ai/api-reference/ai-agent-runs/cancel-an-agent-run

https://platform.ankra.app/openapi.json post /api/v1/org/ai-agent-runs/{run_id}/cancel
Cancel one live AI agent run and its session (organisation admins only). The runner interrupts the in-flight turn within seconds.

# Get an agent run
Source: https://docs.ankra.ai/api-reference/ai-agent-runs/get-an-agent-run

https://platform.ankra.app/openapi.json get /api/v1/org/ai-agent-runs/{run_id}
Fetch one dispatched AI agent run with its owning task's name, the full stored outcome summary (the list clips it), and tool_iterations - the tool calls the run's linked session made, or null when no session is attached. turns_used counts sessions, not tool calls.

# Get an agent run's transcript
Source: https://docs.ankra.ai/api-reference/ai-agent-runs/get-an-agent-runs-transcript

https://platform.ankra.app/openapi.json get /api/v1/org/ai-agent-runs/{run_id}/transcript
Read the run's linked session transcript (ai_session_event page after `since`). Events whose payload is a bare JSON string - the assistant's own prose above all - carry it in `payload_text`; `payload` keeps object payloads only.

# List agent runs
Source: https://docs.ankra.ai/api-reference/ai-agent-runs/list-agent-runs

https://platform.ankra.app/openapi.json get /api/v1/org/ai-agent-runs
List the organisation's dispatched AI agent runs across every task, newest first.

# Get a condition's evidence timeline
Source: https://docs.ankra.ai/api-reference/ai-conditions/get-a-conditions-evidence-timeline

https://platform.ankra.app/openapi.json get /api/v1/org/ai-conditions/{condition_id}
Returns one condition's evidence timeline: the tickets filed on it, how each closed and on what evidence, the probes, the playbook runs and the decisions people took. Answers 404 when the condition does not belong to the organisation.

# Get a condition's evidence timeline (browser session)
Source: https://docs.ankra.ai/api-reference/ai-conditions/get-a-conditions-evidence-timeline-browser-session

https://platform.ankra.app/openapi.json get /org/ai-conditions/{condition_id}
Returns one condition's evidence timeline: the tickets filed on it, how each closed and on what evidence, the probes, the playbook runs and the decisions people took. Answers 404 when the condition does not belong to the organisation.

# List the organisation's conditions
Source: https://docs.ankra.ai/api-reference/ai-conditions/list-the-organisations-conditions

https://platform.ankra.app/openapi.json get /api/v1/org/ai-conditions
Lists the organisation's conditions, the recurring problems AI tickets are filed against, most recently observed first, with totals of all, open and chronic conditions. `chronic=true` keeps only conditions closed as no-action three times in a row; `limit` defaults to 100 and is capped at 500.

# List the organisation's conditions (browser session)
Source: https://docs.ankra.ai/api-reference/ai-conditions/list-the-organisations-conditions-browser-session

https://platform.ankra.app/openapi.json get /org/ai-conditions
Lists the organisation's conditions, the recurring problems AI tickets are filed against, most recently observed first, with totals of all, open and chronic conditions. `chronic=true` keeps only conditions closed as no-action three times in a row; `limit` defaults to 100 and is capped at 500.

# Acknowledge an engineering handoff with the tracker's reference
Source: https://docs.ankra.ai/api-reference/ai-engineering-handoffs/acknowledge-an-engineering-handoff-with-the-trackers-reference

https://platform.ankra.app/openapi.json post /api/v1/org/ai-engineering-handoffs/{handoff_id}/acknowledge
Records the engineering tracker's reference for a handoff once the issue exists there (`tracker_reference`, required). Organisation admins only; answers 404 for an unknown handoff.

# Acknowledge an engineering handoff with the tracker's reference (browser session)
Source: https://docs.ankra.ai/api-reference/ai-engineering-handoffs/acknowledge-an-engineering-handoff-with-the-trackers-reference-browser-session

https://platform.ankra.app/openapi.json post /org/ai-engineering-handoffs/{handoff_id}/acknowledge
Records the engineering tracker's reference for a handoff once the issue exists there (`tracker_reference`, required). Organisation admins only; answers 404 for an unknown handoff.

# List the organisation's engineering handoffs
Source: https://docs.ankra.ai/api-reference/ai-engineering-handoffs/list-the-organisations-engineering-handoffs

https://platform.ankra.app/openapi.json get /api/v1/org/ai-engineering-handoffs
Lists the platform-level conditions Ankra handed to the organisation's engineering tracker instead of the AI ticket board. `status` filters by a comma-separated subset of `open`, `filed` and `resolved`; an unknown status answers 422.

# List the organisation's engineering handoffs (browser session)
Source: https://docs.ankra.ai/api-reference/ai-engineering-handoffs/list-the-organisations-engineering-handoffs-browser-session

https://platform.ankra.app/openapi.json get /org/ai-engineering-handoffs
Lists the platform-level conditions Ankra handed to the organisation's engineering tracker instead of the AI ticket board. `status` filters by a comma-separated subset of `open`, `filed` and `resolved`; an unknown status answers 422.

# Create a demo base stack
Source: https://docs.ankra.ai/api-reference/ai-environment/create-a-demo-base-stack

https://platform.ankra.app/openapi.json post /org/ai-environment/demo-base-stacks
Save a new shared demo base stack in status 'configured'. Nothing reaches the cluster here - materialisation happens on the first demo launch that references it. Organisation-admin only; browser session authentication with the X-Ankra-CSRF double-submit header (no bearer twin). Secret parameter values ride as ${SECRET_SLOT:<uuid>} sentinels, never resolved values.

# Delete a demo base stack
Source: https://docs.ankra.ai/api-reference/ai-environment/delete-a-demo-base-stack

https://platform.ankra.app/openapi.json delete /org/ai-environment/demo-base-stacks/{base_stack_id}
Initiate teardown of a demo base stack. Deletion is refused with a 409 while any live demo references it. A never-materialised (configured) row is deleted outright; a materialised one goes to 'deleting' and the maintainer loop finishes the job. Organisation-admin only; browser session authentication with the X-Ankra-CSRF double-submit header (no bearer twin).

# Get the AI environment
Source: https://docs.ankra.ai/api-reference/ai-environment/get-the-ai-environment

https://platform.ankra.app/openapi.json get /api/v1/org/ai-environment
Read the organisation's AI environment settings, including dns_root_domain - the organisation's own Ankra root domain that every generated hostname nests under - and dns_root_domain_default, the platform default that applies when no custom domain is registered.

# List the organisation's demo base stacks
Source: https://docs.ankra.ai/api-reference/ai-environment/list-the-organisations-demo-base-stacks

https://platform.ankra.app/openapi.json get /org/ai-environment/demo-base-stacks
List the organisation's shared demo base stacks (every status except deleted) with their live-demo reference counts. Reads are member-visible; browser session authentication only (no bearer twin).

# List the organisation's source-control bindings and their AI review switches
Source: https://docs.ankra.ai/api-reference/ai-environment/list-the-organisations-source-control-bindings-and-their-ai-review-switches

https://platform.ankra.app/openapi.json get /api/v1/org/ai-gateway/scm-bindings
Every GitHub App installation and GitLab or Bitbucket credential of the organisation, with its AI review, mention replies, PR previews and merge-when-green switches, review model, draft handling, per-pull-request cap, custom instructions and repository rules. Any member of the organisation may read it.

# List the repositories a source-control binding can reach
Source: https://docs.ankra.ai/api-reference/ai-environment/list-the-repositories-a-source-control-binding-can-reach

https://platform.ankra.app/openapi.json get /api/v1/org/ai-gateway/scm-bindings/{provider}/{binding_external_id}/repos
The repositories the GitHub App installation can read, sorted by name, with the repo_full_name a repository rule takes. GitHub App installations only: other providers answer 404. Any member of the organisation may read it.

# List the repositories related to each other for AI review
Source: https://docs.ankra.ai/api-reference/ai-environment/list-the-repositories-related-to-each-other-for-ai-review

https://platform.ankra.app/openapi.json get /api/v1/org/ai-gateway/related-repos
Lists the repository relationships the organisation has stated for cross-repository AI review within one GitHub App installation (`binding_external_id`), with their total. Answers for the organisation's own installations only.

# Remove a repository's AI review rule from a source-control binding
Source: https://docs.ankra.ai/api-reference/ai-environment/remove-a-repositorys-ai-review-rule-from-a-source-control-binding

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-gateway/scm-bindings/{provider}/{binding_external_id}/repo-overrides
Organisation admin only. Removes one repository's rule so the repository follows the binding-level settings again. removed is false when the repository had no rule.

# Remove a stated relationship between two repositories
Source: https://docs.ankra.ai/api-reference/ai-environment/remove-a-stated-relationship-between-two-repositories

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-gateway/related-repos/{related_repo_id}
Removes a stated repository relationship and answers 204. Organisation admins only; answers 404 when the relationship does not belong to the organisation.

# Set a repository's AI review rule on a source-control binding
Source: https://docs.ankra.ai/api-reference/ai-environment/set-a-repositorys-ai-review-rule-on-a-source-control-binding

https://platform.ankra.app/openapi.json put /api/v1/org/ai-gateway/scm-bindings/{provider}/{binding_external_id}/repo-overrides
Organisation admin only. Writes one repository's own switches on the binding, which then apply to that repository instead of the binding-level settings: ai_review turns the AI review on or off for the repository. repo_full_name, ai_review, mention_replies and pr_previews are required; review_model, review_drafts and max_reviews_per_pr are optional and an omitted member keeps its stored value. Writing the same repository again replaces its rule.

# State that two repositories are related for AI review
Source: https://docs.ankra.ai/api-reference/ai-environment/state-that-two-repositories-are-related-for-ai-review

https://platform.ankra.app/openapi.json post /api/v1/org/ai-gateway/related-repos
States that two repositories (`repo_full_name` and `related_repo_full_name`, as `owner/name`) are related, so an AI review of one may read the other. Organisation admins only; GitHub is the only supported provider, and both repositories must be reachable by the GitHub App installation named in `binding_external_id`.

# Update a demo base stack
Source: https://docs.ankra.ai/api-reference/ai-environment/update-a-demo-base-stack

https://platform.ankra.app/openapi.json put /org/ai-environment/demo-base-stacks/{base_stack_id}
Change the mutable designation of a demo base stack: profile, profile version, parameters, and idle TTL. The name (and thus the namespace) is immutable and ignored here; an omitted profile_id keeps the current profile. Changes are refused while the stack is deploying or deleting, and take effect on the next materialisation. Organisation-admin only; browser session authentication with the X-Ankra-CSRF double-submit header (no bearer twin).

# Update a source-control binding's AI review switches
Source: https://docs.ankra.ai/api-reference/ai-environment/update-a-source-control-bindings-ai-review-switches

https://platform.ankra.app/openapi.json put /api/v1/org/ai-gateway/scm-bindings/{provider}/{binding_external_id}
Organisation admin only. ai_review and mention_replies are required; every other member is optional and an omitted member keeps its stored value. merge_when_green is the switch behind merge-when-green: with it on, and the binding's AI mode set to Agent, an '@ankraai merge when green' comment, the portal button or the scm_merge_pull_request tool records a merge intent that Ankra settles once the pull request is green.

# Update the AI environment
Source: https://docs.ankra.ai/api-reference/ai-environment/update-the-ai-environment

https://platform.ankra.app/openapi.json put /api/v1/org/ai-environment
Update the organisation's AI environment settings (organisation admin only). Only the members present in the body are changed. Setting dns_root_domain registers the organisation's own Ankra root domain; it must be a bare domain the organisation owns, already delegated to the Ankra nameservers, and held by no other organisation. The switch is refused with 400 while cluster DNS zones or DNS records still live under the old domain - the response's blocking_cluster_zones and blocking_dns_records members list exactly what to remove first, each capped at 100 entries with a matching *_truncated flag set to true when more exist (read the full lists from /api/v1/org/dns/cluster-zones and /api/v1/org/dns/records).

# Create an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/create-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks
Creates an agent task and answers 201. `name`, `goal_prompt` and `trigger` are required; `tool_profile` defaults to `read_only`. A name already in use answers 409.

# Delete an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/delete-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-tasks/{task_id}
Deletes an agent task so it is no longer scheduled, and answers 204. Answers 404 when it does not exist.

# Hire an agent from a role template (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/hire-an-agent-from-a-role-template-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks/templates/{template_id}/hire
Creates an agent task from a built-in role, optionally scoped to `cluster_id`, and answers 201. Hiring the Reviewer also makes it the ticket desk's reviewer when none is set; answers 409 when an agent with the role's name already exists.

# List agent hire templates (ai.use)
Source: https://docs.ankra.ai/api-reference/ai-management/list-agent-hire-templates-aiuse

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tasks/templates
Lists the built-in agent roles that can be hired, each with its goal prompt and whether the organisation has already hired it.

# List agent task runs (ai.use)
Source: https://docs.ankra.ai/api-reference/ai-management/list-agent-task-runs-aiuse

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tasks/{task_id}/runs
Lists an agent task's recent runs, newest first. `limit` defaults to 20 and is capped at 100; answers 404 when the task does not exist.

# List organisation agent tasks (ai.use)
Source: https://docs.ankra.ai/api-reference/ai-management/list-organisation-agent-tasks-aiuse

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tasks
Lists the organisation's agent tasks: the AI agents that run on a schedule, on an alert or on demand, with their goal, tool profile, autonomy level and budget.

# Pause an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/pause-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks/{task_id}/pause
Stops scheduling an agent task. A run already in progress is allowed to finish its current turn; use stop to cancel it as well.

# Pause or resume all organisation AI (ai.manage)
Source: https://docs.ankra.ai/api-reference/ai-management/pause-or-resume-all-organisation-ai-aimanage

https://platform.ankra.app/openapi.json put /api/v1/org/ai-settings/pause
Pauses (`paused: true`, with an optional `reason`) or resumes all AI in the organisation. Pausing cancels every running chat session and agent run and expires open confirmation cards, reporting how many; both directions are idempotent. Requires `ai.manage`.

# Read an agent task (ai.use)
Source: https://docs.ankra.ai/api-reference/ai-management/read-an-agent-task-aiuse

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tasks/{task_id}
Returns one agent task of the organisation. Answers 404 when it does not exist.

# Read the organisation AI pause switch (ai.manage)
Source: https://docs.ankra.ai/api-reference/ai-management/read-the-organisation-ai-pause-switch-aimanage

https://platform.ankra.app/openapi.json get /api/v1/org/ai-settings/pause
Returns the organisation's AI kill switch: whether all AI is paused, who paused it, when and why. Requires `ai.manage`.

# Reapply the current role envelope (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/reapply-the-current-role-envelope-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks/{task_id}/reapply-template
Brings an agent up to its role template's current envelope. An envelope an operator customised is only replaced with `force: true`; every refusal answers 409 with a machine-readable `reason`.

# Resume an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/resume-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks/{task_id}/resume
Re-enables a paused agent task and restores its schedule from its trigger.

# Run an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/run-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks/{task_id}/run
Queues an enabled agent task for immediate dispatch and answers 202; the scheduler picks it up within its poll interval, and does nothing if a run is already live. Answers 404 when the task does not exist or is disabled.

# Stop an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/stop-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tasks/{task_id}/stop
Pauses an agent task and cancels its live run in the same step, returning `cancelled_run_id` and `cancelled_session_id` when something was running.

# Update an agent task (ai.manage and organisation admin)
Source: https://docs.ankra.ai/api-reference/ai-management/update-an-agent-task-aimanage-and-organisation-admin

https://platform.ankra.app/openapi.json put /api/v1/org/ai-tasks/{task_id}
Updates an agent task's definition: name, goal, trigger, tool profile, autonomy level, budget, capabilities, model and whether it is enabled. Answers 404 when the task does not exist.

# Verify the token's user and organisation (ai.use)
Source: https://docs.ankra.ai/api-reference/ai-management/verify-the-tokens-user-and-organisation-aiuse

https://platform.ankra.app/openapi.json get /api/v1/org/ai-settings/identity
Returns the `organisation_id` and `user_id` the API token resolves to, so an embedded management client can confirm its binding before it forwards requests.

# Clear AI memories
Source: https://docs.ankra.ai/api-reference/ai-memory/clear-ai-memories

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-memory/memories
Deletes every memory the assistant has stored for the calling user in the current organisation and returns how many were removed. Other members' memories are not touched.

# Delete an AI memory
Source: https://docs.ankra.ai/api-reference/ai-memory/delete-an-ai-memory

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-memory/memories/{memory_id}
Deletes one of the calling user's memories; returns 404 when it does not exist, belongs to someone else, or is already deleted.

# Get the learned AI profile
Source: https://docs.ankra.ai/api-reference/ai-memory/get-the-learned-ai-profile

https://platform.ankra.app/openapi.json get /api/v1/org/ai-memory/profile
Returns what the assistant has learned about the calling user (communication style, expertise, preferred tools) and whether learning is on.

# List AI memories
Source: https://docs.ankra.ai/api-reference/ai-memory/list-ai-memories

https://platform.ankra.app/openapi.json get /api/v1/org/ai-memory/memories
Lists the cross-session memories the assistant has stored for the calling user in the current organisation, newest first, up to limit entries (default 50, at most 200).

# Reset the learned AI profile
Source: https://docs.ankra.ai/api-reference/ai-memory/reset-the-learned-ai-profile

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-memory/profile
Clears what the assistant has learned about the calling user's preferences. Stored memories are not affected.

# Update the learned AI profile
Source: https://docs.ankra.ai/api-reference/ai-memory/update-the-learned-ai-profile

https://platform.ankra.app/openapi.json put /api/v1/org/ai-memory/profile
Replaces the calling user's learned profile and/or turns learning on or off; a member left out keeps its stored value.

# Adopt an AI playbook
Source: https://docs.ankra.ai/api-reference/ai-playbooks/adopt-an-ai-playbook

https://platform.ankra.app/openapi.json post /api/v1/org/ai-playbooks/{playbook_id}/adopt
Approves a playbook for use: a platform template becomes the organisation's own approved playbook, and one of the organisation's candidate playbooks becomes approved. Organisation admins only; answers 409 when the playbook cannot be adopted.

# List AI playbooks
Source: https://docs.ankra.ai/api-reference/ai-playbooks/list-ai-playbooks

https://platform.ankra.app/openapi.json get /api/v1/org/ai-playbooks
Lists the organisation's AI playbooks together with the platform templates it can adopt.

# Retire an AI playbook
Source: https://docs.ankra.ai/api-reference/ai-playbooks/retire-an-ai-playbook

https://platform.ankra.app/openapi.json post /api/v1/org/ai-playbooks/{playbook_id}/retire
Retires one of the organisation's own playbooks, with an optional `reason`. Organisation admins only; platform templates cannot be retired, and a playbook that cannot be retired answers 409.

# Read the auto-remediation policy
Source: https://docs.ankra.ai/api-reference/ai-remediation/read-the-auto-remediation-policy

https://platform.ankra.app/openapi.json get /api/v1/org/ai-remediation/policy
The bearer-token twin of the browser read, authorised the same way it is: any authenticated member of the organisation, with no named permission, because the portal already shows this document to every member. The PUT that writes the policy stays a browser session + CSRF + organisation-admin lane and has no token twin. An organisation that never configured a policy reads the disabled default document (enabled false, autonomy_level 'propose', updated_at null) rather than a 404.

# Choose the model one AI lane runs on
Source: https://docs.ankra.ai/api-reference/ai-settings/choose-the-model-one-ai-lane-runs-on

https://platform.ankra.app/openapi.json put /api/v1/org/ai-settings/lane-models/{lane}
Stores the lane's model: a catalog key or an exact OpenRouter model id. Profile summaries accept only enabled, saved organisation catalog keys and never fall back. A null or empty model_key clears the selection, returning other lanes to their default tier and leaving profile summaries unselected. Requires the ai.manage permission.

# List the model each AI lane runs on
Source: https://docs.ankra.ai/api-reference/ai-settings/list-the-model-each-ai-lane-runs-on

https://platform.ankra.app/openapi.json get /api/v1/org/ai-settings/lane-models
Every registered AI lane - deploy analysis, troubleshooting, CI/CD generation, stack README generation and AI code review - with the organisation's selection and the model the lane resolves to today. Member-level. Profile summaries require an explicit saved organisation model; their effective fields are empty when unselected or unavailable.

# Add an AI ticket link
Source: https://docs.ankra.ai/api-reference/ai-tickets/add-an-ai-ticket-link

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/links
Links a record to a ticket by `target_kind` and `target_id`, with a `relation` that defaults to `relates_to`, and answers 201 with the link it created (200 with the existing link when it was already there). A ticket target is the ticket's id or its number (`T-42`), must be another ticket of the organisation, and is stored by id: the ticket itself answers 400, an unknown ticket or one of another organisation 404. A session cannot be linked as `spawned` or `evidence`: the platform records those relations itself.

# Answer an AI ticket's decision
Source: https://docs.ankra.ai/api-reference/ai-tickets/answer-an-ai-tickets-decision

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/decision
Answers the decision a blocked ticket is waiting on, with one of the offered options (`option_key`), a free-text `answer`, or both, so the agent can resume. Answers 409 when the ticket is not waiting on a decision.

# Assign an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/assign-an-ai-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/assign
Assigns a ticket to an agent (`assignee_agent_task_id`) or an organisation member (`assignee_user_id`), never both; send both as null to unassign. Answers 404 when the agent or member is not in the organisation.

# Attach a workspace to an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/attach-a-workspace-to-an-ai-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/workspace
Attaches an AI workspace of the organisation to the ticket, or detaches the current one when `workspace_id` is null.

# Close an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/close-an-ai-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/close
Closes a ticket with a `resolution` and an optional `note`. A close as `fixed` can name what confirmed the fix in `evidence_kind` and `evidence_reference`; without them the caller is recorded as the evidence. A close as `duplicate` can name the open ticket covering the same cause in `duplicate_of`; it is linked to that ticket's canonical keeper, and the call answers 422 when `duplicate_of` accompanies another resolution or names no open ticket of the organisation. Answers 409 when the ticket cannot be closed from its current state.

# Comment on an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/comment-on-an-ai-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/comments
Adds a comment to a ticket's history as the caller and answers 201 with the recorded event.

# Create an AI sub-ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/create-an-ai-sub-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/sub-tickets
Files a sub-ticket under an open ticket and answers 201. `title` is required; `kind` defaults to `request` and `priority` to `medium`. Answers 400 when the parent ticket is closed.

# Create an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/create-an-ai-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets
Supports idempotent submission: pass an Idempotency-Key header (or the equivalent client_token body field). While the ticket filed for a key is live (not done/cancelled), repeating the submission with the same key returns that ticket instead of filing a duplicate. The key is stored on the ticket as source_kind 'client_token' / source_id.

# Create an AI ticket sync connection
Source: https://docs.ankra.ai/api-reference/ai-tickets/create-an-ai-ticket-sync-connection

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/sync/connections
Creates an outbound sync connection that mirrors tickets to Jira, Linear or a generic webhook; `name` and `provider` are required. Organisation admins only; answers 409 when the name is taken and 502 when the external tracker rejects the setup.

# Delete an AI ticket sync connection
Source: https://docs.ankra.ai/api-reference/ai-tickets/delete-an-ai-ticket-sync-connection

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-tickets/sync/connections/{connection_id}
Deletes a sync connection and answers 204. Organisation admins only; answers 404 when the connection does not exist.

# Detach an AI ticket from its root
Source: https://docs.ankra.ai/api-reference/ai-tickets/detach-an-ai-ticket-from-its-root

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/detach
Makes a symptom a top-level ticket again, with an event on both timelines. Its status and any question it carries are left as they are, and it is worked like any other ticket from then on. A ticket that sits under no root is returned unchanged; a subtask is refused with 409.

# Draft an AI ticket plan
Source: https://docs.ankra.ai/api-reference/ai-tickets/draft-an-ai-ticket-plan

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/plan
Records a plan written by the caller on the ticket (`plan_document`). Answers 404 when the ticket does not exist or is already closed.

# Get AI ticket desk settings
Source: https://docs.ankra.ai/api-reference/ai-tickets/get-ai-ticket-desk-settings

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/settings
Returns the organisation's ticket desk settings: the Slack channel and Microsoft Teams conversation tickets are announced in, the reviewing agent and whether agent review is required, which insight severities are filed automatically, and the channel notification policy. An organisation that never saved settings reads the defaults.

# Get an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/get-an-ai-ticket

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/{ticket_id}
Returns one ticket of the organisation. Answers 404 when it does not exist.

# Get an AI ticket sync connection
Source: https://docs.ankra.ai/api-reference/ai-tickets/get-an-ai-ticket-sync-connection

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/sync/connections/{connection_id}
Returns one sync connection of the organisation, without its stored credential. Answers 404 when it does not exist.

# Get the AI ticket board summary
Source: https://docs.ankra.ai/api-reference/ai-tickets/get-the-ai-ticket-board-summary

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/summary
Returns the board's counts for top-level tickets: per status, per kind and priority, tickets needing a human, tickets in flight, tickets done in the last 7 days, and open tickets assigned to the caller or to each agent. Accepts the same narrowing filters as the ticket list, so the counts match the rows it returns.

# List AI ticket events
Source: https://docs.ankra.ai/api-reference/ai-tickets/list-ai-ticket-events

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/{ticket_id}/events
Lists a ticket's history events in order. Pass `after_sequence` to read only events after one already seen; `limit` defaults to 100 and is capped at 500.

# List AI ticket links
Source: https://docs.ankra.ai/api-reference/ai-tickets/list-ai-ticket-links

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/{ticket_id}/links
Lists the records linked to a ticket, such as chat sessions, agent runs, insights, pending actions, workspaces, merge requests and other tickets, with the relation of each, and under `incoming_links` the ticket links other tickets of the organisation hold on this one. A link to a ticket carries `linked_ticket`: the other ticket's number, title, status and resolution.

# List AI ticket sync connections
Source: https://docs.ankra.ai/api-reference/ai-tickets/list-ai-ticket-sync-connections

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets/sync/connections
Lists the organisation's outbound ticket sync connections (Jira, Linear or a generic webhook). Stored credentials are never returned.

# List AI ticket sync destinations
Source: https://docs.ankra.ai/api-reference/ai-tickets/list-ai-ticket-sync-destinations

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/sync/destinations
Lists the destinations a tracker credential can reach (for example the Linear teams it can file into), so a connection can target one by name. Send either a new `credential` or the `connection_id` of a saved connection; nothing is written. Organisation admins only.

# List AI tickets
Source: https://docs.ankra.ai/api-reference/ai-tickets/list-ai-tickets

https://platform.ankra.app/openapi.json get /api/v1/org/ai-tickets
Tickets are ordered by updated_at DESC, id DESC (stable). Prefer keyset pagination: pass the previous page's next_cursor as cursor; offset is ignored when cursor is set and remains only for existing clients. total_count is always the full filtered population. The search filter is a case-insensitive substring match on title and body; %, _ and \ in the search text match literally.

# Nest an AI ticket under a root
Source: https://docs.ankra.ai/api-reference/ai-tickets/nest-an-ai-ticket-under-a-root

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/nest
Moves an existing ticket under a root ticket as a symptom: the root carries the work, the symptom gets no agent run or thread of its own, and it settles or detaches when the root closes. Name the root with `root_ticket_id` or `root_ticket_number`; a symptom named as the root resolves to its own root. A ticket a person owes an answer on keeps its question. Answers 422 when the root is the ticket itself or does not exist in the organisation, and 409 with the reason when the tickets' state refuses it, for example a closed root, a subtask or a loop.

# Remove an AI ticket link
Source: https://docs.ankra.ai/api-reference/ai-tickets/remove-an-ai-ticket-link

https://platform.ankra.app/openapi.json delete /api/v1/org/ai-tickets/{ticket_id}/links/{link_id}
Removes one link from a ticket, records a `link_removed` event naming who removed it and what it pointed at, and answers 204. Answers 404 when the link does not exist.

# Review an AI ticket plan
Source: https://docs.ankra.ai/api-reference/ai-tickets/review-an-ai-ticket-plan

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/plan/review
Submits a review of the ticket's plan with `verdict` `approve` or `request_changes` and an optional `rationale`. Pass `expected_updated_at` to be refused with 409 if the ticket changed since it was read.

# Transition an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/transition-an-ai-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/ai-tickets/{ticket_id}/transition
Moves a ticket to another `status`, with an optional `note`. Answers 409 when the transition is not allowed from the ticket's current status.

# Update AI ticket desk settings
Source: https://docs.ankra.ai/api-reference/ai-tickets/update-ai-ticket-desk-settings

https://platform.ankra.app/openapi.json put /api/v1/org/ai-tickets/settings
Updates the ticket desk settings sent in the body and keeps the rest. Only organisation admins can change them (403 otherwise).

# Update an AI ticket
Source: https://docs.ankra.ai/api-reference/ai-tickets/update-an-ai-ticket

https://platform.ankra.app/openapi.json patch /api/v1/org/ai-tickets/{ticket_id}
Updates a ticket's metadata: title, body, priority, labels, cluster, staffing and due date. Fields left out keep their values, and an explicit `null` clears `cluster_id` or `due_at`.

# Update an AI ticket sync connection
Source: https://docs.ankra.ai/api-reference/ai-tickets/update-an-ai-ticket-sync-connection

https://platform.ankra.app/openapi.json put /api/v1/org/ai-tickets/sync/connections/{connection_id}
Updates a sync connection; fields left out of the body keep their current values. Organisation admins only; answers 404 for an unknown connection.

# Create an alert ingest credential
Source: https://docs.ankra.ai/api-reference/alerts/create-an-alert-ingest-credential

https://platform.ankra.app/openapi.json post /api/v1/org/alerts/ingest-credentials
Mints an ingest credential and returns its token together with the webhook path (`/webhooks/alerts/{credential_id}`) that accepts Alertmanager webhook payloads. The token is shown only in this response; `scope` is `cluster`, `platform` or `mixed`, a `mixed` credential must be pinned to a cluster with `cluster_id`, and a `platform` one must not be.

# Create an alert integration
Source: https://docs.ankra.ai/api-reference/alerts/create-an-alert-integration

https://platform.ankra.app/openapi.json post /api/v1/org/alerts/integrations
Creates an alert destination. `integration_type` defaults to `slack`; a Slack or Microsoft Teams channel destination carries `channel_id` (Teams also needs `teams_tenant_id`) and every other destination needs a webhook `url`. A name already in use answers 400.

# Delete an alert ingest credential
Source: https://docs.ankra.ai/api-reference/alerts/delete-an-alert-ingest-credential

https://platform.ankra.app/openapi.json delete /api/v1/org/alerts/ingest-credentials/{credential_id}
Revokes an ingest credential so its token can no longer deliver alerts. Answers 404 when the credential does not belong to the organisation.

# Delete an alert integration
Source: https://docs.ankra.ai/api-reference/alerts/delete-an-alert-integration

https://platform.ankra.app/openapi.json delete /api/v1/org/alerts/integrations/{integration_id}
Deletes an alert integration so no further alerts are delivered to it. Answers 404 when it does not exist in the organisation.

# Get an alert integration
Source: https://docs.ankra.ai/api-reference/alerts/get-an-alert-integration

https://platform.ankra.app/openapi.json get /api/v1/org/alerts/integrations/{integration_id}
Returns one alert integration of the organisation. Answers 404 when it does not exist.

# List alert ingest credentials
Source: https://docs.ankra.ai/api-reference/alerts/list-alert-ingest-credentials

https://platform.ankra.app/openapi.json get /api/v1/org/alerts/ingest-credentials
Lists the organisation's alert ingest credentials: the per-credential endpoints external notifiers such as Prometheus Alertmanager use to deliver alerts into Ankra. Tokens are never returned.

# List alert integrations
Source: https://docs.ankra.ai/api-reference/alerts/list-alert-integrations

https://platform.ankra.app/openapi.json get /api/v1/org/alerts/integrations
Lists the organisation's alert integrations (the webhook and channel destinations alerts are delivered to), paginated with `page` and `page_size` (default 20, at most 100). `search` filters by name and `enabled` by state.

# List Microsoft Teams channels for alert integrations
Source: https://docs.ankra.ai/api-reference/alerts/list-microsoft-teams-channels-for-alert-integrations

https://platform.ankra.app/openapi.json get /api/v1/org/alerts/integrations/teams/channels
Lists the channels of every team the Ankra bot is installed in across the organisation's connected Microsoft Teams tenants, for choosing a channel destination. Answers 404 when no Teams tenant is connected.

# List Slack channels for alert integrations
Source: https://docs.ankra.ai/api-reference/alerts/list-slack-channels-for-alert-integrations

https://platform.ankra.app/openapi.json get /api/v1/org/alerts/integrations/slack/channels
Lists the Slack channels the Ankra bot can post to in the organisation's connected Slack workspace, for choosing a channel destination. Answers 404 when no workspace is connected and 409 with `missing_scopes` when the Slack grant is too narrow to list channels.

# Test an alert integration
Source: https://docs.ankra.ai/api-reference/alerts/test-an-alert-integration

https://platform.ankra.app/openapi.json post /api/v1/org/alerts/integrations/{integration_id}/test
Sends a test alert to a saved integration (its webhook URL or its Slack or Teams channel) and returns whether delivery succeeded, with the HTTP status and response time. The result is recorded as the integration's last test.

# Test an alert integration URL
Source: https://docs.ankra.ai/api-reference/alerts/test-an-alert-integration-url

https://platform.ankra.app/openapi.json post /api/v1/org/alerts/integrations/test-url
Sends a test alert to a webhook `url` before it is saved, optionally rendered with `template`, and returns whether delivery succeeded with the HTTP status and response time. Answers 400 for a missing or malformed URL.

# Update an alert integration
Source: https://docs.ankra.ai/api-reference/alerts/update-an-alert-integration

https://platform.ankra.app/openapi.json put /api/v1/org/alerts/integrations/{integration_id}
Updates the fields sent in the body (name, URL, channel, template, description, enabled) and leaves the rest unchanged. Answers 404 for an unknown integration and 400 when the new name is already in use.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/vms
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Add a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/add-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/vms
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Add node group
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/node-groups
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Add node group (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/add-node-group-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/node-groups
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Check Kubernetes upgrade readiness (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/check-kubernetes-upgrade-readiness-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Create Ankra Cloud cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/create-ankra-cloud-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.create`. Creates a self-managed kubeadm / k3s cluster on Ankra Cloud servers: a private RFC 1918 network (`network_ip_range`, or an adopted `private_network_id`), a bastion and the cluster nodes on the private network only. By default (`network_mode` ipv6_only) the nodes reach IPv4 through the zone's NAT64 and the bastion holds only its public IPv6; `network_mode` ipv4_nat adds a router with NAT for IPv4 egress and gives the bastion a public IPv4. Plans replace instance types (`bastion_plan`, `control_plane_plan`, `worker_plan`, `etcd_plan`; node groups keep `instance_type`), `template` is the OS image (default debian-13). The preflight runs first and the first failing item is the refusal. kubeadm requires Cilium; the ankra-cloud-ccm is always installed. `bastion_port` is accepted for contract symmetry and ignored: the bastion listens on 22. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# Create Ankra Cloud cluster (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/create-ankra-cloud-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.create`. Creates a self-managed kubeadm / k3s cluster on Ankra Cloud servers: a private RFC 1918 network (`network_ip_range`, or an adopted `private_network_id`), a bastion and the cluster nodes on the private network only. By default (`network_mode` ipv6_only) the nodes reach IPv4 through the zone's NAT64 and the bastion holds only its public IPv6; `network_mode` ipv4_nat adds a router with NAT for IPv4 egress and gives the bastion a public IPv4. Plans replace instance types (`bastion_plan`, `control_plane_plan`, `worker_plan`, `etcd_plan`; node groups keep `instance_type`), `template` is the OS image (default debian-13). The preflight runs first and the first failing item is the refusal. kubeadm requires Cilium; the ankra-cloud-ccm is always installed. `bastion_port` is accepted for contract symmetry and ignored: the bastion listens on 22. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/ankracloud/{cluster_id}/vms/{vm_id}
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/delete-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/ankracloud/{cluster_id}/vms/{vm_id}
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete node group
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}
Bearer PAT authentication; RBAC permission `clusters.delete`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete node group (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/delete-node-group-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}
Browser session authentication; RBAC permission `clusters.delete`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Deprovision an Ankra Cloud cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/deprovision-an-ankra-cloud-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/ankracloud/{cluster_id}
Bearer PAT authentication; RBAC permission `clusters.delete`. Ordered teardown preserves explicitly retained storage and reports orphaned provider IDs. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Deprovision an Ankra Cloud cluster (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/deprovision-an-ankra-cloud-cluster-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/ankracloud/{cluster_id}
Browser session authentication; RBAC permission `clusters.delete`. Ordered teardown preserves explicitly retained storage and reports orphaned provider IDs. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Diagnose bastion (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/diagnose-bastion-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/bastion/diagnose
Browser session authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `ankracloud_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Get bastion health (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/get-bastion-health-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/bastion/health
Browser session authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Latest restorable state snapshot of a Ankra Cloud cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/latest-restorable-state-snapshot-of-a-ankra-cloud-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the Ankra Cloud cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List Ankra Cloud CPU pools
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-cpu-pools

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/cpu-pools
Bearer PAT authentication; RBAC permission `clusters.read`. The CPU pools of one Ankra Cloud zone: compute nodes grouped by exact CPU, each with its x86-64 microarchitecture level (`x86_64_level`, 3 or more has AVX2) and `has_avx2`. A server is placed in one pool and only moves within it, so a node group pinned to a pool (`cpu_pool` on node-group add) decides which CPU instructions its workloads may use. `zone` is required. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud CPU pools (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-cpu-pools-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/cpu-pools
RBAC permission `clusters.read`. The CPU pools of one Ankra Cloud zone: compute nodes grouped by exact CPU, each with its x86-64 microarchitecture level (`x86_64_level`, 3 or more has AVX2) and `has_avx2`. A server is placed in one pool and only moves within it, so a node group pinned to a pool (`cpu_pool` on node-group add) decides which CPU instructions its workloads may use. `zone` is required. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud networks
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-networks

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/networks
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Private networks the cluster may adopt instead of creating one. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud networks (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-networks-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/networks
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Private networks the cluster may adopt instead of creating one. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud plans
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-plans

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/plans
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Server plans with monthly and hourly prices in cents. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud plans (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-plans-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/plans
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Server plans with monthly and hourly prices in cents. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud pricing
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-pricing

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/pricing
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Storage tier prices and the public IPv4 add-on price, in cents; incomplete pricing carries explicit reasons. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud pricing (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-pricing-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/pricing
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Storage tier prices and the public IPv4 add-on price, in cents; incomplete pricing carries explicit reasons. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud templates
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-templates

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/templates
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Public OS templates a node may be created from. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud templates (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-templates-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/templates
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Public OS templates a node may be created from. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud zones
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-zones

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/zones
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Zones the credential may place servers in; network-only zones are left out. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List Ankra Cloud zones (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-ankra-cloud-zones-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/zones
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. Zones the credential may place servers in; network-only zones are left out. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# List instance types for an Ankra Cloud cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-instance-types-for-an-ankra-cloud-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/instance-types
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. The plan catalog under the cluster's own credential; /instance-types is the alias the shared node-group pickers read. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# List instance types for an Ankra Cloud cluster (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-instance-types-for-an-ankra-cloud-cluster-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/instance-types
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. The plan catalog under the cluster's own credential; /instance-types is the alias the shared node-group pickers read. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# List live cluster Ankra Cloud CPU pools
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-live-cluster-ankra-cloud-cpu-pools

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/cpu-pools
Bearer PAT authentication; RBAC permission `clusters.read`. The CPU pools of the cluster's own Ankra Cloud zone under its credential, each with its x86-64 microarchitecture level (`x86_64_level`, 3 or more has AVX2) and `has_avx2`, for choosing the `cpu_pool` a node group pins its servers to.

# List live cluster Ankra Cloud CPU pools (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-live-cluster-ankra-cloud-cpu-pools-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/cpu-pools
RBAC permission `clusters.read`. The CPU pools of the cluster's own Ankra Cloud zone under its credential, each with its x86-64 microarchitecture level (`x86_64_level`, 3 or more has AVX2) and `has_avx2`, for choosing the `cpu_pool` a node group pins its servers to.

# List live cluster Ankra Cloud plans
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-live-cluster-ankra-cloud-plans

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/plans
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.read`. The plan catalog under the cluster's own credential; /instance-types is the alias the shared node-group pickers read. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# List live cluster Ankra Cloud plans (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-live-cluster-ankra-cloud-plans-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/plans
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.read`. The plan catalog under the cluster's own credential; /instance-types is the alias the shared node-group pickers read. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# List node groups
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/node-groups
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List node groups (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-node-groups-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/node-groups
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List nodes
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/nodes
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List nodes (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-nodes-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/nodes
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/vms
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List standalone VMs (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/list-standalone-vms-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/vms
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Preflight Ankra Cloud cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/preflight-ankra-cloud-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/preflight
Bearer PAT authentication; RBAC permission `clusters. RBAC permission `clusters.create`. Checks the create request against the account without creating anything: the credential authenticates, the zone offers compute, every plan and the template exist, an adopted network lives in the zone, and the counts are within bounds. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# Preflight Ankra Cloud cluster (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/preflight-ankra-cloud-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/preflight
Browser session authentication; RBAC permission `clusters. RBAC permission `clusters.create`. Checks the create request against the account without creating anything: the credential authenticates, the zone offers compute, every plan and the template exist, an adopted network lives in the zone, and the counts are within bounds. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off. With no `credential_id`, the organisation's built-in Ankra Cloud credential is used, and the request answers 503 with Retry-After when it cannot be created or renewed right now.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/control-plane
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read control-plane sizing (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-control-plane-sizing-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/control-plane
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read Kubernetes version
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/k8s-version
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read Kubernetes version (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-kubernetes-version-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/k8s-version
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/nodes/{node_id}
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-node-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/nodes/{node_id}
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `aws_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node-group autoscaling
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-node-group-autoscaling

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/autoscaling
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node-group autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-node-group-autoscaling-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/autoscaling
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/access-info
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read private cluster access (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-private-cluster-access-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/access-info
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/ssh-keys
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-ssh-keys-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/ssh-keys
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read worker count
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/worker-count
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read worker count (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/read-worker-count-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/worker-count
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/vms/{vm_id}/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/vms/{vm_id}/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/control-plane/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize control-plane nodes (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-control-plane-nodes-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/control-plane/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize node group
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize node group (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-node-group-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize the public gateway
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-the-public-gateway

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/bastion/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize the public gateway (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resize-the-public-gateway-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/bastion/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Restart node
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/restart-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/nodes/{node_id}/restart
Bearer PAT authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Restart node (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/restart-node-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/nodes/{node_id}/restart
Browser session authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/ssh-keys/resync
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resync SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/resync-ssh-keys-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/ssh-keys/resync
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale node group
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/scale
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale node group (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/scale-node-group-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/scale
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale workers
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/scale-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/scale-workers
Bearer PAT authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale workers (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/scale-workers-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/scale-workers
Browser session authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Start a stopped cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/start-a-stopped-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/start
Bearer PAT authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Start a stopped cluster (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/start-a-stopped-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/start
Browser session authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Stop a cluster
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/stop-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/stop
Bearer PAT authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Stop a cluster (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/stop-a-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/stop
Browser session authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# The persistent volumes deleting an Ankra Cloud cluster removes
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/the-persistent-volumes-deleting-an-ankra-cloud-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/ankracloud/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/aws/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none. Answers 404 while the organisation's `aws_provider` feature flag is off.

# The persistent volumes deleting an Ankra Cloud cluster removes (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/the-persistent-volumes-deleting-an-ankra-cloud-cluster-removes-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/ankracloud/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/aws/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/control-plane
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update control-plane count (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-control-plane-count-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/control-plane
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group autoscaling
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-node-group-autoscaling

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/autoscaling
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-node-group-autoscaling-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/autoscaling
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/labels
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group labels (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-node-group-labels-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/labels
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/taints
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group taints (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-node-group-taints-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/node-groups/{group_name}/taints
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/ankracloud/{cluster_id}/ssh-keys
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/update-ssh-keys-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/ankracloud/{cluster_id}/ssh-keys
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Upgrade the Kubernetes version
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/upgrade-the-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/ankracloud/{cluster_id}/upgrade-k8s-version
Bearer PAT authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Upgrade the Kubernetes version (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-clusters/upgrade-the-kubernetes-version-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/ankracloud/{cluster_id}/upgrade-k8s-version
Browser session authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Create an Ankra Cloud credential
Source: https://docs.ankra.ai/api-reference/ankra-cloud-credentials/create-an-ankra-cloud-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/ankracloud
Bearer PAT authentication; RBAC permission `credentials.write`. The secret is stored in Vault and connection-tested without echoing key material. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# Create an Ankra Cloud credential (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-credentials/create-an-ankra-cloud-credential-browser-session

https://platform.ankra.app/openapi.json post /org/credentials/ankracloud
Browser session authentication; RBAC permission `credentials.write`. The secret is stored in Vault and connection-tested without echoing key material. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# List Ankra Cloud credentials
Source: https://docs.ankra.ai/api-reference/ankra-cloud-credentials/list-ankra-cloud-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/ankracloud
Bearer PAT authentication; RBAC permission `credentials.read`. Returns credential metadata only; api_token is never returned. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# List Ankra Cloud credentials (browser session)
Source: https://docs.ankra.ai/api-reference/ankra-cloud-credentials/list-ankra-cloud-credentials-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/ankracloud
Browser session authentication; RBAC permission `credentials.read`. Returns credential metadata only; api_token is never returned. Answers 404 while the organisation's `ankra_cloud_provider` feature flag is off.

# Add a branch to the application's pipeline
Source: https://docs.ankra.ai/api-reference/applications/add-a-branch-to-the-applications-pipeline

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/pipeline/push-branches
Proposes adding one branch to on.push.branches of the application's .ankra/pipeline.yaml as a pull request, so an environment following that branch has builds to deploy. Only that list changes; every other key and comment stays. A branch the list already matches answers already_covered with no pull request, and a second request while the pull request is open answers already_open. Held to the applications.write permission and audited.

# Add a branch to the application's pipeline (browser session)
Source: https://docs.ankra.ai/api-reference/applications/add-a-branch-to-the-applications-pipeline-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/pipeline/push-branches
Proposes adding one branch to on.push.branches of the application's .ankra/pipeline.yaml as a pull request, so an environment following that branch has builds to deploy. Only that list changes; every other key and comment stays. A branch the list already matches answers already_covered with no pull request, and a second request while the pull request is open answers already_open. Held to the applications.write permission and audited.

# Add a scan to an application's pipeline
Source: https://docs.ankra.ai/api-reference/applications/add-a-scan-to-an-applications-pipeline

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/pipeline-scan
Adds the requested scanners to the application's `.ankra/pipeline.yaml` and opens a pull request proposing it: the missing scanner is appended to the scan stage that follows each build, or a report-only scan stage is inserted after the build. The rest of the file, comments included, is left as it was. A second call while the pull request is open stacks on it. Requires `applications.write`.

# Adopt reviewed operating expectations
Source: https://docs.ankra.ai/api-reference/applications/adopt-reviewed-operating-expectations

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/environments/{environment_id}/operating-expectations
Environment-scoped operating intent. Targets do not provision or certify runtime controls. Adoption checks the reviewed revision and commits intent with an audit record atomically.

# Adopt reviewed operating expectations (browser session)
Source: https://docs.ankra.ai/api-reference/applications/adopt-reviewed-operating-expectations-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/environments/{environment_id}/operating-expectations
Environment-scoped operating intent. Targets do not provision or certify runtime controls. Adoption checks the reviewed revision and commits intent with an audit record atomically.

# Apply application environment secrets
Source: https://docs.ankra.ai/api-reference/applications/apply-application-environment-secrets

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/env-secrets/apply
Apply the application's stored environment secrets to what is already running: re-seal them into the Secrets the manifests read on every deployment and roll the workloads that read them. An application whose last key has been cleared applies too, and the apply then removes the sealed Secret from the deployment's stack and rolls the workloads off those values - without it, every reconcile put the deleted values back. The values only reach a running workload at deploy time otherwise, so this is the explicit one-click close of that gap - it is never triggered implicitly by setting a value. It takes no body (the values it applies are the ones already stored) and returns none. The deploy parameters of each deployment are left untouched: only the environment-secret manifest and the pod templates that read it are written. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# Apply application environment secrets (browser session)
Source: https://docs.ankra.ai/api-reference/applications/apply-application-environment-secrets-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/env-secrets/apply
Apply the application's stored environment secrets to what is already running: re-seal them into the Secrets the manifests read on every deployment and roll the workloads that read them. An application whose last key has been cleared applies too, and the apply then removes the sealed Secret from the deployment's stack and rolls the workloads off those values - without it, every reconcile put the deleted values back. The values only reach a running workload at deploy time otherwise, so this is the explicit one-click close of that gap - it is never triggered implicitly by setting a value. It takes no body (the values it applies are the ones already stored) and returns none. The deploy parameters of each deployment are left untouched: only the environment-secret manifest and the pod templates that read it are written. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# Approve a security fix merge
Source: https://docs.ankra.ai/api-reference/applications/approve-a-security-fix-merge

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/security-fixes/{run_id}/merge
Approves the merge of one security fix pull request at the head the person reviewed. Ankra merges it at once when its checks and review are green (squash, or through the repository's merge train when it has one), and otherwise refuses with the reason; a push to the branch clears an approval. The person's approval is the authority for the merge, so a paused organisation or application does not hold it. Requires security.manage and the merge authority (an organisation administrator, the pull request's author, or a member whose verified GitHub login can push to the repository); a service account token is refused.

# Approve a security fix merge (browser session)
Source: https://docs.ankra.ai/api-reference/applications/approve-a-security-fix-merge-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/security-fixes/{run_id}/merge
Approves the merge of one security fix pull request at the head the person reviewed. Ankra merges it at once when its checks and review are green (squash, or through the repository's merge train when it has one), and otherwise refuses with the reason; a push to the branch clears an approval. The person's approval is the authority for the merge, so a paused organisation or application does not hold it. Requires security.manage and the merge authority (an organisation administrator, the pull request's author, or a member whose verified GitHub login can push to the repository); a service account token is refused. The browser route also requires the X-Ankra-CSRF header.

# Approve an application's Launch Plan
Source: https://docs.ankra.ai/api-reference/applications/approve-an-applications-launch-plan

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/launch-plan/approvals
Approves the application's live Launch Plan once for a bounded, enumerated action list (ankra-bjkszh.8): the stacks the plan installs in the target cluster, the environment values a person enters (by name; a value only with secret_value_consent), applying them, merging setup pull requests Ankra opened and proved on the application's own repository, the deploy, and the ankra.cc domain. The approval binds to plan_hash from the Launch Plan read and is refused when the plan changed; every open decision must be accepted. Only a person approves: a browser session, or a token whose scopes name ai_actions.approve. The approver must hold every approved action's permission, and the approval expires (one hour by default, at most 24). Requires applications.write. Audited.

# Approve an application's Launch Plan (browser session)
Source: https://docs.ankra.ai/api-reference/applications/approve-an-applications-launch-plan-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/launch-plan/approvals
Approves the application's live Launch Plan once for a bounded, enumerated action list (ankra-bjkszh.8): the stacks the plan installs in the target cluster, the environment values a person enters (by name; a value only with secret_value_consent), applying them, merging setup pull requests Ankra opened and proved on the application's own repository, the deploy, and the ankra.cc domain. The approval binds to plan_hash from the Launch Plan read and is refused when the plan changed; every open decision must be accepted. Only a person approves: a browser session, or a token whose scopes name ai_actions.approve. The approver must hold every approved action's permission, and the approval expires (one hour by default, at most 24). Requires applications.write. Audited.

# Check a branch's demo build
Source: https://docs.ankra.ai/api-reference/applications/check-a-branchs-demo-build

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/demos/build
Preflight a branch demo: resolve the branch's head SHA and probe the container registry for a matching image tag. GitHub or registry problems are reported inside the 200 payload's error and guidance fields, not as HTTP errors. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Check an application's Secret references
Source: https://docs.ankra.ai/api-reference/applications/check-an-applications-secret-references

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/deploy/clusters/{cluster_id}/secret-references
Which Secrets the application's workloads read without `optional: true`, rendered as its next deploy to this cluster namespace would render them, and whether each one will be there when they start: `produced` by the same deploy (its environment secrets, a Secret manifest in the set, or a CloudNativePG Cluster X publishing X-app), `exists` on the cluster, or `missing`. `state` is `unknown` when the manifests could not be rendered or the cluster's Secrets could not be read recently enough to vouch for an absence; an unknown answer never blocks a deploy.

# Check an application's Secret references (browser session)
Source: https://docs.ankra.ai/api-reference/applications/check-an-applications-secret-references-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deploy/clusters/{cluster_id}/secret-references
Which Secrets the application's workloads read without `optional: true`, rendered as its next deploy to this cluster namespace would render them, and whether each one will be there when they start: `produced` by the same deploy (its environment secrets, a Secret manifest in the set, or a CloudNativePG Cluster X publishing X-app), `exists` on the cluster, or `missing`. `state` is `unknown` when the manifests could not be rendered or the cluster's Secrets could not be read recently enough to vouch for an absence; an unknown answer never blocks a deploy.

# Claim an approved Launch Plan action
Source: https://docs.ankra.ai/api-reference/applications/claim-an-approved-launch-plan-action

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/launch-plan/approvals/{approval_id}/claims
Claims one approved action under a plan-level approval, once, before the caller performs it: the gate an Ankra AI run or an MCP or API caller passes to act on the approver's single approval instead of asking again. Refused unless the approval is the caller's own, unexpired and unrevoked, the application's live Launch Plan still hashes as approved, the action is in the approved list and not yet claimed, and the caller still holds the action's permission. Answers the action with the tool that performs it and its bound parameters. Requires applications.write. Audited, refusals included.

# Claim an approved Launch Plan action (browser session)
Source: https://docs.ankra.ai/api-reference/applications/claim-an-approved-launch-plan-action-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/launch-plan/approvals/{approval_id}/claims
Claims one approved action under a plan-level approval, once, before the caller performs it: the gate an Ankra AI run or an MCP or API caller passes to act on the approver's single approval instead of asking again. Refused unless the approval is the caller's own, unexpired and unrevoked, the application's live Launch Plan still hashes as approved, the action is in the approved list and not yet claimed, and the caller still holds the action's permission. Answers the action with the tool that performs it and its bound parameters. Requires applications.write. Audited, refusals included.

# Clone an application environment onto another cluster
Source: https://docs.ankra.ai/api-reference/applications/clone-an-application-environment-onto-another-cluster

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/environments/{environment_id}/clone
Clones one environment of the application onto another cluster: the same image, deploy mode and accepted deploy options (replicas, resources, ports, every option but the addresses), queued as a deploy. Hostnames are claimed organisation-wide, so the copy keeps the target's own address or derives a fresh one. A cluster the application already runs on is overwritten in place. With include_secrets the source's own secret overrides are re-written under the target's Vault path, its suppressions are copied, and the target's other overrides return to the shared value; only key names are returned and each one is audited. environment_id is a stored environment id or the cluster id an unnamed environment is known by. Held to the applications.deploy permission, and applications.write as well when secrets are included. Bearer personal access token; the CLI twin of the browser route (no CSRF header).

# Clone an application environment onto another cluster (browser session)
Source: https://docs.ankra.ai/api-reference/applications/clone-an-application-environment-onto-another-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/environments/{environment_id}/clone
Clones one environment of the application onto another cluster: the same image, deploy mode and accepted deploy options (replicas, resources, ports, every option but the addresses), queued as a deploy. Hostnames are claimed organisation-wide, so the copy keeps the target's own address or derives a fresh one. A cluster the application already runs on is overwritten in place. With include_secrets the source's own secret overrides are re-written under the target's Vault path, its suppressions are copied, and the target's other overrides return to the shared value; only key names are returned and each one is audited. environment_id is a stored environment id or the cluster id an unnamed environment is known by. Held to the applications.deploy permission, and applications.write as well when secrets are included.

# Create an application
Source: https://docs.ankra.ai/api-reference/applications/create-an-application

https://platform.ankra.app/openapi.json post /api/v1/org/applications
Registers a GitHub repository as an application in the organisation and turns on push-to-deploy for it. Requires `applications.write`; `name`, `app_repo_credential_name`, `app_repo_owner` and `app_repo_name` are required and the branch defaults to `main`. A name another application already uses is answered with an error entry in `errors` and no `id`.

# Delete an application
Source: https://docs.ankra.ai/api-reference/applications/delete-an-application

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}
Deletes the application. Requires `applications.delete`. Every deployment of the application is queued for teardown so its workloads do not outlive it, and its environment secrets and registry robot are removed with it; an unknown application answers `success: false`. An application a managed service that has not been retired serves is refused with `409` naming the services.

# Delete an application environment secret
Source: https://docs.ankra.ai/api-reference/applications/delete-an-application-environment-secret

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}/env-secrets/{secret_key}
Clear one environment secret: the catalogue entry and the stored value. The <app>-env Secret stops carrying the key on the application's next deploy. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# Delete an application environment secret (browser session)
Source: https://docs.ankra.ai/api-reference/applications/delete-an-application-environment-secret-browser-session

https://platform.ankra.app/openapi.json delete /org/applications/{application_id}/env-secrets/{secret_key}
Clear one environment secret: the catalogue entry and the stored value. The <app>-env Secret stops carrying the key on the application's next deploy. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# Deploy an application
Source: https://docs.ankra.ai/api-reference/applications/deploy-an-application

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/deploy
Preserves omitted installation options. reset_inputs deliberately removes named overrides so repository defaults apply. Returns a durable operation identity.

# Deploy an application (browser session)
Source: https://docs.ankra.ai/api-reference/applications/deploy-an-application-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/deploy
Preserves omitted installation options. reset_inputs deliberately removes named overrides so repository defaults apply. Returns a durable operation identity.

# Deploy an application demo
Source: https://docs.ankra.ai/api-reference/applications/deploy-an-application-demo

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/demos
Deploy a throwaway demo of the application onto the organisation's staging cluster. Provide exactly one of branch or a positive pr_number; PR demos additionally require an explicit image_tag. Launch env entries are merged over the application's saved demo defaults (overrides win by name) and database overrides the saved throwaway-database default (null keeps it). A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Describe the application's registry robot
Source: https://docs.ankra.ai/api-reference/applications/describe-the-applications-registry-robot

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/registry-robot
Report whether a push robot minted on the registry this application publishes to backs its repository login, and when none does, why - the organisation's project is not provisioned, or the declared registry names no admin_credential_name for Ankra to mint one with. Never contacts the registry. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Fix a branch's demo build
Source: https://docs.ankra.ai/api-reference/applications/fix-a-branchs-demo-build

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/demos/fix-build
Fix a branch whose demo build is missing: apply the deterministic Ankra-side fixes first (publish-readiness auto-fix, failed-run rerun, failed-setup retry) and, when those cannot produce an image, dispatch a one-shot mission agent that investigates the repository and opens a pull request with the fix. The answer points at the dispatched mission rather than carrying its result, so an unattended caller polls the agent run. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Fix a failed application demo
Source: https://docs.ankra.ai/api-reference/applications/fix-a-failed-application-demo

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/demos/{workspace_id}/fix
Dispatch the demo pre-setup mission agent for a failed demo whose container crashed on startup. The agent reads the crash logs, generates the missing demo environment, saves it as the application's demo defaults, and redeploys the demo. No request body. A malformed workspace_id is reported as the same 404 as an unknown demo. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Get a data migration
Source: https://docs.ankra.ai/api-reference/applications/get-a-data-migration

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/launch-plan/data-migration/runs/{run_id}
One data-migration run of the application: its status (running, cut-over, completed, failed, rolling-back, rolled-back, rollback-failed), each step and rollback step with what happened, when the rollback window closes, and whether a rollback was requested. Requires applications.read.

# Get a data migration (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-a-data-migration-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/launch-plan/data-migration/runs/{run_id}
One data-migration run of the application: its status (running, cut-over, completed, failed, rolling-back, rolled-back, rollback-failed), each step and rollback step with what happened, when the rollback window closes, and whether a rollback was requested. Requires applications.read.

# Get a Launch Plan approval
Source: https://docs.ankra.ai/api-reference/applications/get-a-launch-plan-approval

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/launch-plan/approvals/{approval_id}
One plan-level approval of the application's Launch Plan with its approved actions, its status (active, expired or revoked) and the actions claimed under it. Requires applications.read.

# Get a Launch Plan approval (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-a-launch-plan-approval-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/launch-plan/approvals/{approval_id}
One plan-level approval of the application's Launch Plan with its approved actions, its status (active, expired or revoked) and the actions claimed under it. Requires applications.read.

# Get a repository's launch status
Source: https://docs.ankra.ai/api-reference/applications/get-a-repositorys-launch-status

https://platform.ankra.app/openapi.json get /api/v1/org/applications/launch-status
Where a GitHub repository is on its way to a working app on Ankra (ankra-bjkszh.7): not connected, analysing, N decisions left in the Launch Plan, ready for approval, proving the setup pull request, proof failed, or live. The state the Ankra Chrome extension shows on GitHub, Vercel, Lovable and Claude Design pages. Every application the caller can see that builds the repository is listed, the one building branch first. Requires applications.read.

# Get a repository's launch status (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-a-repositorys-launch-status-browser-session

https://platform.ankra.app/openapi.json get /org/applications/launch-status
Where a GitHub repository is on its way to a working app on Ankra (ankra-bjkszh.7): not connected, analysing, N decisions left in the Launch Plan, ready for approval, proving the setup pull request, proof failed, or live. The state the Ankra Chrome extension shows on GitHub, Vercel, Lovable and Claude Design pages. Every application the caller can see that builds the repository is listed, the one building branch first. Requires applications.read.

# Get an application
Source: https://docs.ankra.ai/api-reference/applications/get-an-application

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}
Returns one application of the organisation: its state, generated files, detected stack, latest workflow and delivery status, and a summary of its deployments. Answers 404 when the application does not exist in the organisation.

# Get an application demo's details
Source: https://docs.ankra.ai/api-reference/applications/get-an-application-demos-details

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/demos/{workspace_id}/detail
Return the demo record plus the live picture of its namespace on the staging cluster: the derived provisioning steps, the bill of materials, the namespace's Kubernetes events, and the pod/container names that drive the log viewer. A malformed workspace_id is reported as the same 404 as an unknown demo. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Get an application demo's logs
Source: https://docs.ankra.ai/api-reference/applications/get-an-application-demos-logs

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/demos/{workspace_id}/logs
Collect a bounded log tail from one of the demo's pods. An empty pod resolves to the demo's own pod. tail_lines defaults to 200 and is capped at 2000. A malformed workspace_id is reported as the same 404 as an unknown demo. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Get an application's AI configuration
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-ai-configuration

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/ai-config
Return the AI lanes configured for this application's repository: for each lane whether it runs, whether that decision is inherited from the organisation or overridden for this application, the settings it actually runs with, and the organisation default behind them. An application with no connected source-control binding answers 200 with binding.connected false and a reason, so the AI tab can render its empty state rather than an error. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Get an application's App Contract
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-app-contract

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/app-contract
The App Contract the setup run extracted from an analysed commit of the application (ankra-bjkszh.1): its components, listen port and IP family, environment variables marked required, optional or secret with the file and line that reads each, the external services it talks to, its migrations, build inputs, health routes and exposure. The latest analysed commit by default; commit_sha names one. Every field but application_id is null when no analysis has extracted a contract yet. Requires applications.read.

# Get an application's App Contract (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-app-contract-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/app-contract
The App Contract the setup run extracted from an analysed commit of the application (ankra-bjkszh.1): its components, listen port and IP family, environment variables marked required, optional or secret with the file and line that reads each, the external services it talks to, its migrations, build inputs, health routes and exposure. The latest analysed commit by default; commit_sha names one. Every field but application_id is null when no analysis has extracted a contract yet. Requires applications.read.

# Get an application's demo configuration
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-demo-configuration

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/demo-config
Return the application's saved demo defaults: the environment entries, the throwaway-database flag, and the optional stack-profile and base-stack dependency designations. Secret environment values and secret stack parameters ride as ${SECRET_SLOT:<uuid>} sentinels, never resolved values. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Get an application's Launch Plan
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-launch-plan

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/launch-plan
The Launch Plan for the application (ankra-bjkszh.2, ankra-bjkszh.16), resolved on read from the App Contract of an analysed commit: per external service its lock-in tier with the reason and evidence, the default choice (bring your own, Ankra open source in the cluster, off, a portability PR, or staying at the vendor) and the alternatives; where each environment variable's value comes from; the migration step, port, IP family and exposure; and the decisions only a person can make. The plan is resolved for a target (target): whether it is a playground decides the database default for a Supabase app; other cluster facts are not read yet and say unknown. The latest analysed commit by default; commit_sha names one. Requires applications.read. data_migration is the plan's data move off its vendors for the selection in backup_vault_id and data_migration_choices; without a selection the plan's defaults keep every vendor and it moves nothing.

# Get an application's Launch Plan (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-launch-plan-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/launch-plan
The Launch Plan for the application (ankra-bjkszh.2, ankra-bjkszh.16), resolved on read from the App Contract of an analysed commit: per external service its lock-in tier with the reason and evidence, the default choice (bring your own, Ankra open source in the cluster, off, a portability PR, or staying at the vendor) and the alternatives; where each environment variable's value comes from; the migration step, port, IP family and exposure; and the decisions only a person can make. The plan is resolved for a target (target): whether it is a playground decides the database default for a Supabase app; other cluster facts are not read yet and say unknown. The latest analysed commit by default; commit_sha names one. Requires applications.read. data_migration is the plan's data move off its vendors for the selection in backup_vault_id and data_migration_choices; without a selection the plan's defaults keep every vendor and it moves nothing.

# Get an application's subject state
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-subject-state

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/subject-state
One platform read of everything Ankra records about the application in an environment (ankra-ab5fog.8): the application's record, the place it runs (the one the query names by cluster and namespace, else the environment's one deployment, else every place listed), the installation's current state and the k8s mirror's view of its pods, the newest deploy runs and platform builds with their errors, the setup pull request and the reviews Ankra AI wrote, the active platform errors with the remedy their code names, and the named conversation's actions on it. Every section is three-state: a read that failed or was never attempted is unknown, never empty. Requires applications.read.

# Get an application's subject state (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-an-applications-subject-state-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/subject-state
One platform read of everything Ankra records about the application in an environment (ankra-ab5fog.8): the application's record, the place it runs (the one the query names by cluster and namespace, else the environment's one deployment, else every place listed), the installation's current state and the k8s mirror's view of its pods, the newest deploy runs and platform builds with their errors, the setup pull request and the reviews Ankra AI wrote, the active platform errors with the remedy their code names, and the named conversation's actions on it. Every section is three-state: a read that failed or was never attempted is unknown, never empty. Requires applications.read.

# Get the application timeline
Source: https://docs.ankra.ai/api-reference/applications/get-the-application-timeline

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/timeline
The application's unified timeline, newest first: platform builds, deploys, promotions, rollbacks, demos, AI reviews, what Ankra did on its own and lifecycle events from the platform's own records, capped with the cap reported, a cursor to the next page, and every unreadable source named - an unreadable source is unknown, not a source with no events. Live-fetched lanes (GitHub workflow runs, registry scans) keep their own endpoints.

# Get the application's environments
Source: https://docs.ankra.ai/api-reference/applications/get-the-applications-environments

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/environments
The environment ladder: every place the application runs, one row per environment (wave 1: one per cluster), derived from the deployments read and the installation rows. status is the deployment-state ladder applied to that environment's targets alone; read_state is unknown when the deployments read failed, and environments is then empty - which a client must render as could-not-check, never as no environments. address carries the raw ingress inputs; the verdict is the client's existing rule. custom_domains lists the hostnames each placement's stored ingress_extra_hosts names, each with the certificate verdict the synced cert-manager Certificates and Ingresses give it; its read_state separates none from not-on-record.

# Get the application's planned address
Source: https://docs.ankra.ai/api-reference/applications/get-the-applications-planned-address

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/planned-address
The address the application's first deploy would publish on, knowable from birth when the organisation's preview domain is published by one of its clusters. A read, not a reservation: the deploy's own derivation stays the authority on what is published. state is planned (host named), none (nothing to name yet - the reason says why) or unknown (the organisation's DNS settings could not be read, which is not an organisation without a preview domain).

# Get whether Ankra is paused for an application
Source: https://docs.ankra.ai/api-reference/applications/get-whether-ankra-is-paused-for-an-application

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/autonomy-pause
Whether a person paused Ankra's autonomous actions for this application. While it is paused, auto-remediation does not act on the application's namespaces (or on alerts about a whole cluster it runs on) and Cost Autopilot does not file or run changes on its clusters. Chat and read-only investigation keep working. A failed read is an error, never paused: false.

# Get whether Ankra is paused for an application (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-whether-ankra-is-paused-for-an-application-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/autonomy-pause
Whether a person paused Ankra's autonomous actions for this application. While it is paused, auto-remediation does not act on the application's namespaces (or on alerts about a whole cluster it runs on) and Cost Autopilot does not file or run changes on its clusters. Chat and read-only investigation keep working. A failed read is an error, never paused: false.

# Get who runs each environment
Source: https://docs.ankra.ai/api-reference/applications/get-who-runs-each-environment

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/autonomy
Who runs it: for each of the application's environments, the effective autonomy level (you_run_it, together, ankra_runs_it) in every area, the rule that decided it, and the limits. The stored organisation, application and environment layers apply first; where the organisation layer sets nothing it is seeded from existing settings (auto-remediation policy, Cost Autopilot tier, push-to-deploy) and seeded_from names which. read_state is partial when one of those seeds could not be read and unknown when the environments or the stored policy could not be read, in which case environments is empty and must be rendered as could-not-check, never as no environments.

# Get who runs each environment (browser session)
Source: https://docs.ankra.ai/api-reference/applications/get-who-runs-each-environment-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/autonomy
Who runs it: for each of the application's environments, the effective autonomy level (you_run_it, together, ankra_runs_it) in every area, the rule that decided it, and the limits. The stored organisation, application and environment layers apply first; where the organisation layer sets nothing it is seeded from existing settings (auto-remediation policy, Cost Autopilot tier, push-to-deploy) and seeded_from names which. read_state is partial when one of those seeds could not be read and unknown when the environments or the stored policy could not be read, in which case environments is empty and must be rendered as could-not-check, never as no environments.

# Import a Claude Design application
Source: https://docs.ankra.ai/api-reference/applications/import-a-claude-design-application

https://platform.ankra.app/openapi.json post /api/v1/org/applications/imports/claude-design
Convert a Claude Design export (the .dc.html artboards, canvas.json and images, a zip of them, or a saved canvas page) into a static site, create a GitHub repository for it under the given credential and owner, commit the site with a Dockerfile, and register the application on that repository. Refusals a caller can act on come back as `errors` with a 200, in the create route's shape. The lane ships behind the `claude_design_import` organisation feature flag: while it is off the route answers 404, like the platform build routes.

# Inspect an installation’s live database capture sources
Source: https://docs.ankra.ai/api-reference/applications/inspect-an-installation’s-live-database-capture-sources

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/installations/{installation_id}/recovery-sources
Requires applications.read and backups.read with backups enabled. Resolves CNPG databases from the owned deployed manifest and fresh operator-owned primary Services. Returns 503 for unreadable or ambiguous evidence. This inventory is not a backup or restore receipt. Other database engines are not inventoried.

# Inspect an installation’s live database capture sources (browser session)
Source: https://docs.ankra.ai/api-reference/applications/inspect-an-installation’s-live-database-capture-sources-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/installations/{installation_id}/recovery-sources
Requires applications.read and backups.read with backups enabled. Resolves CNPG databases from the owned deployed manifest and fresh operator-owned primary Services. Returns 503 for unreadable or ambiguous evidence. This inventory is not a backup or restore receipt. Other database engines are not inventoried.

# List an application's data migrations
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-data-migrations

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/launch-plan/data-migration/runs
The application's newest data-migration runs (at most 20), newest first, each with its plan, the state machine's run, the targets and the names of the staged environment values (never a value). Requires applications.read.

# List an application's data migrations (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-data-migrations-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/launch-plan/data-migration/runs
The application's newest data-migration runs (at most 20), newest first, each with its plan, the state machine's run, the targets and the names of the staged environment values (never a value). Requires applications.read.

# List an application's demos
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-demos

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/demos
Return the application's active demos plus everything the demos tab needs in one round-trip: the caller's TTL policy, the staging-cluster status, and the default container port (the generated Dockerfile's EXPOSE port when known). A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List an application's deploy runs
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-deploy-runs

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deploy-runs
List the deploy runs recorded for this application, newest first. application_deploy_run is written when the user presses Deploy and carries the cluster, the ordered roles and the stack name confirmed for each, so an application can show a deploy that is queued, in flight or failed without the browser having remembered its run id - which was previously the only way to reach one. The listing is capped at 50 runs and reports truncated=true when older runs exist beyond it. An unknown application answers 404 rather than an empty list. Browser session authentication only (no bearer twin).

# List an application's image versions with SBOM and findings
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-image-versions-with-sbom-and-findings

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/security/versions
Lists the application's image versions, one row per pushed tag, with the SBOM and vulnerability finding metadata the Security Center holds for each. A version no cluster reports on reads the pipeline's complete image scan of its digest, so a release that has not been deployed yet is not listed as unscanned. `component` narrows the list to one component; answers 404 when the application does not exist in the organisation.

# List an application's image versions with SBOM and findings (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-image-versions-with-sbom-and-findings-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/security/versions
Lists the application's image versions, one row per pushed tag, with the SBOM and vulnerability finding metadata the Security Center holds for each. A version no cluster reports on reads the pipeline's complete image scan of its digest, so a release that has not been deployed yet is not listed as unscanned. `component` narrows the list to one component; answers 404 when the application does not exist in the organisation.

# List an application's jobs
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-jobs

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/jobs
Lists the platform jobs run for the application, paginated with `page` and `page_size` (default 25, at most 100). Answers 404 when the application does not exist in the organisation.

# List an application's rollbacks
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-rollbacks

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/rollbacks
The recorded rollback history of this application's deployment on the named cluster, newest first. It is what explains a deployment running an older build than the newest one the platform observed. Bearer personal access token; the CLI twin of the browser route.

# List an application's rollbacks (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-rollbacks-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/rollbacks
The recorded rollback history of this application's deployment on the named cluster, newest first. It is what explains a deployment running an older build than the newest one the platform observed. Browser session authentication; the bearer twin is GET /api/v1/org/applications/{application_id}/rollbacks.

# List an application's security fixes
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-security-fixes

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/security-fixes
Every security fix pull request opened for the application's findings, newest first (at most 50), each with the remediation run that follows it: the findings it fixes, the checks on its latest pipeline run, the AI review of its head, and whether Ankra merges it when green or waits for a person. Requires applications.read.

# List an application's security fixes (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-an-applications-security-fixes-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/security-fixes
Every security fix pull request opened for the application's findings, newest first (at most 50), each with the remediation run that follows it: the findings it fixes, the checks on its latest pipeline run, the AI review of its head, and whether Ankra merges it when green or waits for a person. Requires applications.read.

# List application deployment placements
Source: https://docs.ankra.ai/api-reference/applications/list-application-deployment-placements

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/deployments
Returns owned application placements and optional workload identity for independent live image verification. Workload references are the applied manifest identities, not proof of running images or availability.

# List application deployment placements (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-application-deployment-placements-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deployments
Returns owned application placements and optional workload identity for independent live image verification. Workload references are the applied manifest identities, not proof of running images or availability.

# List application environment secrets
Source: https://docs.ankra.ai/api-reference/applications/list-application-environment-secrets

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/env-secrets
List the environment-secret keys of an application: which keys its generated manifests read out of the Secrets Ankra fills for it, which of them have a stored value, when each was last set, and - in requirements_state - whether those manifests could be read at all, so an empty missing_keys is never mistaken for a fully configured application. Values are never returned - there is no reveal endpoint on this surface, because a value the platform writes into a cluster Secret has no reason to travel back out. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# List application environment secrets (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-application-environment-secrets-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/env-secrets
List the environment-secret keys of an application: which keys its generated manifests read out of the Secrets Ankra fills for it, which of them have a stored value, when each was last set, and - in requirements_state - whether those manifests could be read at all, so an empty missing_keys is never mistaken for a fully configured application. Values are never returned - there is no reveal endpoint on this surface, because a value the platform writes into a cluster Secret has no reason to travel back out. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# List applications
Source: https://docs.ankra.ai/api-reference/applications/list-applications

https://platform.ankra.app/openapi.json get /api/v1/org/applications
Lists the organisation's applications, paginated with `page` and `page_size` (default 25, at most 100). `search` filters by a case-insensitive match on the application name, and `order` accepts `created` (the default, newest first), `attention` (needs-you-first, A to Z by name within each step) or `name` (A to Z by name).

# List platform builds
Source: https://docs.ankra.ai/api-reference/applications/list-platform-builds

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/builds
The application's platform builds, newest first, capped at 50 with the cap reported - a truncated listing that does not say so reads as complete. Answers 404 for every organisation without the platform_builds flag. Bearer PAT authentication (Authorization: Bearer <token>), with the organisation selected by the token or the X-Ankra-Organisation-Id override. No CSRF header: the double-submit gate belongs to the cookie surface only.

# List platform builds (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-platform-builds-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/builds
The application's platform builds, newest first, capped at 50 with the cap reported - a truncated listing that does not say so reads as complete. Answers 404 for every organisation without the platform_builds flag.

# List the application's branch builds
Source: https://docs.ankra.ai/api-reference/applications/list-the-applications-branch-builds

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/branch-builds
The newest published build of each branch of the application (at most 200 branches, newest first), with the tracked branch: what an environment that follows a branch rule deploys from, so a client can say which build a rule would run or that a branch has published nothing yet. Held to the applications.read permission.

# List the application's branch builds (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-the-applications-branch-builds-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/branch-builds
The newest published build of each branch of the application (at most 200 branches, newest first), with the tracked branch: what an environment that follows a branch rule deploys from, so a client can say which build a rule would run or that a branch has published nothing yet. Held to the applications.read permission.

# List what Ankra did on its own
Source: https://docs.ankra.ai/api-reference/applications/list-what-ankra-did-on-its-own

https://platform.ankra.app/openapi.json get /api/v1/org/applications/autonomous-actions
What Ankra did on its own across every application, newest first: auto-remediation runs on an application's placements, Cost Autopilot actions the autopilot approved itself on an application's cluster, and build fixes the automatic lane sent. Each action is one item naming every application it was on, with who acted, the rule that allowed it and whether it can be undone. At most 20 actions; a source with more is named in capped_sources and a source that could not be read in unavailable_sources.

# List what Ankra did on its own (browser session)
Source: https://docs.ankra.ai/api-reference/applications/list-what-ankra-did-on-its-own-browser-session

https://platform.ankra.app/openapi.json get /org/applications/autonomous-actions
What Ankra did on its own across every application, newest first: auto-remediation runs on an application's placements, Cost Autopilot actions the autopilot approved itself on an application's cluster, and build fixes the automatic lane sent. Each action is one item naming every application it was on, with who acted, the rule that allowed it and whether it can be undone. At most 20 actions; a source with more is named in capped_sources and a source that could not be read in unavailable_sources.

# Mint or rotate the application's registry robot
Source: https://docs.ankra.ai/api-reference/applications/mint-or-rotate-the-applications-registry-robot

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/registry-robot
Make sure a push robot minted for this application backs its repository login: mint one when none does (with Ankra's registry administrator on the organisation's own registry, or with image_registry.admin_credential_name on a registry the organisation operates), refresh its secret when rotate is set, store the login as the platform-managed registry credential ankra-harbor-app-<application-id>, and write it into the repository's Actions secrets. A registry Ankra cannot administer answers 200 with provisioned false and a message naming what would let it. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Open an approved portability pull request
Source: https://docs.ankra.ai/api-reference/applications/open-an-approved-portability-pull-request

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/launch-plan/approvals/{approval_id}/portability-pull-requests
Claims one approved portability pull request action under a plan-level Launch Plan approval, once, and queues the operation that opens it on the application's own repository: the adapter pull request of a dependency the approver moved to needs-portability-pr, or the next.config pull request of a Vercel source. Refused unless the approval is the caller's own, unexpired and unrevoked, the application's live Launch Plan still hashes as approved, the action is an approved portability pull request not yet claimed, and the caller still holds applications.write. The operation renders the change from the newest App Contract at the plan's commit and opens it through the setup write guard; when Ankra cannot make the change with confidence it fails with the reason a person has to, verbatim. Ankra records the pull request for the PR shepherd and never merges it. Audited, refusals included.

# Open an approved portability pull request (browser session)
Source: https://docs.ankra.ai/api-reference/applications/open-an-approved-portability-pull-request-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/launch-plan/approvals/{approval_id}/portability-pull-requests
Claims one approved portability pull request action under a plan-level Launch Plan approval, once, and queues the operation that opens it on the application's own repository: the adapter pull request of a dependency the approver moved to needs-portability-pr, or the next.config pull request of a Vercel source. Refused unless the approval is the caller's own, unexpired and unrevoked, the application's live Launch Plan still hashes as approved, the action is an approved portability pull request not yet claimed, and the caller still holds applications.write. The operation renders the change from the newest App Contract at the plan's commit and opens it through the setup write guard; when Ankra cannot make the change with confidence it fails with the reason a person has to, verbatim. Ankra records the pull request for the PR shepherd and never merges it. Audited, refusals included.

# Park an application deployment
Source: https://docs.ankra.ai/api-reference/applications/park-an-application-deployment

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/deployments/park
Park one deployment of this application: scale its workload to zero replicas on purpose, remembering the prior replica count as parked_replicas inside the stored deploy parameters. The write is the rollback's partial-update shape - one jsonb update of the stored inputs plus the platform's existing deploy job - and the push-to-deploy watermark is moved onto the newest observed build first so a build observed before the park is not converged onto the resting workload. The installation, its manifests and its published Ingress host all stay: parked is a deliberate rest, never not_deployed. Held to the applications.deploy permission. Browser session authentication with the X-Ankra-CSRF double-submit header only (no bearer twin).

# Pause Ankra for an application
Source: https://docs.ankra.ai/api-reference/applications/pause-ankra-for-an-application

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/autonomy-pause
Pauses Ankra's autonomous actions for this application. From the next dispatch, auto-remediation does not act on the application's namespaces (or on alerts about a whole cluster it runs on) and Cost Autopilot does not file or run changes on its clusters; a remediation run already acting there stops before its next mutating step and reports the step it did not run. Chat and read-only investigation keep working, and pausing never starts anything. Pausing a paused application changes nothing and answers its current pause. Each change is audited with who made it. Requires applications.write.

# Pause Ankra for an application (browser session)
Source: https://docs.ankra.ai/api-reference/applications/pause-ankra-for-an-application-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/autonomy-pause
Pauses Ankra's autonomous actions for this application. From the next dispatch, auto-remediation does not act on the application's namespaces (or on alerts about a whole cluster it runs on) and Cost Autopilot does not file or run changes on its clusters; a remediation run already acting there stops before its next mutating step and reports the step it did not run. Chat and read-only investigation keep working, and pausing never starts anything. Pausing a paused application changes nothing and answers its current pause. Each change is audited with who made it. Requires applications.write.

# Preview a promotion between two environments
Source: https://docs.ankra.ai/api-reference/applications/preview-a-promotion-between-two-environments

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/promotions/preview
What promoting the source environment's build into the target would do (ankra-ryfuy.38.4): the build that would move, what the target serves now, the deploy options that differ and stay as they are, the secrets check, the target's manifest-revision drift verdict, and every reason the promotion would be refused, with a fix path each. state is ready, already_current, blocked, or unknown when a read behind the verdict failed - never ready on a guess. Environment ids are the ids the environments read answers with. Held to the applications.deploy permission, as the write is; secrets.missing_keys is null unless the caller also holds applications.write, the env-secrets endpoints' permission. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Preview a promotion between two environments (browser session)
Source: https://docs.ankra.ai/api-reference/applications/preview-a-promotion-between-two-environments-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/promotions/preview
What promoting the source environment's build into the target would do (ankra-ryfuy.38.4): the build that would move, what the target serves now, the deploy options that differ and stay as they are, the secrets check, the target's manifest-revision drift verdict, and every reason the promotion would be refused, with a fix path each. state is ready, already_current, blocked, or unknown when a read behind the verdict failed - never ready on a guess. Environment ids are the ids the environments read answers with. Held to the applications.deploy permission, as the write is; secrets.missing_keys is null unless the caller also holds applications.write, the env-secrets endpoints' permission.

# Promote a proven build into another environment
Source: https://docs.ankra.ai/api-reference/applications/promote-a-proven-build-into-another-environment

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/promotions
Promote the build the source environment has proven into the target environment (ankra-ryfuy.38.4). Exactly one thing moves: the image tag the source runs, written into each target installation's stored deploy inputs and deployed through the same deploy_application job the Deploy button and push-to-deploy enqueue - never a rebuild, never configuration. The target's push-to-deploy watermark is stamped with the promoted build and one application_promotion row records the move. Refused (409) with one of the preview's blocker sentences verbatim: "Source environment is not serving a proven build", "Source environment's build cannot be identified", "Source environment's targets disagree on what they serve", "Target environment follows pushes", "Ankra could not read whether the target environment follows pushes", "Target environment has a deploy in flight", "Target environment is missing required secrets". A target already running the build answers 200 with state already_current and no deploy. Held to the applications.deploy permission. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Promote a proven build into another environment (browser session)
Source: https://docs.ankra.ai/api-reference/applications/promote-a-proven-build-into-another-environment-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/promotions
Promote the build the source environment has proven into the target environment (ankra-ryfuy.38.4). Exactly one thing moves: the image tag the source runs, written into each target installation's stored deploy inputs and deployed through the same deploy_application job the Deploy button and push-to-deploy enqueue - never a rebuild, never configuration. The target's push-to-deploy watermark is stamped with the promoted build and one application_promotion row records the move. Refused (409) with one of the preview's blocker sentences verbatim: "Source environment is not serving a proven build", "Source environment's build cannot be identified", "Source environment's targets disagree on what they serve", "Target environment follows pushes", "Ankra could not read whether the target environment follows pushes", "Target environment has a deploy in flight", "Target environment is missing required secrets". A target already running the build answers 200 with state already_current and no deploy. Held to the applications.deploy permission.

# Queue a platform build
Source: https://docs.ankra.ai/api-reference/applications/queue-a-platform-build

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/builds
Ask Ankra to build the application's image on platform infrastructure (the M2 build lane). Idempotent on (component, head_sha) while a request is live: a redelivery, a retry press and a demo request for the same commit converge on one build, and already_requested reports the join. Answers 404 for every organisation without the platform_builds flag - the surface stays invisible during the dark rollout. Browser session authentication with the X-Ankra-CSRF double-submit header; the bearer twin of this route is POST /api/v1/org/applications/{application_id}/builds. Bearer PAT authentication (Authorization: Bearer <token>), with the organisation selected by the token or the X-Ankra-Organisation-Id override. No CSRF header: the double-submit gate belongs to the cookie surface only.

# Queue a platform build (browser session)
Source: https://docs.ankra.ai/api-reference/applications/queue-a-platform-build-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/builds
Ask Ankra to build the application's image on platform infrastructure (the M2 build lane). Idempotent on (component, head_sha) while a request is live: a redelivery, a retry press and a demo request for the same commit converge on one build, and already_requested reports the join. Answers 404 for every organisation without the platform_builds flag - the surface stays invisible during the dark rollout. Browser session authentication with the X-Ankra-CSRF double-submit header; the bearer twin of this route is POST /api/v1/org/applications/{application_id}/builds.

# Re-bind the application to another GitHub credential
Source: https://docs.ankra.ai/api-reference/applications/re-bind-the-application-to-another-github-credential

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/repository-credential
Move the application onto a GitHub credential of the organisation whose App installation reaches its repository. The credential must exist (400 otherwise); whether its installation reaches the repository is reported in the answer rather than refused. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read a deployment operation and current workload verification
Source: https://docs.ankra.ai/api-reference/applications/read-a-deployment-operation-and-current-workload-verification

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/deployment-verifications/{operation_id}
Scoped live verification of the exact deployment operation and installation. Does not certify recovery or historical availability.

# Read a deployment operation and current workload verification (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-a-deployment-operation-and-current-workload-verification-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deployment-verifications/{operation_id}
Scoped live verification of the exact deployment operation and installation. Does not certify recovery or historical availability.

# Read a platform build
Source: https://docs.ankra.ai/api-reference/applications/read-a-platform-build

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/builds/{build_id}
One platform build: its recipe, the image it pushed, or the error class that routes its failure. Answers 404 for every organisation without the platform_builds flag. Bearer PAT authentication (Authorization: Bearer <token>), with the organisation selected by the token or the X-Ankra-Organisation-Id override. No CSRF header: the double-submit gate belongs to the cookie surface only.

# Read a platform build (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-a-platform-build-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/builds/{build_id}
One platform build: its recipe, the image it pushed, or the error class that routes its failure. Answers 404 for every organisation without the platform_builds flag.

# Read a platform build request
Source: https://docs.ankra.ai/api-reference/applications/read-a-platform-build-request

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/builds/requests/{request_id}
Read one queued build request. Queueing a build answers with a request id before there is a build to read - the build row is created when the scheduler claims the request - so this is how a caller follows that gap: status is pending until the claim, and build_id names the build from then on. Answers 404 for every organisation without the platform_builds flag. Bearer PAT authentication (Authorization: Bearer <token>), with the organisation selected by the token or the X-Ankra-Organisation-Id override.

# Read a platform build request (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-a-platform-build-request-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/builds/requests/{request_id}
Read one queued build request. Queueing a build answers with a request id before there is a build to read - the build row is created when the scheduler claims the request - so this is how a caller follows that gap: status is pending until the claim, and build_id names the build from then on. Answers 404 for every organisation without the platform_builds flag. Browser session authentication.

# Read an application deploy run
Source: https://docs.ankra.ai/api-reference/applications/read-an-application-deploy-run

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deploy-runs/{run_id}
Read one deploy run and its per-role progress. This is the wizard's progress display: the run is driven by the server, so the read is equally correct in a tab that was never open while it ran.

# Read an application's automatic build fixing setting
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-automatic-build-fixing-setting

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/auto-fix-builds
Read whether Ankra automatically runs its fix-build lane - deterministic repairs first, a one-shot mission agent opening a pull request as the fallthrough - when a build of the application's tracked branch fails. On by default: the flag exists to opt out, and automatic dispatch is bounded to one mission per application per UTC day. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read an application's automatic build fixing setting (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-automatic-build-fixing-setting-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/auto-fix-builds
Read whether Ankra automatically runs its fix-build lane - deterministic repairs first, a one-shot mission agent opening a pull request as the fallthrough - when a build of the application's tracked branch fails. On by default: the flag exists to opt out, and automatic dispatch is bounded to one mission per application per UTC day.

# Read an application's proposed setup contract
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-proposed-setup-contract

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/setup-contract
Read the setup Ankra proposed for this application before anything is deployed: the detected stack, whether a database was generated, and the deploy option contract of record. The contract and database each carry a three-valued status - a proposal Ankra could not read answers "unknown", never an empty option list.

# Read an application's push-to-deploy setting
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-push-to-deploy-setting

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/auto-deploy
Read whether a successful build of the application's tracked branch redeploys it automatically, together with the newest build observed on that branch. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read an application's push-to-deploy setting (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-push-to-deploy-setting-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/auto-deploy
Read whether a successful build of the application's tracked branch redeploys it automatically, together with the newest build observed on that branch.

# Read an application's rollback targets
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-rollback-targets

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/rollback-targets
What this application's deployment on the named cluster could be rolled back to: the shape of deployment found, the image tag it is running, the builds still in the registry, whether push-to-deploy is armed, and the list of things a rollback does NOT undo. Bearer personal access token; the CLI twin of the browser route.

# Read an application's rollback targets (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-rollback-targets-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/rollback-targets
What this application's deployment on the named cluster could be rolled back to: the shape of deployment found, the image tag it is running, the builds still in the registry, whether push-to-deploy is armed, and the list of things a rollback does NOT undo. Browser session authentication; the bearer twin is GET /api/v1/org/applications/{application_id}/rollback-targets.

# Read an application's setup pull request auto-merge setting
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-setup-pull-request-auto-merge-setting

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/auto-merge-setup-pull-requests
Read whether Ankra may merge this application's setup pull requests on its own once every check and Ankra's proof of the head are green. enabled is the application's own answer, or null when it follows its organisation's auto_merge_setup_pull_requests; effective is what the merge acts on: on only when the application says on, or when it follows an organisation that opted in. Readable by any member. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read an application's setup pull request auto-merge setting (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-an-applications-setup-pull-request-auto-merge-setting-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/auto-merge-setup-pull-requests
Read whether Ankra may merge this application's setup pull requests on its own once every check and Ankra's proof of the head are green. enabled is the application's own answer, or null when it follows its organisation's auto_merge_setup_pull_requests; effective is what the merge acts on: on only when the application says on, or when it follows an organisation that opted in. Readable by any member.

# Read operating expectations
Source: https://docs.ankra.ai/api-reference/applications/read-operating-expectations

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/environments/{environment_id}/operating-expectations
Environment-scoped operating intent. Targets do not provision or certify runtime controls. Adoption checks the reviewed revision and commits intent with an audit record atomically.

# Read operating expectations (browser session)
Source: https://docs.ankra.ai/api-reference/applications/read-operating-expectations-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/environments/{environment_id}/operating-expectations
Environment-scoped operating intent. Targets do not provision or certify runtime controls. Adoption checks the reviewed revision and commits intent with an audit record atomically.

# Read the demo password
Source: https://docs.ankra.ai/api-reference/applications/read-the-demo-password

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/demo-config/protection/reveal
Answer the password that opens this application's protected demos, for a member who may configure demos. Ankra keeps each minted password encrypted in its secret store and verifies it against the enforced hash before answering, so the answer always opens the current previews. The response is not cacheable. 409 demo_not_protected when the demos have no password; 409 demo_password_not_retrievable when the password was set before Ankra kept preview passwords (rotate it to get one that can be read); 503 secret_store_unavailable when the platform runs without a secret store. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read the organisation's application CI settings
Source: https://docs.ankra.ai/api-reference/applications/read-the-organisations-application-ci-settings

https://platform.ankra.app/openapi.json get /api/v1/org/applications/settings
Read the organisation's application CI settings: the GitHub Actions runner label every pipeline Ankra generates runs on, and the setup pull-request auto-merge opt-in. An organisation that has never chosen a runner reads the default (ubuntu-latest) with is_default true, which is what its existing pipelines already carry; auto_merge_setup_pull_requests defaults to false. Readable by any member. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Reconcile an application
Source: https://docs.ankra.ai/api-reference/applications/reconcile-an-application

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/reconcile
Hands the application back to the platform reconciler; an application whose analysis failed is reset so it is analysed again. Requires `applications.deploy`, and answers 422 with a message when the application cannot be reconciled.

# Remove an application deployment from one cluster
Source: https://docs.ankra.ai/api-reference/applications/remove-an-application-deployment-from-one-cluster

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/deployments/remove
Remove one deployment of this application: take it off one cluster and namespace while the application and its other deployments stay. The installation is marked removing and the same undeploy job an application delete enqueues per installation is enqueued for it; the job removes the deploy stack it can prove belongs to this application (shared operators are kept) and deletes the installation once the cluster has it. The application, its env secrets, images and pipeline history are kept. While the removal runs, a deploy to the same cluster and namespace is refused with 409. Held to the applications.deploy permission. Bearer personal access token; the CLI twin of the browser route (no CSRF header).

# Remove an application deployment from one cluster (browser session)
Source: https://docs.ankra.ai/api-reference/applications/remove-an-application-deployment-from-one-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/deployments/remove
Remove one deployment of this application: take it off one cluster and namespace while the application and its other deployments stay. The installation is marked removing and the same undeploy job an application delete enqueues per installation is enqueued for it; the job removes the deploy stack it can prove belongs to this application (shared operators are kept) and deletes the installation once the cluster has it. The application, its env secrets, images and pipeline history are kept. While the removal runs, a deploy to the same cluster and namespace is refused with 409. Held to the applications.deploy permission. Browser session authentication with the X-Ankra-CSRF double-submit header; the bearer twin is POST /api/v1/org/applications/{application_id}/deployments/remove.

# Rename an application environment
Source: https://docs.ankra.ai/api-reference/applications/rename-an-application-environment

https://platform.ankra.app/openapi.json patch /api/v1/org/applications/{application_id}/environments/{environment_id}
Renames one named environment of the application. Only the name changes: its identity, role, order and deployments stay as they are, and the change is audited. An environment still named after its cluster cannot be renamed yet (409 environment_named_after_cluster). Held to the applications.write permission. Bearer personal access token; the CLI twin of the browser route (no CSRF header).

# Rename an application environment (browser session)
Source: https://docs.ankra.ai/api-reference/applications/rename-an-application-environment-browser-session

https://platform.ankra.app/openapi.json patch /org/applications/{application_id}/environments/{environment_id}
Renames one named environment of the application. Only the name changes: its identity, role, order and deployments stay as they are, and the change is audited. An environment still named after its cluster cannot be renamed yet (409 environment_named_after_cluster). Held to the applications.write permission.

# Reset an application's AI configuration
Source: https://docs.ankra.ai/api-reference/applications/reset-an-applications-ai-configuration

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}/ai-config
Drop this application's AI lane overrides entirely so every lane follows the organisation default again, and answer with the resolved configuration. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF header).

# Restore the shared default in one environment
Source: https://docs.ankra.ai/api-reference/applications/restore-the-shared-default-in-one-environment

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/env-secrets/{secret_key}/inherit
Remove only this environment override or suppression. Its next apply or deployment consumes the shared default if one exists. Secret values are never returned.

# Restore the shared default in one environment (browser session)
Source: https://docs.ankra.ai/api-reference/applications/restore-the-shared-default-in-one-environment-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/env-secrets/{secret_key}/inherit
Remove only this environment override or suppression. Its next apply or deployment consumes the shared default if one exists. Secret values are never returned.

# Resume Ankra for an application
Source: https://docs.ankra.ai/api-reference/applications/resume-ankra-for-an-application

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}/autonomy-pause
Lifts the application's pause, so what Ankra does unasked on its placements runs again under the application's own autonomy setting. Resuming an application that is not paused changes nothing and answers its current state. Each change is audited with who made it and the pause it lifted. Requires applications.write.

# Resume Ankra for an application (browser session)
Source: https://docs.ankra.ai/api-reference/applications/resume-ankra-for-an-application-browser-session

https://platform.ankra.app/openapi.json delete /org/applications/{application_id}/autonomy-pause
Lifts the application's pause, so what Ankra does unasked on its placements runs again under the application's own autonomy setting. Resuming an application that is not paused changes nothing and answers its current state. Each change is audited with who made it and the pause it lifted. Requires applications.write.

# Retry an application
Source: https://docs.ankra.ai/api-reference/applications/retry-an-application

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/retry
Re-runs the repository analysis of an application that is up. Requires `applications.deploy`, and answers 422 when the application is not in a retryable state or already has an active job.

# Retry the fix-build mission for a failed pipeline run
Source: https://docs.ankra.ai/api-reference/applications/retry-the-fix-build-mission-for-a-failed-pipeline-run

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/fix-build
Dispatch the fix-build mission for one failed Ankra Pipelines run of the application again: the same mission, evidence and checks the automatic fix loop uses (a setup pull request or pull request run commits the fix to its own branch, a tracked-branch run opens a pull request). Use it after a fix mission ended without the fix. While a fix-build mission for the run's branch is still running nothing new is dispatched and the answer names that mission (outcome already_running). A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Revise an application's proposed setup contract
Source: https://docs.ankra.ai/api-reference/applications/revise-an-applications-proposed-setup-contract

https://platform.ankra.app/openapi.json patch /org/applications/{application_id}/setup-contract
Change named defaults on the application's deploy option contract. The revised .ankra/ankra.yaml is committed to the setup branch and the stored parameters are reprojected from it; nothing is deployed. The revision is all-or-nothing: any refused member leaves the proposal exactly as it was. Every answered request is a 200 whose outcome the client must switch on - a refusal carries its reasons in refusals rather than as an empty changes list.

# Revoke a Launch Plan approval
Source: https://docs.ankra.ai/api-reference/applications/revoke-a-launch-plan-approval

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/launch-plan/approvals/{approval_id}/revoke
Ends a plan-level approval before its expiry; nothing more can be claimed under it. Revoking a revoked approval changes nothing. Requires applications.write. Audited.

# Revoke a Launch Plan approval (browser session)
Source: https://docs.ankra.ai/api-reference/applications/revoke-a-launch-plan-approval-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/launch-plan/approvals/{approval_id}/revoke
Ends a plan-level approval before its expiry; nothing more can be claimed under it. Revoking a revoked approval changes nothing. Requires applications.write. Audited.

# Revoke the application's registry robot
Source: https://docs.ankra.ai/api-reference/applications/revoke-the-applications-registry-robot

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}/registry-robot
Delete the push robot Ankra minted for this application from its registry, drop the credential holding its login, and forget the record. The repository's Actions secrets are left holding a login that no longer works, which is the point of a revoke. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Roll an application deploy back
Source: https://docs.ankra.ai/api-reference/applications/roll-an-application-deploy-back

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/rollbacks
Put a previously published image back on this application's deployment. The tag is confirmed present in the registry first, the push-to-deploy watermark is moved onto the newest observed build so the convergence loop does not undo the rollback, and the tag is then written through the same narrow path a push-triggered deploy uses. Held to the applications.deploy permission; a scoped token must carry the applications.deploy scope. Bearer personal access token; the CLI twin of the browser route (no CSRF header).

# Roll an application deploy back (browser session)
Source: https://docs.ankra.ai/api-reference/applications/roll-an-application-deploy-back-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/rollbacks
Put a previously published image back on this application's deployment. The tag is confirmed present in the registry first, the push-to-deploy watermark is moved onto the newest observed build so the convergence loop does not undo the rollback, and the tag is then written through the same narrow path a push-triggered deploy uses. Held to the applications.deploy permission. Browser session authentication with the X-Ankra-CSRF double-submit header; the bearer twin is POST /api/v1/org/applications/{application_id}/rollbacks.

# Roll back a data migration
Source: https://docs.ankra.ai/api-reference/applications/roll-back-a-data-migration

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/launch-plan/data-migration/runs/{run_id}/rollback
Asks a data migration to roll back: the pre-cutover environment goes back and every vendor source is made writable again. The request is recorded and the next pass applies it. Refused before the cutover has started, once the rollback window has closed, for a finished run, and while a rollback is requested or running. Nothing at a vendor is deleted. Requires applications.write at the route and applications.deploy on the run's cluster. Audited.

# Roll back a data migration (browser session)
Source: https://docs.ankra.ai/api-reference/applications/roll-back-a-data-migration-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/launch-plan/data-migration/runs/{run_id}/rollback
Asks a data migration to roll back: the pre-cutover environment goes back and every vendor source is made writable again. The request is recorded and the next pass applies it. Refused before the cutover has started, once the rollback window has closed, for a finished run, and while a rollback is requested or running. Nothing at a vendor is deleted. Requires applications.write at the route and applications.deploy on the run's cluster. Audited.

# Rotate the demo password
Source: https://docs.ankra.ai/api-reference/applications/rotate-the-demo-password

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/demo-config/protection/rotate
Mint a new password for this application's protected demos and answer it. Ankra keeps it encrypted in its secret store, so it can be read again through POST demo-config/protection/reveal; running demos keep the previous password until their next redeploy (a pull request push redeploys its preview). 400 when the application's demos are not protected: turn protection on through PUT demo-config first, which mints the first password.

# Set an application environment secret
Source: https://docs.ankra.ai/api-reference/applications/set-an-application-environment-secret

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/env-secrets/{secret_key}
Store the value of one environment secret, creating the entry or rotating it in place. The value goes to the platform secret store; the deploy renders it into the <app>-env Secret, encrypted with SOPS to the organisation's age recipient before it is stored or pushed to Git. The value is not echoed in the response and is never logged. Takes effect on the application's next deploy. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# Set an application environment secret (browser session)
Source: https://docs.ankra.ai/api-reference/applications/set-an-application-environment-secret-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/env-secrets/{secret_key}
Store the value of one environment secret, creating the entry or rotating it in place. The value goes to the platform secret store; the deploy renders it into the <app>-env Secret, encrypted with SOPS to the organisation's age recipient before it is stored or pushed to Git. The value is not echoed in the response and is never logged. Takes effect on the application's next deploy. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). With environment_id, resolve or modify only that environment; deletion suppresses a shared default locally, and apply never changes another target. Without it, existing shared catalogue behaviour is retained; all-target apply still preserves environment overrides.

# Set an application's automatic build fixing setting
Source: https://docs.ankra.ai/api-reference/applications/set-an-applications-automatic-build-fixing-setting

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/auto-fix-builds
Turn automatic build fixing off or back on for this application. The flag is read fresh on every failed build, so opting out needs no redeploy; turning it back on restores the default. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Set an application's automatic build fixing setting (browser session)
Source: https://docs.ankra.ai/api-reference/applications/set-an-applications-automatic-build-fixing-setting-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/auto-fix-builds
Turn automatic build fixing off or back on for this application. The flag is read fresh on every failed build, so opting out needs no redeploy; turning it back on restores the default.

# Set an application's push-to-deploy setting
Source: https://docs.ankra.ai/api-reference/applications/set-an-applications-push-to-deploy-setting

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/auto-deploy
Turn push-to-deploy on or off for this application. Enabling records the build currently observed as every installation's baseline, so switching it on is not itself a deploy: only a build newer than that one is rolled out. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header). Stored environment IDs scope the write to their active installations across targets. A legacy cluster ID is accepted only when it names one complete environment. No installation identity is assigned by this operation.

# Set an application's push-to-deploy setting (browser session)
Source: https://docs.ankra.ai/api-reference/applications/set-an-applications-push-to-deploy-setting-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/auto-deploy
Turn push-to-deploy on or off for this application. Enabling records the build currently observed as every installation's baseline, so switching it on is not itself a deploy: only a build newer than that one is rolled out. Stored environment IDs scope the write to their active installations across targets. A legacy cluster ID is accepted only when it names one complete environment. No installation identity is assigned by this operation.

# Set an application's setup pull request auto-merge setting
Source: https://docs.ankra.ai/api-reference/applications/set-an-applications-setup-pull-request-auto-merge-setting

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/auto-merge-setup-pull-requests
Set whether Ankra may merge this application's setup pull requests on its own: true or false is the application's own answer and wins over its organisation's setting either way, and null clears it so the application follows its organisation again. Read fresh on every merge decision, so it needs no redeploy. Organisation administrators only. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Set an application's setup pull request auto-merge setting (browser session)
Source: https://docs.ankra.ai/api-reference/applications/set-an-applications-setup-pull-request-auto-merge-setting-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/auto-merge-setup-pull-requests
Set whether Ankra may merge this application's setup pull requests on its own: true or false is the application's own answer and wins over its organisation's setting either way, and null clears it so the application follows its organisation again. Read fresh on every merge decision, so it needs no redeploy. Organisation administrators only.

# Set the organisation's CI runner label
Source: https://docs.ankra.ai/api-reference/applications/set-the-organisations-ci-runner-label

https://platform.ankra.app/openapi.json put /api/v1/org/applications/settings
Set the organisation's application CI settings. Organisation admins only. ci_runner_label is the GitHub Actions runner label generated pipelines run on, validated rather than accepted as free text: one label of at most 64 characters, starting and ending with a letter or digit, containing only letters, digits, '-', '_' and '.' (for example ubuntu-latest, depot-ubuntu-24.04, self-hosted). Anything else answers 400 - a label outside that grammar produces a workflow GitHub cannot parse or run, and the generators concatenate it into a YAML scalar. An explicit null clears the choice and puts every future generation back on the default. auto_merge_setup_pull_requests opts the organisation into the platform merging an application's setup pull request itself once the PR's checks pass (squash; branch protection is honoured, never forced). Each member only moves when named: an absent member leaves the stored value untouched, and a body naming neither answers 422. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Set who runs an application
Source: https://docs.ankra.ai/api-reference/applications/set-who-runs-an-application

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/autonomy
Store the application's own "who runs it" layer: a level for every area, per-area levels and limits. It replaces the stored layer. Anyone who may write the application may set anything within what the organisation allows; asking for more needs an organisation admin and is stored as widened_by_admin. Every write is audited.

# Set who runs an application (browser session)
Source: https://docs.ankra.ai/api-reference/applications/set-who-runs-an-application-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/autonomy
Store the application's own "who runs it" layer: a level for every area, per-area levels and limits. It replaces the stored layer. Anyone who may write the application may set anything within what the organisation allows; asking for more needs an organisation admin and is stored as widened_by_admin. Every write is audited.

# Set who runs an environment
Source: https://docs.ankra.ai/api-reference/applications/set-who-runs-an-environment

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/environments/{environment_id}/autonomy
Store one environment's "who runs it" layer, which applies over the application's. It replaces the stored layer and follows the same rule: more than the environment inherits needs an organisation admin. Every write is audited.

# Set who runs an environment (browser session)
Source: https://docs.ankra.ai/api-reference/applications/set-who-runs-an-environment-browser-session

https://platform.ankra.app/openapi.json put /org/applications/{application_id}/environments/{environment_id}/autonomy
Store one environment's "who runs it" layer, which applies over the application's. It replaces the stored layer and follows the same rule: more than the environment inherits needs an organisation admin. Every write is audited.

# Show which GitHub credential the application's repository calls ride on
Source: https://docs.ankra.ai/api-reference/applications/show-which-github-credential-the-applications-repository-calls-ride-on

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/repository-credential
The GitHub credential the application names, and whether it resolves to a GitHub App installation Ankra can mint a token for. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Start a Launch Plan data migration
Source: https://docs.ankra.ai/api-reference/applications/start-a-launch-plan-data-migration

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/launch-plan/data-migration/runs
Starts the data migration a plan-level approval covers (ankra-bjkszh.15): moves the application's data off the vendors the approval selected, through the backup vault it named, to the in-cluster servers in targets, and flips the variables in environment at the cutover. Starting claims every data-migration action of the plan under the approval in one transaction, through the same gate a single claim passes, so it is refused unless the approval is the caller's own, unexpired, unrevoked, still bound to the live plan, lists every data-migration action, and the caller still holds each action's permission. The environment values go to the secret store only and are never answered. One data migration is in flight per application. Requires applications.write. Audited, refusals included.

# Start a Launch Plan data migration (browser session)
Source: https://docs.ankra.ai/api-reference/applications/start-a-launch-plan-data-migration-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/launch-plan/data-migration/runs
Starts the data migration a plan-level approval covers (ankra-bjkszh.15): moves the application's data off the vendors the approval selected, through the backup vault it named, to the in-cluster servers in targets, and flips the variables in environment at the cutover. Starting claims every data-migration action of the plan under the approval in one transaction, through the same gate a single claim passes, so it is refused unless the approval is the caller's own, unexpired, unrevoked, still bound to the live plan, lists every data-migration action, and the caller still holds each action's permission. The environment values go to the secret store only and are never answered. One data migration is in flight per application. Requires applications.write. Audited, refusals included.

# Start or resume an application deploy run
Source: https://docs.ankra.ai/api-reference/applications/start-or-resume-an-application-deploy-run

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/deploy-runs
Hand the deploy wizard's whole ordered multi-stack deploy to the server. The run is persisted before anything is created - roles, drafts, and the stack name derived for each - and the maintenance supervisor creates each stack in turn, waiting for every stack that has another behind it to report up. Closing the browser tab no longer strands the remaining stacks. A request made while a run for the same application and cluster is already in flight joins that run and answers with resumed=true rather than starting a rival queue. Browser session authentication with the X-Ankra-CSRF double-submit header only (no bearer twin).

# Stop an application demo
Source: https://docs.ankra.ai/api-reference/applications/stop-an-application-demo

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}/demos/{workspace_id}
Stop a demo and tear its namespace down. A malformed workspace_id is reported as the same 404 as an unknown demo. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Update an application's AI configuration
Source: https://docs.ankra.ai/api-reference/applications/update-an-applications-ai-configuration

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/ai-config
Patch this application's AI lane overrides and answer with the freshly resolved configuration. Lanes the body does not mention are left untouched. A lane sent with override false is removed from the application's override so it follows the organisation again; a lane sent with override true stores whichever of enabled and settings the body carries. Overrides are stored on the ai-gateway's per-repository binding profile, the same rows that gate the webhook events. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF header).

# Update an application's demo configuration
Source: https://docs.ankra.ai/api-reference/applications/update-an-applications-demo-configuration

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/demo-config
Replace the application's saved demo defaults. env and database are replaced wholesale on every PUT. The stack_profile and base_stack blocks are written only when their key is present in the body: an absent key preserves the stored designation, an explicit null clears it, so a client that predates either block cannot silently drop a demo's dependencies. Secret environment values are submitted and echoed as ${SECRET_SLOT:<uuid>} sentinels. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication plus the X-Ankra-CSRF double-submit header).

# Wake an application deployment
Source: https://docs.ankra.ai/api-reference/applications/wake-an-application-deployment

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/deployments/wake
Wake a parked deployment of this application: restore the remembered replica count (parked_replicas, or the descriptor default when none was pinned), remove the park marker, and enqueue the platform's existing deploy job to apply it. Refused with 409 when the deployment is not parked. Held to the applications.deploy permission. Browser session authentication with the X-Ankra-CSRF double-submit header only (no bearer twin).

# Connect Avura
Source: https://docs.ankra.ai/api-reference/avura/connect-avura

https://platform.ankra.app/openapi.json put /api/v1/org/avura/connection
Store or rotate the platform service token an Avura organization minted for Ankra Platform. The token is verified against base_url before anything is stored. Requires an organisation admin.

# Create Avura DNS Record
Source: https://docs.ankra.ai/api-reference/avura/create-avura-dns-record

https://platform.ankra.app/openapi.json post /api/v1/org/avura/domains/{domain_id}/records
Creates a DNS record in a shared Avura domain and answers 201 with it. `record_type` is one of A, AAAA, CAA, CNAME, MX, NS, SRV or TXT; `ttl` is optional (60-604800 seconds). Requires an org admin.

# Delete Avura DNS Record
Source: https://docs.ankra.ai/api-reference/avura/delete-avura-dns-record

https://platform.ankra.app/openapi.json delete /api/v1/org/avura/domains/{domain_id}/records/{record_id}
Deletes a record from a shared Avura domain and answers 204. The record must belong to that domain. Requires an org admin.

# Disconnect Avura
Source: https://docs.ankra.ai/api-reference/avura/disconnect-avura

https://platform.ankra.app/openapi.json delete /api/v1/org/avura/connection
Remove the linked Avura organization. Refused with 409 while custom DNS zones use the connection.

# Get Avura Connection
Source: https://docs.ankra.ai/api-reference/avura/get-avura-connection

https://platform.ankra.app/openapi.json get /api/v1/org/avura/connection
The linked Avura organization and a live count of the domains it shared with Ankra Platform. connected is false when none is linked; zone_count is null when Avura could not be asked.

# List Avura DNS Records
Source: https://docs.ankra.ai/api-reference/avura/list-avura-dns-records

https://platform.ankra.app/openapi.json get /api/v1/org/avura/domains/{domain_id}/records
Lists the DNS records of one shared Avura domain. The domain must be one the connected Avura workspace shares; any other id answers 404.

# List Avura Domains
Source: https://docs.ankra.ai/api-reference/avura/list-avura-domains

https://platform.ankra.app/openapi.json get /api/v1/org/avura/domains
Lists the domains the organisation's connected Avura workspace shares with Ankra (the ones opted in with Use with Ankra Platform), read live through the org's `avura` credential.

# Update Avura DNS Record
Source: https://docs.ankra.ai/api-reference/avura/update-avura-dns-record

https://platform.ankra.app/openapi.json patch /api/v1/org/avura/domains/{domain_id}/records/{record_id}
Updates the content and, optionally, the TTL of a record in a shared Avura domain. The record must belong to that domain. Requires an org admin.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/aws-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/vms
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Add a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/add-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/vms
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Add node group
Source: https://docs.ankra.ai/api-reference/aws-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/node-groups
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Add node group (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/add-node-group-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/node-groups
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/aws-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Check Kubernetes upgrade readiness (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/check-kubernetes-upgrade-readiness-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Create an AWS EC2 cluster
Source: https://docs.ankra.ai/api-reference/aws-clusters/create-an-aws-ec2-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws
Bearer PAT authentication; RBAC permission `clusters.create`. Creates a self-managed k3s / kubeadm cluster on EC2 (ADR 0015), in a VPC Ankra creates when `vpc_id` is omitted (from `network_ip_range` over `availability_zones`, NAT-gateway egress by default) or in the customer's VPC when `vpc_id`, `node_subnet_ids` and `bastion_subnet_id` are given. The preflight runs first and the first error item is the refusal. Defaults: t3.medium nodes, a t3.small bastion, Ubuntu 24.04 on amd64, a 40 GiB encrypted gp3 root volume, one control plane and one worker, Cilium for either distribution, 10.0.0.0/16 for a created VPC over one zone (three when `control_plane_count` >= 3). `egress_mode` omitted is `nat_gateway` for a created VPC and, for an adopted one, resolved by preflight (`existing` when every node subnet already has egress, `bastion_nat` when none has and none carries a foreign instance). Flannel is accepted but cannot enforce the IMDS guard, so the preflight reports a warning for it; the AWS cloud-controller-manager is always installed. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Create an AWS EC2 cluster (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/create-an-aws-ec2-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws
Browser session authentication; RBAC permission `clusters.create`. Creates a self-managed k3s / kubeadm cluster on EC2 (ADR 0015), in a VPC Ankra creates when `vpc_id` is omitted (from `network_ip_range` over `availability_zones`, NAT-gateway egress by default) or in the customer's VPC when `vpc_id`, `node_subnet_ids` and `bastion_subnet_id` are given. The preflight runs first and the first error item is the refusal. Defaults: t3.medium nodes, a t3.small bastion, Ubuntu 24.04 on amd64, a 40 GiB encrypted gp3 root volume, one control plane and one worker, Cilium for either distribution, 10.0.0.0/16 for a created VPC over one zone (three when `control_plane_count` >= 3). `egress_mode` omitted is `nat_gateway` for a created VPC and, for an adopted one, resolved by preflight (`existing` when every node subnet already has egress, `bastion_nat` when none has and none carries a foreign instance). Flannel is accepted but cannot enforce the IMDS guard, so the preflight reports a warning for it; the AWS cloud-controller-manager is always installed. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/aws-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/aws/{cluster_id}/vms/{vm_id}
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/delete-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/aws/{cluster_id}/vms/{vm_id}
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete node group
Source: https://docs.ankra.ai/api-reference/aws-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}
Bearer PAT authentication; RBAC permission `clusters.delete`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Delete node group (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/delete-node-group-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/aws/{cluster_id}/node-groups/{group_name}
Browser session authentication; RBAC permission `clusters.delete`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Deprovision an AWS EC2 cluster
Source: https://docs.ankra.ai/api-reference/aws-clusters/deprovision-an-aws-ec2-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/aws/{cluster_id}
Bearer PAT authentication; RBAC permission `clusters.delete`. Ordered teardown preserves explicitly retained storage and reports orphaned provider IDs. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Deprovision an AWS EC2 cluster (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/deprovision-an-aws-ec2-cluster-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/aws/{cluster_id}
Browser session authentication; RBAC permission `clusters.delete`. Ordered teardown preserves explicitly retained storage and reports orphaned provider IDs. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/aws-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Diagnose bastion (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/diagnose-bastion-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/bastion/diagnose
Browser session authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/aws-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `aws_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get AWS cluster quotas
Source: https://docs.ankra.ai/api-reference/aws-clusters/get-aws-cluster-quotas

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/quotas
Bearer PAT authentication; RBAC permission `clusters.read`. Quota reporting is not implemented for self-managed AWS clusters yet: the route answers 404 with a detail saying so. Documented so the shape is stable once the vCPU / elastic-IP report ships. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Get AWS cluster quotas (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/get-aws-cluster-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/quotas
Browser session authentication; RBAC permission `clusters.read`. Quota reporting is not implemented for self-managed AWS clusters yet: the route answers 404 with a detail saying so. Documented so the shape is stable once the vCPU / elastic-IP report ships. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Get AWS pricing
Source: https://docs.ankra.ai/api-reference/aws-clusters/get-aws-pricing

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/pricing
Bearer PAT authentication; RBAC permission `clusters.read`. Instance-type on-demand prices plus the encrypted gp3 root-volume price, with explicit incomplete-pricing reasons. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Get AWS pricing (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/get-aws-pricing-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/pricing
Browser session authentication; RBAC permission `clusters.read`. Instance-type on-demand prices plus the encrypted gp3 root-volume price, with explicit incomplete-pricing reasons. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/aws-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Get bastion health (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/get-bastion-health-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/bastion/health
Browser session authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Latest restorable state snapshot of a AWS cluster
Source: https://docs.ankra.ai/api-reference/aws-clusters/latest-restorable-state-snapshot-of-a-aws-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the AWS cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List AWS availability zones
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-availability-zones

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/availability-zones
Bearer PAT authentication; RBAC permission `clusters.read`. Lists the region's availability zones. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS availability zones (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-availability-zones-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/availability-zones
Browser session authentication; RBAC permission `clusters.read`. Lists the region's availability zones. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS instance types
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-instance-types

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/instance-types
Bearer PAT authentication; RBAC permission `clusters.read`. Lists the amd64 instance types offered in the region with on-demand prices; a nil price is unknown, never free, and `pricing_complete` says whether every type was priced. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS instance types (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-instance-types-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/instance-types
Browser session authentication; RBAC permission `clusters.read`. Lists the amd64 instance types offered in the region with on-demand prices; a nil price is unknown, never free, and `pricing_complete` says whether every type was priced. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS regions
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-regions

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/regions
Bearer PAT authentication; RBAC permission `clusters.read`. Lists the regions enabled for the credential's account. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS regions (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-regions-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/regions
Browser session authentication; RBAC permission `clusters.read`. Lists the regions enabled for the credential's account. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS subnets
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-subnets

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/subnets
Bearer PAT authentication; RBAC permission `clusters.read`. Lists a VPC's subnets with each one's IPv4 default-route classification and the count of instances Ankra did not create; both are three-state and never collapse a failed read into a verdict. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS subnets (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-subnets-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/subnets
Browser session authentication; RBAC permission `clusters.read`. Lists a VPC's subnets with each one's IPv4 default-route classification and the count of instances Ankra did not create; both are three-state and never collapse a failed read into a verdict. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS Ubuntu images
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-ubuntu-images

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/images
Bearer PAT authentication; RBAC permission `clusters.read`. Lists the Ubuntu series whose Canonical AMI parameter resolves in the region and the architectures offered (amd64 only until the image catalogue is arm64-audited). Answers 503 rather than an empty list when no series could be resolved. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS Ubuntu images (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-ubuntu-images-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/images
Browser session authentication; RBAC permission `clusters.read`. Lists the Ubuntu series whose Canonical AMI parameter resolves in the region and the architectures offered (amd64 only until the image catalogue is arm64-audited). Answers 503 rather than an empty list when no series could be resolved. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS VPCs
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-vpcs

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/vpcs
Bearer PAT authentication; RBAC permission `clusters.read`. Lists the region's VPCs with their CIDR and DHCP domain-name state (set / empty / unknown). Answers 404 while the organisation's `aws_provider` feature flag is off.

# List AWS VPCs (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-aws-vpcs-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/vpcs
Browser session authentication; RBAC permission `clusters.read`. Lists the region's VPCs with their CIDR and DHCP domain-name state (set / empty / unknown). Answers 404 while the organisation's `aws_provider` feature flag is off.

# List instance types for an AWS cluster
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-instance-types-for-an-aws-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/instance-types
Bearer PAT authentication; RBAC permission `clusters.read`. The instance-type catalog in the cluster's own region and credential. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List instance types for an AWS cluster (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-instance-types-for-an-aws-cluster-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/instance-types
Browser session authentication; RBAC permission `clusters.read`. The instance-type catalog in the cluster's own region and credential. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List node groups
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/node-groups
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List node groups (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-node-groups-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/node-groups
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List nodes
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/nodes
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List nodes (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-nodes-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/nodes
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/vms
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# List standalone VMs (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/list-standalone-vms-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/vms
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Preflight an AWS EC2 cluster create
Source: https://docs.ankra.ai/api-reference/aws-clusters/preflight-an-aws-ec2-cluster-create

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/preflight
Bearer PAT authentication; RBAC permission `clusters.create`. Runs every check the create runs against AWS without creating anything. Each item is three-state: `ok`, `warning` (a read Ankra could not perform, or a caveat such as flannel not enforcing the IMDS guard), or `error`. `network_ownership` says which shape the request describes; a created network is checked for its CIDR plan (`cidr`), its zones (`zones` - chosen here when the request names none), the VPC, NAT-gateway and elastic-IP quotas, while an adopted VPC is checked for its VPC, subnets, egress routes and bastion subnet. `resolved_egress_mode` is the mode the create will run under, null when it could not be decided; `resolved_availability_zones` the zones the cluster will spread over. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Preflight an AWS EC2 cluster create (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/preflight-an-aws-ec2-cluster-create-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/preflight
Browser session authentication; RBAC permission `clusters.create`. Runs every check the create runs against AWS without creating anything. Each item is three-state: `ok`, `warning` (a read Ankra could not perform, or a caveat such as flannel not enforcing the IMDS guard), or `error`. `network_ownership` says which shape the request describes; a created network is checked for its CIDR plan (`cidr`), its zones (`zones` - chosen here when the request names none), the VPC, NAT-gateway and elastic-IP quotas, while an adopted VPC is checked for its VPC, subnets, egress routes and bastion subnet. `resolved_egress_mode` is the mode the create will run under, null when it could not be decided; `resolved_availability_zones` the zones the cluster will spread over. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/control-plane
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read control-plane sizing (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-control-plane-sizing-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/control-plane
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read Kubernetes version
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/k8s-version
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read Kubernetes version (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-kubernetes-version-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/k8s-version
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/nodes/{node_id}
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-node-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/nodes/{node_id}
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `aws_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node-group autoscaling
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-node-group-autoscaling

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}/autoscaling
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read node-group autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-node-group-autoscaling-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/node-groups/{group_name}/autoscaling
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/access-info
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read private cluster access (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-private-cluster-access-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/access-info
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/ssh-keys
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-ssh-keys-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/ssh-keys
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read worker count
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/worker-count
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Read worker count (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/read-worker-count-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/aws/{cluster_id}/worker-count
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/vms/{vm_id}/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/vms/{vm_id}/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/control-plane/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize control-plane nodes (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-control-plane-nodes-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/control-plane/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize node group
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize node group (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-node-group-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/node-groups/{group_name}/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize the public gateway
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-the-public-gateway

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/bastion/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resize the public gateway (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/resize-the-public-gateway-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/bastion/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Restart node
Source: https://docs.ankra.ai/api-reference/aws-clusters/restart-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/nodes/{node_id}/restart
Bearer PAT authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Restart node (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/restart-node-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/nodes/{node_id}/restart
Browser session authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/aws-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/ssh-keys/resync
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Resync SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/resync-ssh-keys-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/ssh-keys/resync
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale node group
Source: https://docs.ankra.ai/api-reference/aws-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}/scale
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale node group (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/scale-node-group-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/node-groups/{group_name}/scale
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale workers
Source: https://docs.ankra.ai/api-reference/aws-clusters/scale-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/scale-workers
Bearer PAT authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Scale workers (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/scale-workers-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/scale-workers
Browser session authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Start a stopped cluster
Source: https://docs.ankra.ai/api-reference/aws-clusters/start-a-stopped-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/start
Bearer PAT authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Start a stopped cluster (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/start-a-stopped-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/start
Browser session authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Stop a cluster
Source: https://docs.ankra.ai/api-reference/aws-clusters/stop-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/stop
Bearer PAT authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Stop a cluster (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/stop-a-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/stop
Browser session authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# The persistent volumes deleting an AWS cluster removes
Source: https://docs.ankra.ai/api-reference/aws-clusters/the-persistent-volumes-deleting-an-aws-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/aws/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/aws/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/control-plane
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update control-plane count (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-control-plane-count-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/control-plane
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group autoscaling
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-node-group-autoscaling

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}/autoscaling
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-node-group-autoscaling-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/node-groups/{group_name}/autoscaling
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}/labels
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group labels (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-node-group-labels-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/node-groups/{group_name}/labels
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/node-groups/{group_name}/taints
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update node-group taints (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-node-group-taints-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/node-groups/{group_name}/taints
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/aws/{cluster_id}/ssh-keys
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Update SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/update-ssh-keys-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/aws/{cluster_id}/ssh-keys
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Upgrade the Kubernetes version
Source: https://docs.ankra.ai/api-reference/aws-clusters/upgrade-the-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/aws/{cluster_id}/upgrade-k8s-version
Bearer PAT authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Upgrade the Kubernetes version (browser session)
Source: https://docs.ankra.ai/api-reference/aws-clusters/upgrade-the-kubernetes-version-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/aws/{cluster_id}/upgrade-k8s-version
Browser session authentication; RBAC permission `clusters.operate`. Answers 404 while the organisation's `aws_provider` feature flag is off.

# Create an AWS access-key credential
Source: https://docs.ankra.ai/api-reference/aws-credentials/create-an-aws-access-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/aws/keys
Bearer PAT authentication. Registers an access-key credential after an STS GetCallerIdentity check; a name clash answers 409, a failed check 400.

# Create an AWS access-key credential (browser session)
Source: https://docs.ankra.ai/api-reference/aws-credentials/create-an-aws-access-key-credential-browser-session

https://platform.ankra.app/openapi.json post /org/credentials/aws/keys
Browser session authentication. Registers an access-key credential after an STS GetCallerIdentity check; a name clash answers 409, a failed check 400.

# Create an AWS role credential
Source: https://docs.ankra.ai/api-reference/aws-credentials/create-an-aws-role-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/aws/role
Bearer PAT authentication. Registers an STS role credential after assuming it. A `self_managed` scope is additionally proven against EC2 (a DryRun DescribeVpcs) and the Canonical Ubuntu AMI SSM parameters; unknown scopes answer 400, a name clash 409, a failed connection test 400.

# Create an AWS role credential (browser session)
Source: https://docs.ankra.ai/api-reference/aws-credentials/create-an-aws-role-credential-browser-session

https://platform.ankra.app/openapi.json post /org/credentials/aws/role
Browser session authentication. Registers an STS role credential after assuming it. A `self_managed` scope is additionally proven against EC2 (a DryRun DescribeVpcs) and the Canonical Ubuntu AMI SSM parameters; unknown scopes answer 400, a name clash 409, a failed connection test 400.

# Get AWS onboarding details
Source: https://docs.ankra.ai/api-reference/aws-credentials/get-aws-onboarding-details

https://platform.ankra.app/openapi.json get /api/v1/credentials/aws/onboarding
Bearer PAT authentication. Generates an external ID and the CloudFormation launch-stack URL for the requested scope (`cost`, `provisioning`, or `self_managed` for the AnkraSelfManagedProvisioning role the k3s / kubeadm lane uses). Unknown scopes answer 400.

# Get AWS onboarding details (browser session)
Source: https://docs.ankra.ai/api-reference/aws-credentials/get-aws-onboarding-details-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/aws/onboarding
Browser session authentication. Generates an external ID and the CloudFormation launch-stack URL for the requested scope (`cost`, `provisioning`, or `self_managed` for the AnkraSelfManagedProvisioning role the k3s / kubeadm lane uses). Unknown scopes answer 400.

# Create an Azure credential
Source: https://docs.ankra.ai/api-reference/azure-credentials/create-an-azure-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/azure
Bearer PAT authentication; RBAC permission `credentials.write`. The secret is stored in Vault and connection-tested without echoing key material.

# Create an Azure credential (browser session)
Source: https://docs.ankra.ai/api-reference/azure-credentials/create-an-azure-credential-browser-session

https://platform.ankra.app/openapi.json post /org/credentials/azure
Browser session authentication; RBAC permission `credentials.write`. The secret is stored in Vault and connection-tested without echoing key material.

# Create an SSH key credential
Source: https://docs.ankra.ai/api-reference/azure-credentials/create-an-ssh-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/azure/ssh-key
Creates an SSH key credential from `name` and either `ssh_public_key` or `generate=true`; a generated RSA-4096 key pair's private key is returned once, in this response. A public key the organisation already stores under another credential is refused with 400. Requires `credentials.write`; answers 201.

# Get Azure credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/azure-credentials/get-azure-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/azure/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the Azure API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get Azure credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/azure-credentials/get-azure-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/azure/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the Azure limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# List Azure credentials
Source: https://docs.ankra.ai/api-reference/azure-credentials/list-azure-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/azure
Bearer PAT authentication; RBAC permission `credentials.read`. Returns credential metadata only; the client secret is never returned.

# List Azure credentials (browser session)
Source: https://docs.ankra.ai/api-reference/azure-credentials/list-azure-credentials-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/azure
Browser session authentication; RBAC permission `credentials.read`. Returns credential metadata only; the client secret is never returned.

# List SSH key credentials
Source: https://docs.ankra.ai/api-reference/azure-credentials/list-ssh-key-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/azure/ssh-keys
Lists the organisation's SSH key credentials. The list is the same under every cloud provider. Each item carries the stored public key with the fingerprint (as `ssh-keygen -l` prints it), key type and comment derived from it; a stored value that is not a readable key keeps its row, with a null `fingerprint` and `fingerprint_error` saying why.

# Preview restoring an application deployment
Source: https://docs.ankra.ai/api-reference/backups/preview-restoring-an-application-deployment

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/deployments/{deployment_id}/restore-points/{restore_point_id}/restore-plan
Answers what restoring this deployment in place from this restore point would do if it were confirmed now, without doing any of it: the steps in order with the volume claims they remove, the namespaces whose objects are restored, whether a safety copy of the live stack is taken first, every reason the restore would be refused, and whether the stack has drifted. It opens no run, mints no restore point and writes nothing to the stack. The stack is resolved from the application's own records; a restore point captured from another stack or cluster is not found here. Requires the backups rollout flag and backups.read.

# Preview restoring an application deployment (browser session)
Source: https://docs.ankra.ai/api-reference/backups/preview-restoring-an-application-deployment-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deployments/{deployment_id}/restore-points/{restore_point_id}/restore-plan
Answers what restoring this deployment in place from this restore point would do if it were confirmed now, without doing any of it: the steps in order with the volume claims they remove, the namespaces whose objects are restored, whether a safety copy of the live stack is taken first, every reason the restore would be refused, and whether the stack has drifted. It opens no run, mints no restore point and writes nothing to the stack. The stack is resolved from the application's own records; a restore point captured from another stack or cluster is not found here. Requires the backups rollout flag and backups.read.

# Read one application deployment restore point with its receipt
Source: https://docs.ankra.ai/api-reference/backups/read-one-application-deployment-restore-point-with-its-receipt

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/deployments/{deployment_id}/restore-points/{restore_point_id}
Reads one restore point of one application deployment with its manifest: assets with their measured sizes and per-artifact size and SHA-256 checksums, coverage, what was not carried, and the run that produced it. The stack is resolved from the application's own installation rows; a restore point captured from another stack or cluster is not found here. Requires the backups rollout flag and backups.read. Object keys are never returned. A completed capture is not a verified restore: verification_status is written only by an automated restore verification.

# Read one application deployment restore point with its receipt (browser session)
Source: https://docs.ankra.ai/api-reference/backups/read-one-application-deployment-restore-point-with-its-receipt-browser-session

https://platform.ankra.app/openapi.json get /org/applications/{application_id}/deployments/{deployment_id}/restore-points/{restore_point_id}
Reads one restore point of one application deployment with its manifest: assets with their measured sizes and per-artifact size and SHA-256 checksums, coverage, what was not carried, and the run that produced it. The stack is resolved from the application's own installation rows; a restore point captured from another stack or cluster is not found here. Requires the backups rollout flag and backups.read. Object keys are never returned. A completed capture is not a verified restore: verification_status is written only by an automated restore verification.

# Restore an application deployment from a restore point
Source: https://docs.ankra.ai/api-reference/backups/restore-an-application-deployment-from-a-restore-point

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/deployments/{deployment_id}/restore-points/{restore_point_id}/restore
Restores this deployment in place from one of its own restore points. The cluster and stack are resolved from the deployment on the server, and confirm must be that stack's name. A safety restore point of the live stack is taken first and the restore is refused if it cannot be; the workloads are then scaled down, the claims the restore point replaces are removed, the data is restored and the workloads are scaled back up. A refusal answers with the sentence as detail and a stable error_code. force overrides drift and nothing else. Requires the backups rollout flag and backups.operate.

# Restore an application deployment from a restore point (browser session)
Source: https://docs.ankra.ai/api-reference/backups/restore-an-application-deployment-from-a-restore-point-browser-session

https://platform.ankra.app/openapi.json post /org/applications/{application_id}/deployments/{deployment_id}/restore-points/{restore_point_id}/restore
Restores this deployment in place from one of its own restore points. The cluster and stack are resolved from the deployment on the server, and confirm must be that stack's name. A safety restore point of the live stack is taken first and the restore is refused if it cannot be; the workloads are then scaled down, the claims the restore point replaces are removed, the data is restored and the workloads are scaled back up. A refusal answers with the sentence as detail and a stable error_code. force overrides drift and nothing else. Requires the backups rollout flag and backups.operate.

# Approve usage charges as the organisation owner
Source: https://docs.ankra.ai/api-reference/billing/approve-usage-charges-as-the-organisation-owner

https://platform.ankra.app/openapi.json post /api/v1/org/billing/activation
Requires billing.manage and a live organisation owner assignment. The owner must send accept_charges=true and the exact current terms, and have a verified payment method. The approval, plan switch and audit record commit together. Repeated confirmation is idempotent.

# Approve usage charges as the organisation owner (browser session)
Source: https://docs.ankra.ai/api-reference/billing/approve-usage-charges-as-the-organisation-owner-browser-session

https://platform.ankra.app/openapi.json post /org/billing/activation
Requires billing.manage and a live organisation owner assignment. The owner must send accept_charges=true and the exact current terms, and have a verified payment method. The approval, plan switch and audit record commit together. Repeated confirmation is idempotent.

# Attach an AWS Marketplace subscription to the organisation
Source: https://docs.ankra.ai/api-reference/billing/attach-an-aws-marketplace-subscription-to-the-organisation

https://platform.ankra.app/openapi.json post /api/v1/org/billing/aws-marketplace/link
Requires billing.manage. Consumes the single-use link token the AWS Marketplace registration redirect carried and attaches that license to the caller's organisation. Once AWS confirms the contract, the organisation moves to the plan its contract dimension maps to (startup_vcpu to Startup, enterprise_vcpu to Enterprise), and its usage is collected by AWS Marketplace: worker vCPU above the 30 free and the contracted quantity is metered to AWS hourly. An organisation holds at most one live AWS Marketplace subscription, and one already paying Ankra on a paid plan or by invoice is refused. Repeating the call from the organisation that already holds the license answers the same outcome.

# Read billing, trial allowance and linked Cloud credits
Source: https://docs.ankra.ai/api-reference/billing/read-billing-trial-allowance-and-linked-cloud-credits

https://platform.ankra.app/openapi.json get /api/v1/org/billing/activation
Reads the current organisation only. Requires billing.read. Unknown capacity or Cloud credit observations remain null and saving a card does not authorise paid usage. Once a card is saved, the read grants the welcome credit if the setup webhook has not.

# Read billing, trial allowance and linked Cloud credits (browser session)
Source: https://docs.ankra.ai/api-reference/billing/read-billing-trial-allowance-and-linked-cloud-credits-browser-session

https://platform.ankra.app/openapi.json get /org/billing/activation
Reads the current organisation only. Requires billing.read. Unknown capacity or Cloud credit observations remain null and saving a card does not authorise paid usage. Once a card is saved, the read grants the welcome credit if the setup webhook has not.

# Save a card without approving paid usage
Source: https://docs.ankra.ai/api-reference/billing/save-a-card-without-approving-paid-usage

https://platform.ankra.app/openapi.json post /api/v1/org/billing/activation/setup
Requires billing.manage and CSRF for browser sessions. Creates a Stripe setup checkout and returns to an allowed Platform origin. This operation never selects a paid plan or removes the trial limit.

# Save a card without approving paid usage (browser session)
Source: https://docs.ankra.ai/api-reference/billing/save-a-card-without-approving-paid-usage-browser-session

https://platform.ankra.app/openapi.json post /org/billing/activation/setup
Requires billing.manage and CSRF for browser sessions. Creates a Stripe setup checkout and returns to an allowed Platform origin. This operation never selects a paid plan or removes the trial limit.

# Set or clear the organisation's daily AI caps (a key not sent is kept)
Source: https://docs.ankra.ai/api-reference/billing/set-or-clear-the-organisations-daily-ai-caps-a-key-not-sent-is-kept

https://platform.ankra.app/openapi.json put /api/v1/org/billing/ai-spend-cap
Partially updates the organisation's daily AI caps: a key left out of the body is kept, `null` clears it and a value sets it. Requires `billing.manage`; returns 400 for a non-positive cap or a soft token cap above the hard cap.

# The organisation's daily AI money and token caps with today's spend
Source: https://docs.ankra.ai/api-reference/billing/the-organisations-daily-ai-money-and-token-caps-with-todays-spend

https://platform.ankra.app/openapi.json get /api/v1/org/billing/ai-spend-cap
Returns the organisation's daily AI limits: its own USD chat spend cap with the plan default and effective cap, the soft and hard daily token caps with the budget state, and today's spend and token usage. Past the soft token cap unattended runs degrade to a quicker model tier; past the hard cap new unattended runs are refused until the UTC day resets.

# List canvas datasets
Source: https://docs.ankra.ai/api-reference/canvas-datasets/list-canvas-datasets

https://platform.ankra.app/openapi.json get /api/v1/org/canvas-datasets
Lists the fixed, named datasets a canvas dashboard element can bind to, with the shape each answers and the parameters it takes. The queries behind them are owned by the platform; no query text is ever accepted.

# Query a canvas dataset
Source: https://docs.ankra.ai/api-reference/canvas-datasets/query-a-canvas-dataset

https://platform.ankra.app/openapi.json post /api/v1/org/canvas-datasets/{dataset_id}/query
Runs one dataset for a time range, pinned to the caller's organisation and project, and with compare_previous also for the period of the same length just before it. Series are capped at 20 with at most 1000 points each and tables at 500 rows; truncated says when a cap applied.

# List published canvas pages
Source: https://docs.ankra.ai/api-reference/canvas-pages/list-published-canvas-pages

https://platform.ankra.app/openapi.json get /api/v1/org/canvas-publications
Lists the organisation's published chat canvas pages, newest first, without their content. Pass `next_cursor` back as `cursor` for the next page. Any organisation member can read them.

# Publish a canvas page
Source: https://docs.ankra.ai/api-reference/canvas-pages/publish-a-canvas-page

https://platform.ankra.app/openapi.json post /api/v1/org/canvas-publications
Publishes a chat canvas artifact at a public address on the pages host. The content is sent explicitly, so edited canvases publish as shown. Only `html`, `svg` and `markdown` can be published. The page is a static snapshot served in a sandbox, with a fixed notice naming it as an AI-generated page. Publishing the same `conversation_id` and `artifact_id` again keeps the URL and extends the expiry. A durable canvas is published with `canvas_id` and `revision_id` instead: it has one publication whichever revision is published, the canvas's `published_revision_id` follows it, and a json dashboard revision is published as the html snapshot sent in `content`. Who may publish is the organisation's `public_canvas_publishing` setting (`admins` by default, `members`, or `disabled`); tightening it leaves live pages up. `ttl_hours` defaults to 168 and is capped at 720.

# Unpublish a canvas page
Source: https://docs.ankra.ai/api-reference/canvas-pages/unpublish-a-canvas-page

https://platform.ankra.app/openapi.json delete /api/v1/org/canvas-publications/{publication_id}
Takes a published page down. Its address answers 410 from then on; publishing the artifact again restores it at the same address.

# Create a canvas
Source: https://docs.ankra.ai/api-reference/canvases/create-a-canvas

https://platform.ankra.app/openapi.json post /api/v1/org/canvases
Saves a new canvas with its first revision as the draft. A canvas is private to its creator until shared. Saving a chat artifact names `source_conversation_id` and `source_artifact_id` together; saving the same artifact again returns the canvas it already made (200) instead of creating another.

# Delete a canvas
Source: https://docs.ankra.ai/api-reference/canvases/delete-a-canvas

https://platform.ankra.app/openapi.json delete /api/v1/org/canvases/{canvas_id}
Removes the canvas from the library. Its revisions are purged later. A chat artifact saved as this canvas can be saved again afterwards. Only the owner can delete a canvas.

# Get a canvas
Source: https://docs.ankra.ai/api-reference/canvases/get-a-canvas

https://platform.ankra.app/openapi.json get /api/v1/org/canvases/{canvas_id}
Returns a canvas with the content of its draft revision.

# Get a canvas revision
Source: https://docs.ankra.ai/api-reference/canvases/get-a-canvas-revision

https://platform.ankra.app/openapi.json get /api/v1/org/canvases/{canvas_id}/revisions/{revision_id}
Returns one revision of a canvas with its content.

# List canvas revisions
Source: https://docs.ankra.ai/api-reference/canvases/list-canvas-revisions

https://platform.ankra.app/openapi.json get /api/v1/org/canvases/{canvas_id}/revisions
Lists a canvas's revisions newest first, without content. Pass `next_cursor` back as `cursor` for the next page.

# List canvases
Source: https://docs.ankra.ai/api-reference/canvases/list-canvases

https://platform.ankra.app/openapi.json get /api/v1/org/canvases
Lists the canvases the caller can see - their own and every canvas shared with the organisation - most recently updated first, without content. `query` matches the title, `kind` is dashboard or page, and `pinned=true` keeps the caller's pinned canvases. Pass `next_cursor` back as `cursor` for the next page. With `source_conversation_id` and `source_artifact_id` the list is a lookup instead: `items` holds the one canvas saved from that chat artifact when the caller can see it, or is empty, and `next_cursor` is null.

# Move a canvas draft
Source: https://docs.ankra.ai/api-reference/canvases/move-a-canvas-draft

https://platform.ankra.app/openapi.json post /api/v1/org/canvases/{canvas_id}/draft
Undo and redo: points the draft at any revision of the canvas without writing a new one, under the same `base_revision_id` check as saving. Only the owner can move the draft.

# Pin a canvas
Source: https://docs.ankra.ai/api-reference/canvases/pin-a-canvas

https://platform.ankra.app/openapi.json put /api/v1/org/canvases/{canvas_id}/pin
Adds a canvas the caller can see to their pinned canvases. Pins are per member; pinning twice changes nothing.

# Rename or share a canvas
Source: https://docs.ankra.ai/api-reference/canvases/rename-or-share-a-canvas

https://platform.ankra.app/openapi.json patch /api/v1/org/canvases/{canvas_id}
Changes the title, the visibility or both. `private` keeps the canvas to its owner; `organisation` lets every member read it. Only the owner can change a canvas.

# Save a canvas revision
Source: https://docs.ankra.ai/api-reference/canvases/save-a-canvas-revision

https://platform.ankra.app/openapi.json post /api/v1/org/canvases/{canvas_id}/revisions
Appends a revision and makes it the draft. `base_revision_id` is the draft the change was made on: when the draft has moved since, nothing is saved and the answer is 409 with the current revision, so a newer change is never overwritten. Only the owner can save.

# Unpin a canvas
Source: https://docs.ankra.ai/api-reference/canvases/unpin-a-canvas

https://platform.ankra.app/openapi.json delete /api/v1/org/canvases/{canvas_id}/pin
Removes a canvas from the caller's pinned canvases. Unpinning a canvas that was not pinned changes nothing.

# Get detailed information about a specific chart
Source: https://docs.ankra.ai/api-reference/charts/get-detailed-information-about-a-specific-chart

https://platform.ankra.app/openapi.json post /api/v1/org/stacks/charts/details
Returns a chart's icon, repository and available versions, looked up by `chart_name` and `repository_url`. Answers 404 when no such chart exists.

# List available Helm charts
Source: https://docs.ankra.ai/api-reference/charts/list-available-helm-charts

https://platform.ankra.app/openapi.json get /api/v1/org/stacks/charts
Lists the Helm charts available to the organisation, from its own registries and the global ones, with each chart's repository, icon, version and registry credential name. Paginated, with `page_size` up to 1500.

# Answer the question a durable AI chat session is parked on
Source: https://docs.ankra.ai/api-reference/chat/answer-the-question-a-durable-ai-chat-session-is-parked-on

https://platform.ankra.app/openapi.json post /api/v1/chat/sessions/{session_id}/answers
Answers the question an AI chat session is waiting on, with the `question_id` and at least one of the offered `selected_option_ids`, so the turn can continue. Answers 409 when no pending question matches.

# Approve an AI chat plan and execute its steps
Source: https://docs.ankra.ai/api-reference/chat/approve-an-ai-chat-plan-and-execute-its-steps

https://platform.ankra.app/openapi.json post /api/v1/chat/plans/{plan_id}/approve
Approves an AI plan and executes its steps, streaming progress as server-sent events. Requires `ai.execute`. High-risk and irreversible steps must be named in `acknowledged_step_orders`, or the call answers 400 listing them; a plan created before the current plan format answers 410 and has to be proposed again.

# Approve an AI chat plan and execute its steps (browser session)
Source: https://docs.ankra.ai/api-reference/chat/approve-an-ai-chat-plan-and-execute-its-steps-browser-session

https://platform.ankra.app/openapi.json post /chat/plans/{plan_id}/approve
Approves an AI plan and executes its steps, streaming progress as server-sent events. Requires `ai.execute`. High-risk and irreversible steps must be named in `acknowledged_step_orders`, or the call answers 400 listing them; a plan created before the current plan format answers 410 and has to be proposed again.

# Ask a running AI chat session to answer now
Source: https://docs.ankra.ai/api-reference/chat/ask-a-running-ai-chat-session-to-answer-now

https://platform.ankra.app/openapi.json post /api/v1/chat/sessions/{session_id}/wrap-up
Asks the running turn to stop investigating and answer with what it has; the session keeps running. Repeating the call is safe and returns the original `wrap_up_requested_at`; answers 409 when no turn is running.

# Cancel a durable AI chat session
Source: https://docs.ankra.ai/api-reference/chat/cancel-a-durable-ai-chat-session

https://platform.ankra.app/openapi.json post /api/v1/chat/sessions/{session_id}/cancel
Cancels an AI chat session and stops any turn it is running. Answers 409 when the session can no longer be cancelled and 404 when it is not visible to the caller.

# Confirm or reject a pending AI action
Source: https://docs.ankra.ai/api-reference/chat/confirm-or-reject-a-pending-ai-action

https://platform.ankra.app/openapi.json post /api/v1/chat/actions/confirm
Approves (`confirmed: true`) or rejects a write the AI proposed in chat, identified by `action_id`, or every write of one proposal batch identified by `batch_id` (with `action_ids` to approve some and reject the rest). Requires `ai.execute`. For one action, answers 404 when it is unknown or expired, 409 when the cluster state drifted since the proposal or the action was superseded, and 410 when its approval window has passed. For a batch, answers 404 when no action carries it and otherwise 200 with one result per action in proposal order (a decided action's result is the single decision's response; `drifted`, `agent_timeout`, `expired`, `superseded` and `skipped` name the actions it could not decide) and a `summary` of `executed`, `failed`, `rejected`, `open`, `skipped` and `deciding` counts. A batch that takes longer than about 90 seconds answers then: the actions not yet decided read `deciding`, are still decided in order afterwards, and report their outcomes as `action_decided` events on the conversation. An `action_decided` event for an action whose execution failed carries its `error` when the decision knew it.

# Create a durable AI chat session
Source: https://docs.ankra.ai/api-reference/chat/create-a-durable-ai-chat-session

https://platform.ankra.app/openapi.json post /api/v1/chat/sessions
The bearer twin of the browser session transport - the successor the deprecated POST /api/v1/chat/general points clients at. Token authentication replaces the session cookie and CSRF pair; authorisation is the browser lane's.

# Delete a chat conversation
Source: https://docs.ankra.ai/api-reference/chat/delete-a-chat-conversation

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/{cluster_id}/kubernetes/chat/history/{conversation_id}
Deletes one of the caller's saved chat conversations. Answers 404 when the cluster or the conversation is not found.

# Delete a general chat conversation
Source: https://docs.ankra.ai/api-reference/chat/delete-a-general-chat-conversation

https://platform.ankra.app/openapi.json delete /api/v1/chat/general/history/{conversation_id}
Deletes one of the caller's saved chat conversations. Answers 404 when the conversation does not exist or belongs to someone else.

# Edit a proposed AI plan step's parameters
Source: https://docs.ankra.ai/api-reference/chat/edit-a-proposed-ai-plan-steps-parameters

https://platform.ankra.app/openapi.json patch /api/v1/chat/plans/{plan_id}/steps/{step_id}
Replaces the `parameters` object of one step in a proposed AI plan and returns the updated plan. Answers 400 when the step cannot be edited.

# Extend a proposed AI plan's expiry
Source: https://docs.ankra.ai/api-reference/chat/extend-a-proposed-ai-plans-expiry

https://platform.ankra.app/openapi.json post /api/v1/chat/plans/{plan_id}/refresh
Pushes back the expiry of a proposed AI plan and returns the new `expires_at`. It does not regenerate the plan; answers 409 when the plan is not in a refreshable state.

# Get a specific chat conversation
Source: https://docs.ankra.ai/api-reference/chat/get-a-specific-chat-conversation

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/kubernetes/chat/history/{conversation_id}
Returns one of the caller's saved chat conversations with its messages. Answers 404 when the cluster or the conversation is not found.

# Get a specific general chat conversation
Source: https://docs.ankra.ai/api-reference/chat/get-a-specific-general-chat-conversation

https://platform.ankra.app/openapi.json get /api/v1/chat/general/history/{conversation_id}
Returns one of the caller's saved chat conversations with its messages, or the conversation of a platform-dispatched session that a ticket the caller can read links as its work. Answers 404 when it does not exist or neither applies.

# Get AI-analysed cluster health
Source: https://docs.ankra.ai/api-reference/chat/get-ai-analysed-cluster-health

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/kubernetes/health
Returns health insights for the cluster. Set `include_ai_analysis` to true to add an AI analysis; answers 404 when the cluster is not a live cluster of the organisation.

# Get one AI plan with its steps
Source: https://docs.ankra.ai/api-reference/chat/get-one-ai-plan-with-its-steps

https://platform.ankra.app/openapi.json get /api/v1/chat/plans/{plan_id}
Returns an AI plan with its steps. Answers 404 for an unknown plan and 403 when the plan belongs to another user.

# Get one durable AI chat session
Source: https://docs.ankra.ai/api-reference/chat/get-one-durable-ai-chat-session

https://platform.ankra.app/openapi.json get /api/v1/chat/sessions/{session_id}
Returns one of the caller's AI chat sessions with its current status, or a platform-dispatched session that a ticket the caller can read links as its work. Answers 404 when it does not exist or neither applies.

# List chat conversations for a cluster
Source: https://docs.ankra.ai/api-reference/chat/list-chat-conversations-for-a-cluster

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/kubernetes/chat/history
Lists the caller's saved chat conversations about the cluster, paginated with `limit` (default 50, 1 to 1000) and `offset`. Set `show_all` to true to list the caller's conversations across all clusters.

# List general chat conversations
Source: https://docs.ankra.ai/api-reference/chat/list-general-chat-conversations

https://platform.ankra.app/openapi.json get /api/v1/chat/general/history
Lists the caller's saved chat conversations, newest first, paginated with `limit` (default 50, 1 to 1000) and `offset`. `show_all` (default true) includes cluster conversations; set it to false for general conversations only.

# List general chat conversations with unseen finished replies
Source: https://docs.ankra.ai/api-reference/chat/list-general-chat-conversations-with-unseen-finished-replies

https://platform.ankra.app/openapi.json get /api/v1/chat/general/history/unread

# List pending AI actions for a conversation
Source: https://docs.ankra.ai/api-reference/chat/list-pending-ai-actions-for-a-conversation

https://platform.ankra.app/openapi.json get /api/v1/chat/actions/pending
Lists the caller's AI-proposed actions still awaiting confirmation in the conversation named by the required `conversation_id` query parameter, with their count.

# List the caller's durable AI chat sessions
Source: https://docs.ankra.ai/api-reference/chat/list-the-callers-durable-ai-chat-sessions

https://platform.ankra.app/openapi.json get /api/v1/chat/sessions
Lists the caller's AI chat sessions, optionally filtered by `cluster_id`, `agent_task_id` and `status`. `limit` defaults to 50 and is capped at 200.

# List the caller's open AI plans for a conversation
Source: https://docs.ankra.ai/api-reference/chat/list-the-callers-open-ai-plans-for-a-conversation

https://platform.ankra.app/openapi.json get /api/v1/chat/plans
Lists the caller's open AI plans in the conversation named by the required `conversation_id` query parameter, with their count.

# Mark a general chat conversation's results as seen
Source: https://docs.ankra.ai/api-reference/chat/mark-a-general-chat-conversations-results-as-seen

https://platform.ankra.app/openapi.json post /api/v1/chat/general/history/{conversation_id}/seen

# Re-check a pending AI action against the live cluster state
Source: https://docs.ankra.ai/api-reference/chat/re-check-a-pending-ai-action-against-the-live-cluster-state

https://platform.ankra.app/openapi.json get /api/v1/chat/actions/{action_id}/revalidate
Re-checks a pending AI action before it is confirmed. Answers 200 when it still applies, 409 when the cluster state drifted or the action was superseded, 410 when it expired, 404 when it is unknown, and 503 when the cluster agent could not be reached.

# Read a conversation's decision trace
Source: https://docs.ankra.ai/api-reference/chat/read-a-conversations-decision-trace

https://platform.ankra.app/openapi.json get /api/v1/chat/conversations/{conversation_id}/trace
Returns the team-readable decision trace of a chat conversation, grouped by turn: the model routing decision with its reason, the tool families offered and lazily loaded, every refused tool call with its error code, every post-hoc rewrite of the reply, every budget or loop-guard intervention, how each turn ended, and every pending-action status transition with who decided it. Organisation admins only; a conversation outside the organisation answers 404.

# Read a durable AI chat session's event log, as a page or an SSE tail
Source: https://docs.ankra.ai/api-reference/chat/read-a-durable-ai-chat-sessions-event-log-as-a-page-or-an-sse-tail

https://platform.ankra.app/openapi.json get /api/v1/chat/sessions/{session_id}/events
Reads an AI chat session's event log from sequence `since`, as a JSON page of up to `limit` events (default 1000, at most 5000). With `stream=true` it replays the log and then follows new events as server-sent events, resuming from `since` or the `Last-Event-ID` header, and ends when the session finishes.

# Record that an approval card for this action was rendered to its owner
Source: https://docs.ankra.ai/api-reference/chat/record-that-an-approval-card-for-this-action-was-rendered-to-its-owner

https://platform.ankra.app/openapi.json post /api/v1/chat/actions/{action_id}/presented
Stamps presented_at for a surface that painted a decidable approval card for the calling user - the Slack confirmation card acknowledges here with the asker's own token. A surface that only mentions the action must not call it. Repeat acknowledgements answer recorded=false and leave the first stamp alone.

# Reject a proposed AI plan
Source: https://docs.ankra.ai/api-reference/chat/reject-a-proposed-ai-plan

https://platform.ankra.app/openapi.json post /api/v1/chat/plans/{plan_id}/reject
Rejects a proposed AI plan, with an optional `reason`. A chat session waiting on the plan is resumed with the decision; answers 404 when the plan does not exist or can no longer be rejected.

# Reorder the steps of a proposed AI plan
Source: https://docs.ankra.ai/api-reference/chat/reorder-the-steps-of-a-proposed-ai-plan

https://platform.ankra.app/openapi.json post /api/v1/chat/plans/{plan_id}/reorder
Sets a new order for a proposed plan's steps from `entries`, a non-empty list of `step_id` and integer `step_order` pairs, and returns the updated plan. Answers 400 when the new order is not valid.

# Restore a skipped AI plan step
Source: https://docs.ankra.ai/api-reference/chat/restore-a-skipped-ai-plan-step

https://platform.ankra.app/openapi.json post /api/v1/chat/plans/{plan_id}/steps/{step_id}/restore
Puts a skipped step of an AI plan back into the plan and returns the updated plan. Answers 400 when the step cannot be restored.

# Skip a pending AI plan step
Source: https://docs.ankra.ai/api-reference/chat/skip-a-pending-ai-plan-step

https://platform.ankra.app/openapi.json post /api/v1/chat/plans/{plan_id}/steps/{step_id}/skip
Marks one pending step of an AI plan as skipped, with an optional `reason`, and returns the updated plan. Answers 400 when the step cannot be skipped.

# Stream chat responses for cluster troubleshooting
Source: https://docs.ankra.ai/api-reference/chat/stream-chat-responses-for-cluster-troubleshooting

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/{cluster_id}/kubernetes/chat
Runs one AI chat turn about the cluster and streams the reply as server-sent events. Answers 404 when the cluster is not a live cluster of the organisation. Deprecated: responses carry `Deprecation` and `Sunset` headers, and durable chat sessions (`/api/v1/chat/sessions`) are the successor.

# Stream general chat responses
Source: https://docs.ankra.ai/api-reference/chat/stream-general-chat-responses

https://platform.ankra.app/openapi.json post /api/v1/chat/general
Runs one general (not cluster-scoped) AI chat turn and streams the reply as server-sent events. Deprecated: responses carry `Deprecation` and `Sunset` headers, and durable chat sessions (`/api/v1/chat/sessions`) are the successor.

# Submit a user turn to a durable AI chat session
Source: https://docs.ankra.ai/api-reference/chat/submit-a-user-turn-to-a-durable-ai-chat-session

https://platform.ankra.app/openapi.json post /api/v1/chat/sessions/{session_id}/turns
Scoped tokens are honoured end to end: the token's scope allowlist is persisted with the turn (token_scopes on the user_turn event) and the session runner narrows its ai.execute lane gate and per-tool gate to it.

# Summarise a conversation's placeholder title from its first exchange
Source: https://docs.ankra.ai/api-reference/chat/summarise-a-conversations-placeholder-title-from-its-first-exchange

https://platform.ankra.app/openapi.json post /api/v1/chat/conversations/{conversation_id}/title/regenerate
Replaces a conversation's placeholder title with a short AI-generated summary of its first exchange and returns the new `title`. Answers 409 when the title was already set by hand, 422 when the conversation has no exchange yet, and 404 when it is not the caller's.

# Approve or decline the Platform connection request
Source: https://docs.ankra.ai/api-reference/cloud-delegation/approve-or-decline-the-platform-connection-request

https://platform.ankra.app/openapi.json post /oauth/cloud/authorize/decision
Requires the same Platform browser, authenticated subject, a single-use CSRF nonce paired with an HttpOnly host-only cookie, and the Platform Origin header. Membership and MFA are rechecked before issuing a 60-second code. Refuses cross-origin submissions.

# Exchange an approved Cloud consent code for an organisation grant
Source: https://docs.ankra.ai/api-reference/cloud-delegation/exchange-an-approved-cloud-consent-code-for-an-organisation-grant

https://platform.ankra.app/openapi.json post /api/v1/cloud/delegation-grants/exchange
Authenticates Cloud before reading the body. Atomically consumes a 60-second code, checks S256 PKCE and the exact callback, and rechecks the consenting human and organisation membership. Only the grant hash is stored; Cloud keeps its secret sealed. A directory bearer cannot exchange a code.

# Show Platform consent for an Ankra Cloud organisation connection
Source: https://docs.ankra.ai/api-reference/cloud-delegation/show-platform-consent-for-an-ankra-cloud-organisation-connection

https://platform.ankra.app/openapi.json get /oauth/cloud/authorize
Requires the person’s real Platform browser session and its MFA gate. Auth0 subject must match Cloud’s requested subject. The exact callback is deployment configured. Shows explicit consent for the person’s current permissions in one active organisation, for at most twelve hours. No grant is created by GET.

# Connect a Cloudflare credential
Source: https://docs.ankra.ai/api-reference/cloudflare/connect-a-cloudflare-credential

https://platform.ankra.app/openapi.json post /api/v1/org/cloudflare/credentials
Verifies a Cloudflare API token against Cloudflare, stores it under `name` and answers 201 with the verification result. Organisation admins only; a token Cloudflare rejects, or one that reaches no domain, answers 400.

# Create a Cloudflare DNS record
Source: https://docs.ankra.ai/api-reference/cloudflare/create-a-cloudflare-dns-record

https://platform.ankra.app/openapi.json post /api/v1/org/cloudflare/domains/{zone_id}/records
Creates a DNS record in the Cloudflare domain and answers 201 with it; the TTL defaults to automatic and proxying to off. Organisation admins only; answers 409 when the record already exists.

# Delete a Cloudflare DNS record
Source: https://docs.ankra.ai/api-reference/cloudflare/delete-a-cloudflare-dns-record

https://platform.ankra.app/openapi.json delete /api/v1/org/cloudflare/domains/{zone_id}/records/{record_id}
Deletes the record from the Cloudflare domain and answers 204. Organisation admins only.

# Get a Cloudflare domain
Source: https://docs.ankra.ai/api-reference/cloudflare/get-a-cloudflare-domain

https://platform.ankra.app/openapi.json get /api/v1/org/cloudflare/domains/{zone_id}
Returns one Cloudflare domain by zone id, with its status and name servers. Answers 404 for a domain the organisation's credential cannot reach.

# List Cloudflare credentials
Source: https://docs.ankra.ai/api-reference/cloudflare/list-cloudflare-credentials

https://platform.ankra.app/openapi.json get /api/v1/org/cloudflare/credentials
Lists the Cloudflare credentials connected to the organisation, with the account each one reaches, when it was verified, token expiry and state. The API token itself is never returned.

# List Cloudflare DNS records
Source: https://docs.ankra.ai/api-reference/cloudflare/list-cloudflare-dns-records

https://platform.ankra.app/openapi.json get /api/v1/org/cloudflare/domains/{zone_id}/records
Lists the DNS records in a Cloudflare domain, with optional `name`, `record_type` and `search` filters. Answers 404 for a domain the organisation's credential cannot reach.

# List Cloudflare domains
Source: https://docs.ankra.ai/api-reference/cloudflare/list-cloudflare-domains

https://platform.ankra.app/openapi.json get /api/v1/org/cloudflare/domains
Lists the Cloudflare domains the organisation's credential reaches, optionally filtered by `name`; pick a credential with `credential_name`. `is_truncated` is true when the list was cut short.

# Update a Cloudflare DNS record
Source: https://docs.ankra.ai/api-reference/cloudflare/update-a-cloudflare-dns-record

https://platform.ankra.app/openapi.json patch /api/v1/org/cloudflare/domains/{zone_id}/records/{record_id}
Changes a record's `content`, which is required, and any of `ttl`, `proxied`, `priority` and `comment`: an omitted field keeps its current value and a field sent as null is reset. The name and record type cannot change. Organisation admins only.

# Verify a Cloudflare token
Source: https://docs.ankra.ai/api-reference/cloudflare/verify-a-cloudflare-token

https://platform.ankra.app/openapi.json post /api/v1/org/cloudflare/credentials/verify
Checks a Cloudflare API token and reports the account and domains it reaches, without storing it. Organisation admins only.

# Create a cluster access grant
Source: https://docs.ankra.ai/api-reference/cluster-access/create-a-cluster-access-grant

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/access/grants
Grants an active organisation member (by `user_email`) a Kubernetes role (`view`, `edit`, `admin` or `cluster-admin`) on the whole cluster or on one `namespace`, optionally expiring via `expires_in` or `expires_at` and with an audit `reason`. Requires `kube_access.manage` and organisation admin; returns 409 when a matching grant already exists and 400 when the user is not an active member. A caller holding `kube_access.elevate` instead may grant only itself (403 otherwise), and the grant must expire within the policy's elevated_max_ttl_seconds (4 hours when unset) and carry a reason; it may re-time only an elevation it made. Grants outside the organisation policy answer 403 with detail cluster_access_policy_violation, cluster_access_grant_expiry_required, cluster_access_grant_lifetime_exceeded or cluster_access_grant_reason_required, naming the bound.

# Delete a cluster access grant
Source: https://docs.ankra.ai/api-reference/cluster-access/delete-a-cluster-access-grant

https://platform.ankra.app/openapi.json delete /api/v1/clusters/{cluster_id}/access/grants/{grant_id}
Revokes one access grant on a cluster; the member loses that access through the kube gateway. Requires `kube_access.manage` and organisation admin; returns 404 when the grant does not exist. A grant that comes from the member's organisation role (source role) answers 409: the role sync would re-create it, so change the member's role, or the role's Kubernetes access, to remove it. A caller holding `kube_access.elevate` instead may end only an elevation it made for itself; any other grant answers 404.

# Elevate your own cluster access
Source: https://docs.ankra.ai/api-reference/cluster-access/elevate-your-own-cluster-access

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/access/elevate
Break-glass addressed to the caller: the body names no member (a `user_email` is refused with 422), and the route grants the authenticated principal itself (a member or a service account, which has no email the grants route could name) a Kubernetes role on the whole cluster or one `namespace`. The grant must expire (`expires_in` or `expires_at`) within the organisation policy's elevated_max_ttl_seconds, or 4 hours when unset, must carry a `reason`, and stays under max_grant_role; re-posting with a new expiry re-times only the caller's own elevation. Requires `kube_access.elevate` (or `kube_access.manage`, held to the same bounds). Refusals answer 403 with detail cluster_access_policy_violation, cluster_access_grant_expiry_required, cluster_access_grant_lifetime_exceeded or cluster_access_grant_reason_required, naming the bound, and 409 when a matching grant exists that is not the caller's own elevation. End it early with DELETE /api/v1/clusters/{cluster_id}/access/grants/{grant_id}.

# Generate a kubeconfig
Source: https://docs.ankra.ai/api-reference/cluster-access/generate-a-kubeconfig

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubeconfig
Returns a ready-to-use kubeconfig document for the cluster that points at the kube gateway and embeds a freshly minted short-lived token, together with the server URL and the token's expiry. Requires `kube_access.use` on the cluster; requests are rate limited per user (429).

# Get a cluster access policy proposal
Source: https://docs.ankra.ai/api-reference/cluster-access/get-a-cluster-access-policy-proposal

https://platform.ankra.app/openapi.json get /api/v1/org/cluster-access-policy/proposals/{proposal_id}
One cluster access policy proposal: the proposed policy, the policy it was proposed against (base), the current policy and whether it still matches base, the reason, the proposer and the token that carried the proposal, its status, expiry and decision, and the apply_url. Readable with `kube_access.manage`, `kube_access.policy` or `kube_access.elevate`; 404 when the organisation has no such proposal, naming the organisation searched (organisation_id, organisation_name): a proposal created in another organisation answers 404 here.

# Get Cluster Access Policy
Source: https://docs.ankra.ai/api-reference/cluster-access/get-cluster-access-policy

https://platform.ankra.app/openapi.json get /api/v1/org/cluster-access-policy
The organisation cluster access policy: the role the user who creates or imports a cluster receives on it, the highest role any cluster access grant may carry, the longest a grant above view may last, and the role from which grants need a reason. An organisation that has not set one reads the default (creator receives cluster-admin, no ceiling, no bounds) with is_configured false. Readable with `kube_access.manage`, `kube_access.policy` or `kube_access.elevate` (a break-glass holder reads the bounds it is held to). organisation_id and organisation_name name the organisation read: a token reads its own unless X-Ankra-Organisation-Id names another, so check them before reporting another organisation's policy.

# List cluster access grants
Source: https://docs.ankra.ai/api-reference/cluster-access/list-cluster-access-grants

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/access/grants
Lists the access grants on a cluster, newest first, each naming the member, the scope (whole cluster or one namespace), the Kubernetes role and the expiry. Requires `kube_access.manage` and organisation admin; returns 403 otherwise.

# List cluster access policy proposals
Source: https://docs.ankra.ai/api-reference/cluster-access/list-cluster-access-policy-proposals

https://platform.ankra.app/openapi.json get /api/v1/org/cluster-access-policy/proposals
The organisation's cluster access policy proposals, newest first (at most 20; is_capped says when more matched). status filters by the status a proposal reads as: a pending proposal past its expiry reads as expired. Readable with `kube_access.manage`, `kube_access.policy` or `kube_access.elevate`, like the policy itself. organisation_id and organisation_name name the organisation listed, so an empty listing still says whose it is.

# Mint a Kubernetes access token
Source: https://docs.ankra.ai/api-reference/cluster-access/mint-a-kubernetes-access-token

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/k8s-token
Mints a short-lived bearer token for the cluster's kube gateway (valid for one hour by default), as used by the CLI's kubectl exec credential plugin. Requires `kube_access.use` on the cluster, and the minted token carries the calling token's restrictions; requests are rate limited per user (429).

# Propose a cluster access policy change
Source: https://docs.ankra.ai/api-reference/cluster-access/propose-a-cluster-access-policy-change

https://platform.ankra.app/openapi.json post /api/v1/org/cluster-access-policy/proposals
Propose a change to the organisation cluster access policy. This never changes the policy: it records a proposal that an organisation owner or admin applies, signed in to the Ankra web app, from apply_url. Every field but reason is optional and an omitted one keeps its current value; elevated_max_ttl_seconds and require_reason_from_role may be null to clear the bound. The proposed policy is validated exactly like a policy write, and a proposal identical to the current policy answers 422. A new proposal supersedes the pending one; a proposal expires after 7 days, and applying it answers 409 policy_changed if the policy changed since it was proposed. Requires `kube_access.manage`, which is not human-only: an administrator's CLI token can propose. Applying and dismissing have no token route.

# Set Cluster Access Policy
Source: https://docs.ankra.ai/api-reference/cluster-access/set-cluster-access-policy

https://platform.ankra.app/openapi.json put /api/v1/org/cluster-access-policy
Set the organisation cluster access policy. creator_grant_role none seeds no grant for the creator; a creator role above max_grant_role is refused, and so is a creator role above view while elevated_max_ttl_seconds is set (sent or stored), because the creator's grant is standing and would be over policy as soon as it is seeded. A lowered ceiling leaves manual and creator grants above it in place, but they cannot be re-timed; grants that come from organisation roles are lowered to the new ceiling on the next role sync (about a minute), each with an audit row and one organisation notification per sync. New grants above the ceiling answer 403 cluster_access_policy_violation. elevated_max_ttl_seconds and require_reason_from_role are optional: an omitted bound keeps its stored value and null clears it; new and re-timed grants outside them answer 403 cluster_access_grant_expiry_required, cluster_access_grant_lifetime_exceeded or cluster_access_grant_reason_required. Requires `kube_access.policy`, which is human-only: an API token must name it in its scopes, and an unscoped or wildcard token answers 403 permission_denied. organisation_id and organisation_name name the organisation written.

# Change cluster labels
Source: https://docs.ankra.ai/api-reference/clusters/change-cluster-labels

https://platform.ankra.app/openapi.json patch /api/v1/org/clusters/{cluster_id}/labels
Sets and removes labels on this cluster (`ankra cluster label set|rm`): `set` adds or overwrites labels, `remove` deletes keys (removing a key the cluster does not carry is not an error). A label moves the cluster into or out of every dynamic cluster group that selects on it, and so changes what members holding a group-scoped role may do on it; the change therefore requires `clusters.write` for the whole organisation, not only on the cluster. Keys are 1-63 lowercase letters, digits, `.`, `_`, `-` or `/`; values are 1-63 letters, digits, `.`, `_` or `-`; a cluster carries at most 32 labels; the `environment` key is reserved. Every change is recorded in the organisation's audit log; a change that leaves the labels as they were records nothing. Answers the labels after the change.

# Create the organisation's playground
Source: https://docs.ankra.ai/api-reference/clusters/create-the-organisations-playground

https://platform.ankra.app/openapi.json post /org/clusters/playground
Creates the organisation's playground. With the hosts provider it is a real, writable vcluster on Ankra's shared playground host; with the ankracloud provider it is an Ankra Cloud dev cluster created through the managed-create flow on the organisation's built-in Ankra Cloud credential (the free 24-hour trial for an account with no payment method, a billed dev cluster otherwise; IPv6-only, with proxied records for IPv4 clients, unless the order body carries `public_ipv4: true`, which orders the public IPv4 add-on at create for an account that can spend and on conversion for a trial). Browser session authentication. One live playground per organisation across both providers.

# Declare a custom DNS zone on the cluster
Source: https://docs.ankra.ai/api-reference/clusters/declare-a-custom-dns-zone-on-the-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/custom-dns-zones
The DNS zones this cluster serves with the organisation's own external-dns webhook credential, alongside the delegated zone Ankra serves itself. Ankra's own Avura token is pinned to Ankra's account, so ingress hosts on a zone the customer holds in their own provider account are dropped server-side and publish nothing. Declaring the zone here has Ankra render and own an external-dns deployment for it, pinned to that zone with its own txt owner id. A zone that overlaps the delegated zone Ankra already serves for this cluster is refused with 400: two sync-policy controllers on one zone delete each other's records.

# Delete a cluster by name
Source: https://docs.ankra.ai/api-reference/clusters/delete-a-cluster-by-name

https://platform.ankra.app/openapi.json delete /api/v1/clusters/{cluster_name}
Deletes an imported cluster identified by its name and revokes its agent's credentials. Requires `clusters.delete` at organisation scope; cloud clusters are refused with `409` and must be deleted through their provider's route so cloud resources are released. A cluster that hosts managed services that have not been retired is refused with `409` naming them, until they are retired or its agent has been offline for 15 minutes.

# Deprovision a cluster
Source: https://docs.ankra.ai/api-reference/clusters/deprovision-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/deprovision
Tears down what Ankra manages on an imported cluster, which must be online: active executions are cancelled, every resource is set to stop, and a reconcile is triggered. Requires `clusters.delete`; cloud clusters are refused with `409` and must be deleted through their provider's route so cloud resources are released.

# Disable the cluster's DNS zone
Source: https://docs.ankra.ai/api-reference/clusters/disable-the-clusters-dns-zone

https://platform.ankra.app/openapi.json delete /api/v1/clusters/{cluster_id}/dns-zone
Hands the cluster's DNS zone back for asynchronous teardown and returns its state; the cluster itself is not changed, and the zone is not recreated until it is enabled again. Answers 404 when the cluster has no zone.

# Enable the cluster's DNS zone
Source: https://docs.ankra.ai/api-reference/clusters/enable-the-clusters-dns-zone

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/dns-zone
Creates the cluster's generated public DNS zone under the organisation's root domain and returns its FQDN and state. Idempotent: an existing zone keeps its FQDN and a failed one is retried. The zone is provisioned asynchronously, after which Ankra installs external-dns on the cluster to publish hostnames in it.

# Get a cluster's Baseline score
Source: https://docs.ankra.ai/api-reference/clusters/get-a-clusters-baseline-score

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/baseline
A cluster's Ankra Baseline score: the latest nightly evaluation of the ten Baseline checks (metrics and logs, service-level alerts, backups with a tested restore, requests and limits, probes, PodDisruptionBudgets, pinned images, supported versions, certificate automation, no critical or known-exploited CVEs), each pass, fail or unknown with its evidence, the gaps heaviest first and the unknowns named. The score is passed weight over decided weight; unknown checks leave the denominator and are reported as coverage. A cluster the nightly recorder has not scored answers computed false with every check unknown, not a score of zero. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Get cluster GitOps status
Source: https://docs.ankra.ai/api-reference/clusters/get-cluster-gitops-status

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/gitops/status
Returns which GitOps repository, branch and credential the cluster syncs from, together with the last synced commit. A cluster without GitOps configured returns a `not_configured` status.

# Get control plane self-heal
Source: https://docs.ankra.ai/api-reference/clusters/get-control-plane-self-heal

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/control-plane-self-heal
Whether Ankra may restart a NotReady control plane of this cluster through its cloud provider (`ankra cluster control-plane-heal status`), and the cluster's latest NotReady episode: which node, what Ankra did, and how it ended. Ankra restarts a control plane only after it has been NotReady for about ten minutes, only when every other control plane is Ready and etcd keeps its quorum without it, and at most twice per node per day. It never stops, deprovisions or scales anything. Automatic restart is on for every cluster until a member turns it off. Readable by any member of the organisation. Bearer-PAT twin of the browser route of the same name under /org.

# Get hosted log shipping
Source: https://docs.ankra.ai/api-reference/clusters/get-hosted-log-shipping

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/hosted-logs
Whether this cluster's container log lines are sent to Ankra's hosted log store (`ankra cluster logs-ship status`), whether that store is live on this platform (`available`), and whether the cluster's agent can obey the switch (`agent_supports_switch`; false means the agent needs an upgrade or has hosted log shipping turned off in its own Helm values). Hosted log shipping is off for every cluster until a member turns it on. Readable by any member of the organisation. Bearer-PAT twin of the browser route of the same name under /org.

# Get state snapshot retention
Source: https://docs.ankra.ai/api-reference/clusters/get-state-snapshot-retention

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/state-snapshot-retention
The cluster's retention window for its scheduled etcd backups (`ankra cluster state-snapshots retention`). Ankra backs up the etcd state of every running cluster it provisions off the control plane, to the organisation's backup vault, every six hours. It keeps the four newest backups, plus the newest backup of each UTC day for `retention_days` days, 7 unless a member sets another window between 1 and 90. Whatever the window, Ankra also keeps the newest backup from before the cluster's last start and its last recovery incidents. Readable by any member of the organisation. Bearer-PAT twin of the browser route of the same name under /org.

# Get the cluster agent's sizing
Source: https://docs.ankra.ai/api-reference/clusters/get-the-cluster-agents-sizing

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/agent/resources
Returns the agent container sizing Ankra holds for the cluster (memory and CPU limits and requests; null where Ankra holds nothing, so the agent chart's default and the agent's live sizing apply) and what it is doing now: apply_state not_set, applied, pending_upgrade or agent_offline, with a message to show verbatim. The bearer twin of `ankra cluster agent resources get`.

# Get the cluster's DNS token rotation
Source: https://docs.ankra.ai/api-reference/clusters/get-the-clusters-dns-token-rotation

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/dns-zone/token-rotation
Reports where the rotation of the cluster's DNS write token stands: whether a rotation is waiting for its replacement token, and whether the token a rotation replaced is still valid and waiting to be revoked. Never returns a token.

# Get the cluster's DNS zone
Source: https://docs.ankra.ai/api-reference/clusters/get-the-clusters-dns-zone

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/dns-zone
Read the cluster's generated public DNS domain without creating one. A cluster that has no zone reports state "none" with an empty fqdn. The domain nests under the organisation's Ankra root domain (dns_root_domain on /api/v1/org/ai-environment; ankra.cc by default). Use POST to create the zone and DELETE to hand it back for teardown.

# Import or update a cluster
Source: https://docs.ankra.ai/api-reference/clusters/import-or-update-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/import
Applies an ImportCluster specification: creates the cluster when no cluster with that name exists in your organisation, otherwise updates it, including its stacks and GitOps settings. By default the apply runs in the background and the call answers `202` with `{"status": "accepted", "operation_id": "<id>"}` (a `409` means an apply for the same cluster is already running). Follow the operation on `/api/v1/org/executions/{execution_id}`: it settles `success` or `failed`, and its step result carries the status code and body the apply would have answered synchronously, including the reason it was refused. Pass `wait=true` to run it synchronously and receive the result or the rejection reason directly.

# Latest restorable state snapshot of a HPE Morpheus cluster
Source: https://docs.ankra.ai/api-reference/clusters/latest-restorable-state-snapshot-of-a-hpe-morpheus-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/morpheus/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the HPE Morpheus cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# Latest restorable state snapshot of a Proxmox VE cluster
Source: https://docs.ankra.ai/api-reference/clusters/latest-restorable-state-snapshot-of-a-proxmox-ve-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/proxmox/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the Proxmox VE cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List cluster add-ons
Source: https://docs.ankra.ai/api-reference/clusters/list-cluster-add-ons

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/addons
Returns a paginated list of the add-ons deployed on the cluster, including their live health where available. Answers `404` when the cluster is not in your organisation.

# List cluster labels
Source: https://docs.ankra.ai/api-reference/clusters/list-cluster-labels

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/labels
The free-form key/value labels on this cluster (`ankra cluster label list`), which dynamic cluster groups select on, beside the cluster's own environment. The `environment` key is reserved: a group selecting on it reads the cluster's environment, so it is never stored as a label. Readable by any member of the organisation. Bearer-PAT twin of the browser route of the same name under /org.

# List cluster manifests
Source: https://docs.ankra.ai/api-reference/clusters/list-cluster-manifests

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/manifests
Returns the manifests deployed on the cluster. A cluster outside your organisation returns an empty list.

# List cluster stacks
Source: https://docs.ankra.ai/api-reference/clusters/list-cluster-stacks

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/stacks
Returns the first page (up to 25) of the stacks on the cluster. Answers `404` when the cluster is not in your organisation; use the imported-cluster stacks listing for search and paging.

# List clusters
Source: https://docs.ankra.ai/api-reference/clusters/list-clusters

https://platform.ankra.app/openapi.json get /api/v1/clusters
Returns a paginated list of the clusters in your organisation. Filter by `cluster_id` or by `cluster_name` (a case-insensitive partial match); `page_size` accepts 1 to 100 and defaults to 25.

# List CNI options
Source: https://docs.ankra.ai/api-reference/clusters/list-cni-options

https://platform.ankra.app/openapi.json get /api/v1/clusters/cni-options
Returns the container network interface (CNI) plugins you can choose when creating a cluster, with a display label for each and a flag marking the default.

# List GitOps conflicts
Source: https://docs.ankra.ai/api-reference/clusters/list-gitops-conflicts

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/gitops/conflicts
Lists the cluster's open GitOps merge conflicts (`ankra cluster gitops conflicts list`): resources changed both in the GitOps repository and on the platform since they last agreed. GitOps sync stays paused on them until each is resolved. Each entry names the resource, how Git (`git_change_type`) and the platform (`db_change_type`) changed it, and any resolution already recorded that the next sync will apply. Any member of the cluster's organisation can read it.

# List hosted log shipping
Source: https://docs.ankra.ai/api-reference/clusters/list-hosted-log-shipping

https://platform.ankra.app/openapi.json get /api/v1/org/hosted-logs
Every live cluster of the organisation with its hosted log shipping switch, ordered by name: whether the cluster's container log lines are sent to Ankra's hosted log store, whether that store is live on this platform (`available`), and whether the cluster's agent can obey the switch (`agent_supports_switch`). Each cluster is answered exactly as GET /api/v1/org/clusters/{cluster_id}/hosted-logs answers it, so this is the one place to see which clusters ship their logs and which could. Readable by any member of the organisation, like the per-cluster read. Bearer-PAT twin of the browser route of the same name under /org.

# List K3s versions
Source: https://docs.ankra.ai/api-reference/clusters/list-k3s-versions

https://platform.ankra.app/openapi.json get /api/v1/clusters/k3s-versions
Returns the K3s versions Ankra supports: the newest three minor releases with their two latest patches each. `stable_version` is the recommended version, used when a cluster is created without an explicit version.

# List kubeadm versions
Source: https://docs.ankra.ai/api-reference/clusters/list-kubeadm-versions

https://platform.ankra.app/openapi.json get /api/v1/clusters/kubeadm-versions
Returns the Kubernetes versions Ankra supports for kubeadm clusters: the newest three minor releases with their two latest patches each. `stable_version` is the recommended version, used when a cluster is created without an explicit version.

# List preserved GitOps paths
Source: https://docs.ankra.ai/api-reference/clusters/list-preserved-gitops-paths

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/gitops/preserved-paths
Lists the files Git and the platform are divided on: each was edited in Git, so Ankra keeps Git's bytes there instead of overwriting them, and the platform's later changes to it do not reach Git. Every entry carries both sides - withheld, with the reason, for a file that may carry a secret - and any decision already recorded, in path order and capped at 100 entries and a content budget (truncated says when either cap applied). Unlike a GitOps merge conflict a preserved file pauses nothing. Bearer-PAT twin of the browser route of the same name under /org.

# List the cluster's custom DNS zones
Source: https://docs.ankra.ai/api-reference/clusters/list-the-clusters-custom-dns-zones

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/custom-dns-zones
The DNS zones this cluster serves with the organisation's own external-dns webhook credential, alongside the delegated zone Ankra serves itself. Ankra's own Avura token is pinned to Ankra's account, so ingress hosts on a zone the customer holds in their own provider account are dropped server-side and publish nothing. Declaring the zone here has Ankra render and own an external-dns deployment for it, pinned to that zone with its own txt owner id.

# Read labels from the selected cluster log store
Source: https://docs.ankra.ai/api-reference/clusters/read-labels-from-the-selected-cluster-log-store

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/logs/labels
Namespace, pod and container values observed in the time window. Values can be capped and absence does not establish that collection is disabled. Use the same source choice as the history query.

# Read the playground provisioning status
Source: https://docs.ankra.ai/api-reference/clusters/read-the-playground-provisioning-status

https://platform.ankra.app/openapi.json get /org/clusters/playground/{clusterId}/status
Reads the provisioning phase of the organisation's playground. A playground belonging to another organisation is not found.

# Read what a cluster is for
Source: https://docs.ankra.ai/api-reference/clusters/read-what-a-cluster-is-for

https://platform.ankra.app/openapi.json get /org/clusters/{cluster_id}/criticality
Reports the cluster's criticality, the denominator the insight scanner grades blast radius against. Clusters that have never been classified read as production, which is the column's default and the value the grading falls back to.

# (Removed) Get a cluster operation
Source: https://docs.ankra.ai/api-reference/clusters/removed-get-a-cluster-operation

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/operations/{operation_id}
This endpoint has been removed and always answers 410 Gone. Use `GET /api/v1/org/executions/{execution_id}` instead.

# (Removed) List a cluster operation's jobs
Source: https://docs.ankra.ai/api-reference/clusters/removed-list-a-cluster-operations-jobs

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/operations/{operation_id}/jobs
This endpoint has been removed and always answers 410 Gone. Use `GET /api/v1/org/executions/{execution_id}/steps` and `GET /api/v1/org/executions/{execution_id}/result` instead.

# (Removed) List cluster operations
Source: https://docs.ankra.ai/api-reference/clusters/removed-list-cluster-operations

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/operations
This endpoint has been removed and always answers 410 Gone. Use `GET /api/v1/org/executions?cluster_id={cluster_id}` instead.

# Resolve a GitOps conflict
Source: https://docs.ankra.ai/api-reference/clusters/resolve-a-gitops-conflict

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/{cluster_id}/gitops/conflicts/resolve-resource
Records the resolution of one open GitOps conflict, named by its `resource_key` (`ankra cluster gitops conflicts resolve <key>`). `git` keeps the repository's version and overwrites the platform's; `cluster` keeps the platform's version and pushes it back to the repository. The call triggers a sync, which applies the choice and clears the conflict. Without `resolution` the conflict is cleared undecided and the sync re-evaluates it. Requires `clusters.write` on the cluster.

# Resolve a preserved GitOps path
Source: https://docs.ankra.ai/api-reference/clusters/resolve-a-preserved-gitops-path

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/{cluster_id}/gitops/preserved-paths/resolve
Records a decision on one preserved file, over the two sides the caller listed: git imports Git's content into the platform, cluster writes Ankra's version into Git and makes the file Ankra's again, none withdraws a decision that has not run yet. The next sync executes a decision; a git decision runs once every preserved file on the cluster has a decision, because the import reads Git at head, and an import the platform refuses (for example one that would lower an add-on's chart version) records why on the file and clears the decision. Nothing is written to Git by this call. Requires `clusters.write` on the cluster. Bearer-PAT twin of the browser route of the same name under /org.

# Resolve all GitOps conflicts
Source: https://docs.ankra.ai/api-reference/clusters/resolve-all-gitops-conflicts

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/{cluster_id}/gitops/conflicts/resolve
Records one resolution for every open GitOps conflict on the cluster (`ankra cluster gitops conflicts resolve --all`). `git` keeps the repository's version and overwrites the platform's; `cluster` keeps the platform's version and pushes it back to the repository. The call triggers a sync, which applies the choice and clears the conflicts. Without `resolution` the conflicts are cleared undecided and the sync re-evaluates them, recording again any that still conflict. Requires `clusters.write` on the cluster.

# Revoke the cluster's replaced DNS token
Source: https://docs.ankra.ai/api-reference/clusters/revoke-the-clusters-replaced-dns-token

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/dns-zone/token-rotation/revoke-previous
Asks Ankra to revoke the DNS write token the last rotation replaced. Call it only once the cluster publishes with the new token: a cluster still using the replaced token stops publishing when it is revoked. Idempotent once requested.

# Roll a cluster back to a resource version
Source: https://docs.ankra.ai/api-reference/clusters/roll-a-cluster-back-to-a-resource-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/resources/roll-to
Rolls a cluster's resource definitions back to an earlier saved version, identified by `cluster_id` and `version_id` in the body, and moves the cluster's current version to it. Requires `clusters.operate`; answers `{"ok": true}` on success.

# Rotate the cluster's DNS token
Source: https://docs.ankra.ai/api-reference/clusters/rotate-the-clusters-dns-token

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/dns-zone/token-rotation
Asks Ankra to replace the write token the cluster's external-dns uses to publish into its DNS zone. Ankra mints the replacement within about a minute and republishes the external-dns Secret; the replaced token stays valid until it is revoked, so the cluster keeps publishing meanwhile. Restart external-dns on the cluster so it reads the new Secret, confirm records still publish, then revoke the replaced token. Idempotent while a rotation is pending.

# Save a stack draft
Source: https://docs.ankra.ai/api-reference/clusters/save-a-stack-draft

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/stacks/draft
Saves a specification holding exactly one stack as a draft on the cluster without deploying it, and returns the draft id and version. Requires `stacks.write`; validation errors answer `422`.

# Search cluster log history in the selected store
Source: https://docs.ankra.ai/api-reference/clusters/search-cluster-log-history-in-the-selected-store

https://platform.ankra.app/openapi.json post /org/clusters/imported/{cluster_id}/logs/query
Session-authenticated historical search. Requires kubernetes.logs on this cluster. An explicit source never replaces a saved connection or changes shipping. Hosted reads remain pinned to the organisation and cluster.

# Set control plane self-heal
Source: https://docs.ankra.ai/api-reference/clusters/set-control-plane-self-heal

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/{cluster_id}/control-plane-self-heal
Turns the automatic restart of a NotReady control plane on or off for this cluster (`ankra cluster control-plane-heal enable|disable`). While it is on, Ankra restarts a control plane through the cloud provider when it has been NotReady for about ten minutes, every other control plane is Ready, and etcd keeps its quorum without it; it never stops, deprovisions or scales anything, and shows each restart and its outcome in the cluster's notifications and audit log. Turning it off leaves a NotReady control plane for you to handle. Every change is recorded in the organisation's audit log; re-sending the current value changes nothing. Requires `clusters.write` on the cluster.

# Set hosted log shipping
Source: https://docs.ankra.ai/api-reference/clusters/set-hosted-log-shipping

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/{cluster_id}/hosted-logs
Turns hosted log shipping on or off for this cluster (`ankra cluster logs-ship enable|disable`). While it is on and the hosted store is live, the cluster's agent sends the log lines of every running container to Ankra's hosted log store, where members of the organisation can search them; turning it off stops shipping within about a minute. Lines already stored age out with the store's retention. Every change is recorded in the organisation's audit log; re-sending the current value changes nothing. Requires `clusters.write` on the cluster.

# Set state snapshot retention
Source: https://docs.ankra.ai/api-reference/clusters/set-state-snapshot-retention

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/{cluster_id}/state-snapshot-retention
Sets the cluster's retention window for its scheduled etcd backups, in days between 1 and 90 (`ankra cluster state-snapshots retention --days N`). From the next retention pass on, Ankra keeps the newest backup of each UTC day within the window, on top of the four newest backups. A shorter window deletes the daily backups that fall outside it from the backup vault; a longer one keeps backups from then on and cannot bring back ones already deleted. The newest backup from before the cluster's last start and its last recovery incidents is kept whatever the window. Every change is recorded in the organisation's audit log; re-sending the current value changes nothing. Requires `clusters.write` on the cluster.

# Set the cluster agent's sizing
Source: https://docs.ankra.ai/api-reference/clusters/set-the-cluster-agents-sizing

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/{cluster_id}/agent/resources
Sets the agent container sizing Ankra holds for the cluster. Name any of memory_limit, memory_request, cpu_limit and cpu_request: a Kubernetes quantity holds the member, an empty string stops holding it (which does not change what the agent runs: it keeps its current value, carried through upgrades), and an absent member is unchanged. Limits take memory 512Mi-16Gi and CPU 100m-8; requests are capped at memory 128Mi-2Gi and CPU 50m-2 because the agent's old pod stops before its replacement schedules. Every later agent upgrade and every install command renders the held sizing; an online agent that accepts it re-renders its own release at once and restarts onto it. The bearer twin of `ankra cluster agent resources set`.

# Set what a cluster is for
Source: https://docs.ankra.ai/api-reference/clusters/set-what-a-cluster-is-for

https://platform.ankra.app/openapi.json put /org/clusters/{cluster_id}/criticality
Records the cluster's criticality, the denominator the insight scanner grades blast radius against. A production cluster reports exactly as it always has; a lower criticality needs a correspondingly larger blast radius before a finding reaches a severity that opens a ticket.

# Start a cluster
Source: https://docs.ankra.ai/api-reference/clusters/start-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/provision
Starts a stopped cluster, retries a start whose control plane never came up (the cluster `offline` or `provider_without_access`), or brings back parked workers with the default scope; any other state answers `409`. Pass `scope=control_plane` to start only the control plane (the default starts everything), and `restore_state=false` to boot an empty etcd instead of restoring a captured cluster state snapshot. By default a cluster whose stop deleted its VMs restores a restore already requested, otherwise the newest snapshot captured after its last start (the stop's own capture, otherwise the newest scheduled backup); an older one is restored only when named with `restore_snapshot_id`. A paused cluster keeps its etcd and gets no new restore, unless `restore_over_kept_etcd=true` is passed with `restore_snapshot_id` to confirm that the kept control-plane machines, and their etcd, are lost. The answer's `state_restore`, `state_snapshot` and `state_restore_message` say which snapshot is restored. Answers `409` when the cluster cannot be started in its current state.

# The persistent volumes deleting a Proxmox VE cluster removes
Source: https://docs.ankra.ai/api-reference/clusters/the-persistent-volumes-deleting-a-proxmox-ve-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/proxmox/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the disks the Proxmox CSI driver provisioned on the Proxmox storage, which `DELETE /api/v1/clusters/proxmox/{cluster_id}` deletes with the cluster. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none.

# Validate a cluster specification
Source: https://docs.ankra.ai/api-reference/clusters/validate-a-cluster-specification

https://platform.ankra.app/openapi.json post /api/v1/clusters/validate
Checks an ImportCluster specification without applying it and returns the errors and warnings an apply would hit: resource definitions, unique names, parent references and dependency cycles, chart references, and secret encryption. Pass `cluster_id` to validate against that cluster's current state, exactly as an update would.

# Withdraw a custom DNS zone from the cluster
Source: https://docs.ankra.ai/api-reference/clusters/withdraw-a-custom-dns-zone-from-the-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/{cluster_id}/custom-dns-zones/{zone}
Withdraws the declaration. The scheduler's next pass republishes the cluster's custom-dns stack without it, which removes the external-dns deployment; the zone itself and the records already published into it are untouched.

# Change a cost budget
Source: https://docs.ankra.ai/api-reference/cost/change-a-cost-budget

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-cost/budgets/{budget_id}
Changes a budget's name, amount, currency, owner or notify threshold; a field left out keeps its value and owner_user_id null clears the owner. A budget's scope never changes: naming scope_kind or scope_id is refused. Audited as update_cost_budget with what it replaced. Gated on billing.manage; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Change the cost autopilot policy
Source: https://docs.ankra.ai/api-reference/cost/change-the-cost-autopilot-policy

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-cost/autopilot
A partial policy write. defaults names only the environment kinds it changes; quiet_hours and notification_route_id change only when present, and null clears them; a field the policy does not have is refused (400). Needs billing.manage and clusters.write (at the organisation); the token stands in for the browser route's CSRF double-submit. The change and what it replaced are written to the audit log in the same transaction. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect. The policy answered lists the clusters of the scope project_id names, as the read does.

# Clean up a batch of cloud waste
Source: https://docs.ankra.ai/api-reference/cost/clean-up-a-batch-of-cloud-waste

https://platform.ankra.app/openapi.json post /api/v1/org/cloud-cost/waste/resolve-batch
Starts the cleanup of up to 100 cloud-waste findings at once, one operation per finding, and answers each finding's outcome: started with its operation, refused with the platform's own reason (resolved already, a cleanup running, no consent, not old enough, a kind Ankra does not remove, no clusters.write on a released persistent volume's cluster, or what that volume's live read showed), or failed when the cleanup could not be started. Each finding is decided exactly as the single resolve route decides it; the written consent and minimum age apply to every finding that needs them. Answers 200 when at least one started (partial: true when not all did) and 409, with the same results, when none did. Needs billing.manage. A token pinned to a project, or a member limited to projects, cleans up only the findings their waste read lists; any other is refused as not found. Bearer-PAT twin of the browser route of the same name under /org.

# Clean up one cloud-waste finding
Source: https://docs.ankra.ai/api-reference/cost/clean-up-one-cloud-waste-finding

https://platform.ankra.app/openapi.json post /api/v1/org/cloud-cost/waste/{finding_id}/resolve
Starts the cleanup of one open cloud-waste finding and answers the operation that does it (`ankra cost waste resolve`). What happens is decided by the kind of waste, never by the caller: a stopped server gets a snapshot image kept for seven days and is deleted only once the image is available; an unassigned IP or an idle load balancer is released. An unattached volume has no snapshot (the provider offers none), so it is deleted only with written consent in the body (`consent: delete_unattached_volume_acknowledged`, the value consent_by_kind names for the kind, or the generic `no_snapshot_acknowledged`) and only once it has been seen unattached for at least `min_unattached_days` (30, or more if asked): the consent is recorded on the finding and in the audit log, and the job re-reads the volume and refuses one attached again or delete-protected. A released persistent volume (released_pv) keeps its disk because its reclaim policy is Retain, so it is cleaned up the Kubernetes way: with the same written consent and minimum age, and with clusters.write on its cluster, the volume is read live from its cluster and, only when it is still Released and was created by a cloud provider's CSI driver that deletes the disks it provisioned, its reclaim policy is set to Delete (action reclaim_delete); the operation then waits for the volume to leave its cluster before the saving is counted. A pre-provisioned volume, one of another driver, one bound again, one already gone, or one that could not be read live is refused and left unchanged. The body is optional; without one no consent is given. Needs billing.manage. A token pinned to a project, or a member limited to projects, cleans up only the findings their waste read lists (stamped with their project, on a cluster they may read); any other answers 404. Bearer-PAT twin of the browser route of the same name under /org.

# Clear a cluster's cost autopilot tier
Source: https://docs.ankra.ai/api-reference/cost/clear-a-clusters-cost-autopilot-tier

https://platform.ankra.app/openapi.json delete /api/v1/org/cloud-cost/autopilot/clusters/{cluster_id}
Returns one cluster to its environment's default tier. Clearing a cluster with no override changes nothing and writes no audit row. The answer is the cluster's tier as it now stands. Needs billing.manage and clusters.write (at the cluster); the token stands in for the browser route's CSRF double-submit. The change and what it replaced are written to the audit log in the same transaction. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Clear a project's cost autopilot tier
Source: https://docs.ankra.ai/api-reference/cost/clear-a-projects-cost-autopilot-tier

https://platform.ankra.app/openapi.json delete /api/v1/org/cloud-cost/autopilot/projects/{project_id}
Returns a project's clusters to the organisation's defaults by removing the project's own autopilot defaults (ADR 0022). Clearing a project that set none changes nothing and writes no audit row. The answer is the project's layer as it now stands (empty). Needs billing.manage and clusters.write; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org.

# Clear a rate card
Source: https://docs.ankra.ai/api-reference/cost/clear-a-rate-card

https://platform.ankra.app/openapi.json delete /api/v1/org/cloud-cost/rate-cards/{credential_id}
Removes a stated card so its capacity falls back to the provider default, or becomes unpriced when the provider ships none. Gated on billing.manage. A token pinned to a project, or a member limited to projects, clears the cards of their own project's credentials only: the organisation fallback card and a credential no project owns are refused with 403, another project's credential answers 404; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Create a cost budget
Source: https://docs.ankra.ai/api-reference/cost/create-a-cost-budget

https://platform.ankra.app/openapi.json post /api/v1/org/cloud-cost/budgets
Adds a monthly budget for the organisation, one cluster, one environment label or one application. A scope holds at most one budget (409). Audited as create_cost_budget. Gated on billing.manage; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Delete a cost budget
Source: https://docs.ankra.ai/api-reference/cost/delete-a-cost-budget

https://platform.ankra.app/openapi.json delete /api/v1/org/cloud-cost/budgets/{budget_id}
Removes a budget; its card is no longer raised. Audited as delete_cost_budget. Gated on billing.manage; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Download the provider invoice lines for a month
Source: https://docs.ankra.ai/api-reference/cost/download-the-provider-invoice-lines-for-a-month

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/reconciliation.csv
Every billed line of the month's counted provider invoices as a CSV download, one row per line, for the same month and project scope as the reconciliation read and behind the same billing.read gate. Amounts stay in the provider's currency, in minor units, credits negative. An invoice two credentials of one provider account both imported is listed once, under the credential the reconciliation counts it under. On a one-project read only the lines placed on the project's clusters are listed. Text cells that would start a spreadsheet formula are prefixed with an apostrophe. Bearer-PAT twin of the browser route of the same name under /org.

# Estimate what a change to an application costs
Source: https://docs.ankra.ai/api-reference/cost/estimate-what-a-change-to-an-application-costs

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/cost/estimate
Prices a proposed change to an application as the monthly change to its cost. A change to one deployment - its replica count, its per-pod CPU and memory requests, parking it, or promoting a build into it - is read from its object cost projection and moved by the metering's own allocation rule; a new environment or a database preset is priced on the cluster it would run on as the share that cluster's latest metering pass would have allocated it, compute only, so a floor. The answer carries the confidence of the snapshot it is read from and how it was reached. A change Ankra cannot price (a namespace another application shares, a cluster with no recent snapshot or none recording its capacity yet, a parked deployment's size, a workload the cluster has no room for) answers priced false with the reason, never zero. Nothing is stored. Bearer-PAT twin of the browser route of the same name under /org.

# Every move on the cost line, named by what happened
Source: https://docs.ankra.ai/api-reference/cost/every-move-on-the-cost-line-named-by-what-happened

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/events
The events that moved the organisation's cost run rate over the last `days` UTC days (`ankra cost events`), newest first, in the caller's display currency: application releases (version changes in the clusters' resource graphs), node-count changes between adjacent priced hours, scheduled and manual stops and starts, executed cost decisions, clusters entering or leaving pricing, and resolved cloud waste. A snapshot-measured event carries window_delta_monthly_cents, how the cluster's run rate moved between the priced hour before it and the first priced hour at least 30 minutes after it; delta_monthly_cents is set only when the event was alone in that window, no other event on the cluster being measured across any of its hours (delta_status isolated). Events whose windows overlap by any span, identical or not, are shared: each carries its window's move and none claims a share of it. A start alone in a window whose run rate fell, or a stop alone in one whose run rate rose, is contradicted: something else moved it, so it carries the window's move and no delta of its own. metering_gap means the cluster was not priced for some hours inside the event's window (a start after a stop it was not metered through, a missed metering hour): the run rate either side of the gap is no move of the event's, so it carries neither delta, and an event whose window overlaps it is still shared. no_snapshots means no priced hour on one side, so the move is unknown, never zero. A coverage event's delta is coverage, not spend; a resolved finding's is its own monthly cost (own_cost), unknown (unpriced), or not_counted with no delta when other organisations also saw the resource and its cost counts in another organisation or in none. sources says which kinds could be read; a kind marked unavailable is missing from events, not quiet. At most 500 events (truncated). Bearer-PAT twin of the browser route of the same name under /org.

# Get a cluster's cost estimate
Source: https://docs.ankra.ai/api-reference/cost/get-a-clusters-cost-estimate

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/cost
A cluster's latest cost snapshot with its daily trend and namespace allocation, in the caller's display currency, or its readiness when no estimate exists yet (`ankra cost cluster`). Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Get a cluster's cost projection
Source: https://docs.ankra.ai/api-reference/cost/get-a-clusters-cost-projection

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/cluster/{cluster_id}
What one cluster costs: its run rate at the latest snapshot inside the window, its idle share, its share of the fleet, its open waste and 30 days of daily cost. Bearer-PAT twin of the browser route of the same name under /org.

# Get a cluster's namespace cost history
Source: https://docs.ankra.ai/api-reference/cost/get-a-clusters-namespace-cost-history

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/cost/namespaces/history
One cluster's namespace allocations over the window the metering keeps (35 days of hourly snapshots), in day buckets or, for at most 7 days, hour buckets, in the caller's display currency. Each bucket says how many of its hours the metering attributed to namespaces; a namespace's value for a bucket with none is null (unknown), never 0, and a namespace missing from an attributed hour was allocated nothing that hour. Nothing is extrapolated. Bearer-PAT twin of the browser route of the same name under /org.

# Get a credential's cost projection
Source: https://docs.ankra.ai/api-reference/cost/get-a-credentials-cost-projection

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/credential/{credential_id}
What one cloud credential costs: the run rate of the priced clusters it provisioned, resolved the way the fleet summary groups spend by credential, plus the open waste found with it, and the month so far of the clusters it provisioned that exist now, the sum of their own months. A cluster deleted this month is not counted: the month's records name no credential, and only live clusters are resolved to one. Bearer-PAT twin of the browser route of the same name under /org.

# Get a namespace's cost projection
Source: https://docs.ankra.ai/api-reference/cost/get-a-namespaces-cost-projection

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/namespace/{cluster_id}/{namespace}
What one namespace of a cluster costs: its allocation at the cluster's latest attributed metering pass, its share of the fleet and 30 days of daily allocation. A pass that attributed the cluster but not this namespace allocated it nothing; a pass that attributed no namespace leaves it unknown. Bearer-PAT twin of the browser route of the same name under /org.

# Get a stack's cost projection
Source: https://docs.ankra.ai/api-reference/cost/get-a-stacks-cost-projection

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/stack/{cluster_id}/{stack_name}
What one stack of a cluster costs: the allocations of the namespaces its cluster's latest metering pass attributes to it (a namespace two stacks claim is attributed to neither), its share of the fleet and 30 days of daily cost. Bearer-PAT twin of the browser route of the same name under /org.

# Get an application's cost projection
Source: https://docs.ankra.ai/api-reference/cost/get-an-applications-cost-projection

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/application/{application_id}
What one application costs across every namespace it is installed in. A namespace another application also runs in is marked shared and counted whole rather than split on no basis. Bearer-PAT twin of the browser route of the same name under /org.

# Get project cost
Source: https://docs.ankra.ai/api-reference/cost/get-project-cost

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/project/{project_id}
What one project costs: the run rate of the priced clusters it holds now, plus the open waste found on them, and what was spent under the project's stamp this month. A cluster that moved projects keeps what it spent where it was spent, and a cluster deleted this month stays in the month of the project it was in, so the month equals the project's by_project figure in the fleet summary. Bearer-PAT twin of the browser route of the same name under /org.

# Get the cloud cost settings
Source: https://docs.ankra.ai/api-reference/cost/get-the-cloud-cost-settings

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/settings
The organisation's stored cost settings, the display currency effective for the token's user, and the FX table (`ankra cost settings get`). Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Get the cost autopilot policy
Source: https://docs.ankra.ai/api-reference/cost/get-the-cost-autopilot-policy

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/autopilot
How much Ankra may do about cost unasked (`ankra cost autopilot`): the tier each environment kind defaults to, the quiet hours, the notification route kept with the policy (no notice is sent to it today), the four tiers with what each lets Ankra do, and every live cluster with its tier, whether an override or its environment set it, and the sentence a card shows for it. An organisation that never set a policy reads is_set false and Hands-off for every kind; recommended_defaults is the policy the Autopilot view offers to turn on. Any member can read it. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect. The clusters listed are those of one project - the one project_id names, else the caller's current project - that the caller may read; scope says what was read.

# Get the organisation's fleet cost rollup
Source: https://docs.ankra.ai/api-reference/cost/get-the-organisations-fleet-cost-rollup

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/summary
Every cluster whose latest snapshot is inside the staleness window, grouped by provider and by provisioning credential, in the caller's display currency (`ankra cost summary`). Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Get the provider invoice reconciliation for a month
Source: https://docs.ankra.ai/api-reference/cost/get-the-provider-invoice-reconciliation-for-a-month

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/reconciliation
What each cloud credential's provider billed for a month against what the metering estimated for the same clusters. Lines stay in the provider's currency; the estimate is converted at the stated rate. A credential with no imported document is absent, a failed import says so, a line nothing places on a cluster is listed with its amount, and a difference is stated only when the provider's figures are final and the clusters the metering fully covered hold at least half of the invoice; it is over those clusters, never the whole invoice, and difference_coverage says what share of the invoice and of the hours they hold. Bearer-PAT twin of the browser route of the same name under /org.

# List applications' cost projections
Source: https://docs.ankra.ai/api-reference/cost/list-applications-cost-projections

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/objects/application
Every application of the organisation with its cost projection in one call - the single application read's figures without the trend and the waste - and the fleet's run rate split into the namespaces applications run in (each once), the rest of the attributed clusters, and the clusters whose pass attributed no namespace. Bearer-PAT twin of the browser route of the same name under /org. Reads the applications of one project - the one project_id names, else the caller's current project - over the clusters the caller may read; scope says what was read.

# List open cloud waste findings
Source: https://docs.ankra.ai/api-reference/cost/list-open-cloud-waste-findings

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/waste
The organisation's open waste findings from the latest scan, with the credentials whose sweep failed so an incomplete scan never reads as zero waste. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# List the cost budgets
Source: https://docs.ankra.ai/api-reference/cost/list-the-cost-budgets

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/budgets
Every budget of the organisation, largest first, each with its month as of the read: spent so far, the projected month end at the current pace, the hour it crosses, and where it lands once the changes already approved or running have landed. Figures are in the budget's own currency; a scope with no priced cluster answers status unknown with null figures rather than zero. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# List the fleet's namespace allocations
Source: https://docs.ankra.ai/api-reference/cost/list-the-fleets-namespace-allocations

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/workloads
The latest namespace allocation of every analysed cluster, decorated with the stack, addons and applications running in each namespace, ordered by allocated monthly cost. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# List the private-capacity rate cards
Source: https://docs.ankra.ai/api-reference/cost/list-the-private-capacity-rate-cards

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/rate-cards
The private credentials the caller may read with the rates that price them, the organisation fallback card, the provider defaults, and how many of the private clusters the caller may read nothing prices yet. A token pinned to a project or a member limited to projects reads their project's credentials and clusters only, never another project's or a credential no project owns; a caller narrowed to the clusters they hold clusters.read on counts and prices those clusters only. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Measured outcomes of the organisation's cost decisions
Source: https://docs.ankra.ai/api-reference/cost/measured-outcomes-of-the-organisations-cost-decisions

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/ledger
The measured outcomes of the organisation's cost decisions (`ankra cost ledger`): every cost proposal that was approved, is running or has run, with what the surface expected it to save, what was measured seven days after it ran (the subject cluster's mean run rate over the week before the change minus its mean over the week after it, from cost snapshots, never an estimate; unmeasured when another measured change on the cluster overlaps it), where the measurement stands and why it could not be made, in the caller's display currency. measured_total_cents sums measured rows only; running_total_cents sums the expectations of approved, running and still-verifying changes, leaving out an approval older than seven days whose change never started (approval_expired on its row). Bearer-PAT twin of the browser route of the same name under /org.

# Price a cluster's current configuration for a what-if draft
Source: https://docs.ankra.ai/api-reference/cost/price-a-clusters-current-configuration-for-a-what-if-draft

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/{cluster_id}/cost/estimate
Prices what the cluster runs today - its node groups (from the machines Ankra provisioned, or the synced nodes grouped by pool) and load balancers - from the same price book or rate card the metering loop bills from, in the caller's display currency. The estimate echoes the baseline so a draft can start from it. Bearer-PAT twin of the browser route of the same name under /org.

# Price a what-if node-group draft against a cluster
Source: https://docs.ankra.ai/api-reference/cost/price-a-what-if-node-group-draft-against-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/{cluster_id}/cost/estimate
Prices a draft configuration - the full set of node groups the prototype cluster would run (count, vCPU, memory, disk, spot) and optionally its network resources - beside the cluster's current configuration, and predicts the monthly bill as the metered run rate plus the difference. In catalogue mode each group is placed on the cheapest published size that holds it (locked to the current size's CPU architecture); private capacity is priced per vCPU, GB of memory and GB of disk from the rate card. Nothing is stored. Bearer-PAT twin of the browser route of the same name under /org.

# Resolved cloud waste
Source: https://docs.ankra.ai/api-reference/cost/resolved-cloud-waste

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/waste/resolved
Totals what Ankra's cleanup resolved in the last `days` days (default 30, at most 90), by kind, in the caller's display currency: the monthly cost the resolved findings were billing. Only findings Ankra's cleanup resolved count; a finding the scan stopped seeing for another reason is not. A finding whose resource other organisations also saw, and whose cost counts in another organisation or in none, is counted in shared_not_counted_count instead. Unpriced findings are counted in unpriced_count and never summed as zero, and monthly_cost_cents is null when none was priced. Bearer-PAT twin of the browser route of the same name under /org.

# Savings model for the organisation
Source: https://docs.ankra.ai/api-reference/cost/savings-model-for-the-organisation

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/savings
The organisation's savings model: right-size and off-hours recommendations across the biggest priced clusters, the cost breakdowns they were read from, the clusters the fleet cannot price, and the waste scan, in the caller's display currency (`ankra cost savings`). One cluster counts once in the total, at its best lever. Bearer-PAT twin of the browser route of the same name under /org.

# Set a cluster's cost autopilot tier
Source: https://docs.ankra.ai/api-reference/cost/set-a-clusters-cost-autopilot-tier

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-cost/autopilot/clusters/{cluster_id}
Puts one cluster in a tier whatever its environment kind, with the reason a card shows (3 to 500 characters), until expires_at (omitted for no expiry; it must be in the future). It replaces the cluster's previous override. The answer is the cluster's tier as it now stands. Needs billing.manage and clusters.write (at the cluster); the token stands in for the browser route's CSRF double-submit. The change and what it replaced are written to the audit log in the same transaction. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Set a project's cost autopilot tier
Source: https://docs.ankra.ai/api-reference/cost/set-a-projects-cost-autopilot-tier

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-cost/autopilot/projects/{project_id}
Sets a project's autopilot tier per environment kind (ADR 0022), a layer between a cluster's override and the organisation's defaults: the body is {"defaults": {kind: tier, ...}} and is the whole layer, a kind it does not name falls through to the organisation. Needs billing.manage and clusters.write; the token stands in for the browser route's CSRF double-submit. The change and what it replaced are written to the audit log in the same transaction. Bearer-PAT twin of the browser route of the same name under /org.

# State a rate card
Source: https://docs.ankra.ai/api-reference/cost/state-a-rate-card

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-cost/rate-cards
Writes the monthly rates for one private credential, or the organisation fallback card. Gated on billing.manage. A token pinned to a project, or a member limited to projects, writes the cards of their own project's credentials only: the organisation fallback card and a credential no project owns are refused with 403, another project's credential answers 404; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# The fleet's run rate per day, with coverage drawn apart from spend
Source: https://docs.ankra.ai/api-reference/cost/the-fleets-run-rate-per-day-with-coverage-drawn-apart-from-spend

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-cost/trend
The organisation's cost run rate per UTC day over every priced cluster (`ankra cost trend`), in the caller's display currency. A cost snapshot exists only for an hour a cluster was priced, so a cluster missing from a day was not priced that day - it did not cost nothing. Each point says how many clusters it covers (priced_cluster_count, and fully_priced_cluster_count for those whose run rate is the whole cost, not a floor), and a day no cluster was priced has a null run rate. coverage_changes lists every day the set of priced clusters changed, naming the clusters that entered and left and what that moved the line by: a coverage move, never a spend move. The last point (current) is the summary's own run rate - each cluster's latest snapshot within 26 hours, deleted clusters out - so the line ends where GET /api/v1/org/cloud-cost/summary does; earlier points are each cluster's mean run rate over its snapshots of the UTC day, not its last hour. clusters carries each priced cluster's span over the window, when it was first priced (first_priced_exact false means the earliest priced hour still known, not necessarily the first), when it was created and deleted, its own run rate per day index-aligned with points (daily_monthly_cost_estimate_cents, null on a day it was not priced), so the line can be stacked by cluster, and what its current estimate leaves out (estimate_gaps). Bearer-PAT twin of the browser route of the same name under /org.

# Update the cloud cost settings
Source: https://docs.ankra.ai/api-reference/cost/update-the-cloud-cost-settings

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-cost/settings
Sets the effective discount and the organisation default currency (`ankra cost settings set`). Gated on billing.manage. The settings are the organisation's, every project's, so a token pinned to a project, or a member limited to projects, is refused with 403 whatever organisation role they also hold; the token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Create a registry project
Source: https://docs.ankra.ai/api-reference/credentials/create-a-registry-project

https://platform.ankra.app/openapi.json post /api/v1/org/registry-projects
Create an extra registry project for the organisation, private and under the same scan policy, retention policy and storage quota as its own. A robot account is bound to one project, so an extra project is how a login is given access to less than everything the organisation publishes. An organisation can hold up to extra_project_limit extra projects. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Create a registry robot
Source: https://docs.ankra.ai/api-reference/credentials/create-a-registry-robot

https://platform.ankra.app/openapi.json post /api/v1/org/registry-robots
Create a robot account on the organisation's Ankra registry project, with a preset scope (push, which pushes and pulls, or pull) or its own list of permissions, and optionally an expiry in days. The robot is a project-level robot: it reaches the organisation's project and no other. Stating permissions that reach past pull and push additionally needs the credentials.reveal permission. The secret is returned once, in this response, together with the docker login command that uses it; the login is stored as a platform-managed registry credential named ankra-harbor-robot-<name>. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Delete a credential
Source: https://docs.ankra.ai/api-reference/credentials/delete-a-credential

https://platform.ankra.app/openapi.json delete /api/v1/org/credentials/{credential_id}
Deletes a credential. A credential a cluster still uses is refused with 409, and a Git credential a cluster's GitOps binding still names can be refused unless `replacement_credential_id` re-points those bindings in the same delete. Requires `credentials.delete`.

# Delete a registry project
Source: https://docs.ankra.ai/api-reference/credentials/delete-a-registry-project

https://platform.ankra.app/openapi.json delete /api/v1/org/registry-projects/{project_name}
Delete an extra registry project. Nothing else is deleted on the way: a project that still holds repositories, or that robot accounts are still bound to, is refused with 409, and so is the organisation's own project. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Discover a registry connection
Source: https://docs.ankra.ai/api-reference/credentials/discover-a-registry-connection

https://platform.ankra.app/openapi.json post /api/v1/org/registry-connections/discover
Discover what an admin credential sees on a registry before any registry entry points at it: Ankra acts as the credential, over the same SSRF-guarded client the robot lane uses, and lists the projects (Harbor, up to 500 by name, truncated true past that) or the Docker repositories (Google Artifact Registry; only the named one when the URL names a repository) robots and registry entries can be made for. Nothing is written or minted. A connection that fails - the credential refused, the registry unreachable, a credential that cannot be used there, a Google URL naming no project, or a registry Ankra cannot make robots on - answers 200 with ok false, no projects and a sentence saying why. A credential the platform manages is refused (422). Requires credentials.write and credentials.reveal. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication, CSRF-guarded).

# Get a credential's rotation status
Source: https://docs.ankra.ai/api-reference/credentials/get-a-credentials-rotation-status

https://platform.ankra.app/openapi.json get /api/v1/org/credentials/{credential_id}/propagation
Reports where the credential's latest recorded rotation has got to in each cluster linked to it, and whether the old value is safe to revoke: safe_to_revoke is true once every running cluster whose copy Ankra renders serves the new value, and blocking_clusters names the rest. Stopped, not_covered and platform_only clusters do not block it and are still listed; a not_covered cluster carries the command that updates its copy by hand. A credential with no recorded rotation is safe to revoke only when no cluster is linked to it. The answer carries no secret material. Requires `credentials.read`.

# Get credential details
Source: https://docs.ankra.ai/api-reference/credentials/get-credential-details

https://platform.ankra.app/openapi.json get /api/v1/org/credentials/{credential_id}
Returns one credential including its decrypted secret material, and records the read in the audit log. Requires `credentials.reveal`; answers 404 when the credential does not exist. An SSH-key credential is the exception: it stores only a public key, which is not a secret, so its detail (the public key with its fingerprint, key type and comment, and the clusters it is attached to) answers on `credentials.read` and records no reveal.

# Get paid registry storage
Source: https://docs.ankra.ai/api-reference/credentials/get-paid-registry-storage

https://platform.ankra.app/openapi.json get /api/v1/org/registry-storage/addon
Read the organisation's paid registry storage: the storage blocks it holds on top of its base limit, the price of a block, the limit they make up, and whether more can be bought (available, billing_ready, billing_blocker). Requires credentials.read or billing.manage. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Get registry retention
Source: https://docs.ankra.ai/api-reference/credentials/get-registry-retention

https://platform.ankra.app/openapi.json get /api/v1/org/registry-storage/retention
Read which images the organisation keeps: its project-wide retention policy (or the platform default), its per-repository rules, the protections every organisation-set policy carries, when retention runs and when deleted images stop counting against storage. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Get registry storage
Source: https://docs.ankra.ai/api-reference/credentials/get-registry-storage

https://platform.ankra.app/openapi.json get /api/v1/org/registry-storage
Read the organisation's registry storage: the storage limit each of its registry projects carries, whether that limit is the platform default or one set for the organisation (and why), and how much each project holds. usage_status says whether the figures are complete, a lower bound (partial), unknown (the registry could not be read; used_bytes is then absent, never zero) or not_provisioned (no registry project yet). A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List a Bitbucket Cloud repository's branches
Source: https://docs.ankra.ai/api-reference/credentials/list-a-bitbucket-cloud-repositorys-branches

https://platform.ankra.app/openapi.json get /api/v1/org/bitbucket-cloud/{credential_id}/branches
Lists the branches of a Bitbucket Cloud repository through a stored Bitbucket Cloud credential, for the repository and branch pickers. The credential must belong to the caller's organisation, and a personal credential must be the caller's own; any other id answers 404. Every page Bitbucket returns is followed, and default_branch is the repository's main branch, or null for an empty repository. A listing that cannot be read whole is refused with a 422 rather than answered partially, including a repository with more than 5000 branches. A 422 whose remedy is reconnecting the credential carries detail {message, error_code: bitbucket_cloud_credential_invalid}; any other failure Bitbucket reports is a plain-string detail.

# List a Bitbucket Cloud repository's branches (browser session)
Source: https://docs.ankra.ai/api-reference/credentials/list-a-bitbucket-cloud-repositorys-branches-browser-session

https://platform.ankra.app/openapi.json get /org/bitbucket-cloud/{credential_id}/branches
Lists the branches of a Bitbucket Cloud repository through a stored Bitbucket Cloud credential, for the repository and branch pickers. The credential must belong to the caller's organisation, and a personal credential must be the caller's own; any other id answers 404. Every page Bitbucket returns is followed, and default_branch is the repository's main branch, or null for an empty repository. A listing that cannot be read whole is refused with a 422 rather than answered partially, including a repository with more than 5000 branches. A 422 whose remedy is reconnecting the credential carries detail {message, error_code: bitbucket_cloud_credential_invalid}; any other failure Bitbucket reports is a plain-string detail.

# List credentials
Source: https://docs.ankra.ai/api-reference/credentials/list-credentials

https://platform.ankra.app/openapi.json get /api/v1/org/credentials
Lists the organisation's credentials of every kind with their metadata, optionally filtered by `provider`. Requires `credentials.read`.

# List registry projects
Source: https://docs.ankra.ai/api-reference/credentials/list-registry-projects

https://platform.ankra.app/openapi.json get /api/v1/org/registry-projects
List the organisation's registry projects: its own first (named default), then the extra projects it created, each with how many repositories it holds and how many robot accounts are bound to it. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List registry providers
Source: https://docs.ankra.ai/api-reference/credentials/list-registry-providers

https://platform.ankra.app/openapi.json get /api/v1/org/registry-providers
List the registry providers robots can be made on and what each supports: Harbor (the Ankra registry and any integrated Harbor), Google Artifact Registry (pkg.dev and gcr.io hosts), and any other OCI registry, on which no robot can be made. Each states whether its robots can expire, whether custom permissions can be picked, the permission catalogue a create picks from, and what the admin credential's username looks like. Requires credentials.read. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List registry repositories by size
Source: https://docs.ankra.ai/api-reference/credentials/list-registry-repositories-by-size

https://platform.ankra.app/openapi.json get /api/v1/org/registry-storage/repositories
List every repository of the organisation's registry projects, largest first, with its image count, approximate size and last push, and the retention rule that governs it. CI build images live under ankra-ci/. Sizes count layers shared between images once per image, so they rank repositories but do not add up to the storage figure. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List the organisation's registry robots
Source: https://docs.ankra.ai/api-reference/credentials/list-the-organisations-registry-robots

https://platform.ankra.app/openapi.json get /api/v1/org/registry-robots
List every robot login the organisation holds: the robot accounts its members created on its Ankra registry project, then the ones Ankra manages (the organisation's ci and pull robots and one push robot per application, marked managed and read-only here). The answer also carries the registry project robots are minted on and the permissions a robot may be created with. Secrets are never listed. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List the repositories a credential covers
Source: https://docs.ankra.ai/api-reference/credentials/list-the-repositories-a-credential-covers

https://platform.ankra.app/openapi.json get /api/v1/org/credentials/{credential_id}/repositories
For a GitHub credential, lists the repositories its installation can reach, the repositories Ankra needs it to reach, and a verdict on the difference; other credential kinds answer 409. Requires `credentials.read`.

# Read a registry robot
Source: https://docs.ankra.ai/api-reference/credentials/read-a-registry-robot

https://platform.ankra.app/openapi.json get /api/v1/org/registry-robots/{robot_name}
Read one robot's record: its registry login, the projects it reaches, its permissions, when it was created and last rotated, and when it expires. A member's robot is read by its name; a robot Ankra manages by ci, pull, or app-<application id>. The secret is never returned here. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Revoke a registry robot
Source: https://docs.ankra.ai/api-reference/credentials/revoke-a-registry-robot

https://platform.ankra.app/openapi.json delete /api/v1/org/registry-robots/{robot_name}
Delete the robot on the registry and the credential holding its login. Anything still using the login stops working, which is the point of a revoke. A robot Ankra manages is refused with 409. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Rotate a credential's secret in place
Source: https://docs.ankra.ai/api-reference/credentials/rotate-a-credentials-secret-in-place

https://platform.ankra.app/openapi.json put /api/v1/org/credentials/{credential_id}
Replaces the credential's secret without recreating it, so clusters and other resources that reference it keep working. The supplied fields are probed against the provider first: a refused probe answers 200 with `rotated: false` and the probe's code, message and hints, and the stored secret is left unchanged. The new value is then read against every cluster that uses the credential (its network, then its servers): a cluster it cannot see refuses the rotation with code `foreign_project`, one that could not be checked with `cluster_unreachable`, both listed in `unreachable_clusters`; set `force` to save anyway. Connection settings cannot be rotated. Requires `credentials.write`; a credential pinned to another project answers 404.

# Rotate a registry robot's secret
Source: https://docs.ankra.ai/api-reference/credentials/rotate-a-registry-robots-secret

https://platform.ankra.app/openapi.json post /api/v1/org/registry-robots/{robot_name}/rotate
Mint a new secret for the robot and return it once. The previous secret stops working. A robot the registry no longer has is minted again under the same name with its recorded permissions and the rest of its lifetime. A rotation never extends a robot: an expired one, and a robot Ankra manages, are refused with 409. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Run registry retention now
Source: https://docs.ankra.ai/api-reference/credentials/run-registry-retention-now

https://platform.ankra.app/openapi.json post /api/v1/org/registry-storage/retention/run
Start the retention of every registry project of the organisation now instead of at its daily time. Deleted images stop counting against storage at the registry's next garbage collection. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Set or clear a credential display name
Source: https://docs.ankra.ai/api-reference/credentials/set-or-clear-a-credential-display-name

https://platform.ankra.app/openapi.json patch /api/v1/org/credentials/{credential_id}
Sets the credential's human label, or clears it with `null` or an empty string so the credential name shows again. The credential name, which other resources reference, never changes. An omitted `display_name` is refused with 422. A credential the platform manages is refused with 409. Requires `credentials.write`; a credential pinned to another project answers 404.

# Set paid registry storage
Source: https://docs.ankra.ai/api-reference/credentials/set-paid-registry-storage

https://platform.ankra.app/openapi.json put /api/v1/org/registry-storage/addon
Set how many paid storage blocks the organisation holds and apply the new limit to the registry at once. Each block adds block_gib GiB to every registry project's limit and is billed on the monthly invoice, prorated by the days held. Buying more needs billing that can pay (402 with a sentence saying what to fix on the Billing page; 503 when billing could not be checked). More than max_blocks, a decrease below what the registry holds, or a purchase while sales are paused answer 422 with the figures. A stale expected_version answers 409. Requires billing.manage. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication, CSRF header).

# Update registry retention
Source: https://docs.ankra.ai/api-reference/credentials/update-registry-retention

https://platform.ankra.app/openapi.json put /api/v1/org/registry-storage/retention
Change the organisation's project-wide retention policy (null resets it to the platform default), its repository rules (the list replaces the stored one; an empty list removes them all), or both, and apply the result to the registry at once. The newest image of every repository is always kept. harbor_applied false means the change is saved and applies on the next provisioning pass, within about five minutes. Send the version you read as expected_version: if someone changed the retention since, the save answers 409 and writes nothing. A change that needs more retention rules than the registry runs for one project (rule_slots in the read) answers 422 saying how many it needs, and writes nothing. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Validate credential name
Source: https://docs.ankra.ai/api-reference/credentials/validate-credential-name

https://platform.ankra.app/openapi.json get /api/v1/org/credentials/validate
Checks whether `credential_name` is valid and still free in the organisation, returning `valid`, a message, the name's RFC 1035 form and, when the conflicting credential is one you can see, its ID.

# Verify an integrated registry connection
Source: https://docs.ankra.ai/api-reference/credentials/verify-an-integrated-registry-connection

https://platform.ankra.app/openapi.json post /api/v1/org/registry-connections/verify
Check that an admin credential can manage robots on an integrated registry entry, before a robot is made there: Ankra acts as the credential and lists the projects (Harbor) or Docker repositories (Google Artifact Registry) robots can be bound to. Nothing is minted. A connection that fails - the credential refused, the registry unreachable, a credential that cannot be used there, or a registry Ankra cannot make robots on - answers 200 with ok false and a sentence saying why. Requires credentials.write and credentials.reveal. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication, CSRF-guarded).

# Create data source credential
Source: https://docs.ankra.ai/api-reference/data-source-credentials/create-data-source-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/datasource
Bearer token authentication; RBAC permission `credentials.write`. Creates the org-scoped credential the metrics and log data sources reference by credential_name; the secret is stored in Vault and never echoed.

# Create data source credential (browser session)
Source: https://docs.ankra.ai/api-reference/data-source-credentials/create-data-source-credential-browser-session

https://platform.ankra.app/openapi.json post /org/credentials/datasource
Browser session authentication; RBAC permission `credentials.write`. Creates the org-scoped credential the metrics and log data sources reference by credential_name; the secret is stored in Vault and never echoed.

# List data source credentials
Source: https://docs.ankra.ai/api-reference/data-source-credentials/list-data-source-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/datasource
Bearer PAT authentication; RBAC permission `credentials.read`. Returns credential metadata only; secret material is never returned.

# List data source credentials (browser session)
Source: https://docs.ankra.ai/api-reference/data-source-credentials/list-data-source-credentials-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/datasource
Browser session authentication; RBAC permission `credentials.read`. Returns credential metadata only; secret material is never returned.

# A decision proposal's activity feed
Source: https://docs.ankra.ai/api-reference/decisions/a-decision-proposals-activity-feed

https://platform.ankra.app/openapi.json get /api/v1/org/decisions/{decision_id}/activity
Everything that happened to the proposal, newest first: proposed, reopened, approved, set_aside, superseded, execution_started, dispatched, succeeded, failed, each with its actor, note and detail. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Approve a decision proposal
Source: https://docs.ankra.ai/api-reference/decisions/approve-a-decision-proposal

https://platform.ankra.app/openapi.json post /api/v1/org/decisions/{decision_id}/approve
Records the caller's approval of the plan they read, with an optional note. The body's plan_hash names that plan (the plan_hash the read answered): when the proposal holds another plan by now, because a surface re-posted it since, nothing is approved and the answer is 409 with error_code PLAN_DRIFTED and the proposal as it stands. An approval without plan_hash approves the plan the proposal holds when the request is read; it is accepted for clients released before plan_hash existed and will become required. Allowed from proposed, set_aside (re-opens it) and failed (approving again is the retry); a new decision clears the previous run's receipt. Gated on the area's permission: billing.manage for cost, security.manage for security. The token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Check decision proposals without filing them
Source: https://docs.ankra.ai/api-reference/decisions/check-decision-proposals-without-filing-them

https://platform.ankra.app/openapi.json post /api/v1/org/decisions/check
Answers, for each proposal, what POST /api/v1/org/decisions would answer it with now, and writes nothing: no proposal or activity event is created or changed, and no row or lock is held past the request. The proposals are judged as the caller, by the same validation and refusal logic the upsert runs, against the read replica, so a result can trail a write made a moment before. Each result is ok (the upsert would take it), refused with exactly the status code and body the upsert answers, or unknown when the check could not be evaluated; a client must not read unknown as ok. A check takes at most 24 proposals; a larger one is refused with 422 and nothing is checked. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Hold a decision
Source: https://docs.ankra.ai/api-reference/decisions/hold-a-decision

https://platform.ankra.app/openapi.json post /api/v1/org/decisions/{decision_id}/hold
Holds an approved proposal before it ran, with the caller's reason: a held proposal is run by nothing - neither the cost autopilot nor execute - until it is released or set aside. Allowed from approved. A cost approval older than seven days is refused with 409 (error_code approval_expired) and returned to proposed; a hold does not restart the seven days. The cost autopilot's pre-notice links here (ankra-cozgu.2.2.1). Gated on the area's permission: billing.manage for cost, security.manage for security. The token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# List the organisation's decision proposals
Source: https://docs.ankra.ai/api-reference/decisions/list-the-organisations-decision-proposals

https://platform.ankra.app/openapi.json get /api/v1/org/decisions
The organisation's Security and Cost proposals inside the caller's reach, newest first, narrowed by ?area= (security, cost) and ?status= (proposed, approved, set_aside, running, succeeded, failed, superseded); ?limit= caps the page (default 200, at most 500), and truncated says whether the cap cut it. Running proposals are settled against their platform operation before they are answered, and a cost approval whose change has not started within seven days of it, held or not, is returned to proposed (event approval_expired); a ladder between its waves counts from the wave it last verified. The reach (ADR 0022): a proposal is scoped through the project of the cluster its plan acts on (a waste_cleanup through its cloud waste finding's own project and cluster); a token pinned to a project and a member limited to projects reach their own project only; a caller whose clusters are narrowed by clusters.read (always a member limited to projects, anyone else where RBAC is enforced) reaches those clusters only; and a proposal anchored on no cluster of the organisation - a security proposal, or one whose plan and subject name different clusters - is reached only by a caller who reaches the whole organisation. Every other route answers a proposal outside the reach with 404, as if the organisation did not hold it. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Read one decision proposal
Source: https://docs.ankra.ai/api-reference/decisions/read-one-decision-proposal

https://platform.ankra.app/openapi.json get /api/v1/org/decisions/{decision_id}
One proposal with its plan, evidence, decision and receipt. A running proposal is settled first: the terminal status of its platform operation becomes succeeded or failed, with the outcome appended to the receipt. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Record a computed proposal (upsert by dedupe key)
Source: https://docs.ankra.ai/api-reference/decisions/record-a-computed-proposal-upsert-by-dedupe-key

https://platform.ankra.app/openapi.json post /api/v1/org/decisions
Records what a surface computed. The dedupe key is the proposal's identity within the organisation: a re-post refreshes a proposal nobody has decided and leaves a decided, running or finished one exactly as it was decided, so an approval is always of the plan the person saw; the one exception is a cost approval whose change has not started within seven days, which the re-post returns to proposed with the new computation (event approval_expired). An off_hours_schedule is also keyed by its subject.cluster_id, whichever dedupe key a surface files it under: filing one withdraws an undecided proposal of the same change under another key, or one whose approval expired (superseded, naming the new proposal), and is refused with 409 while one approved within the last seven days, one somebody held, or one that is running stands for it. Proposals of one change are filed one at a time, so two surfaces filing it at once never both stand. Only the right-size verification files a right_size_rollback: a proposal of that kind, or under a dedupe key starting with rollback: (the verification's rollback namespace), is refused with 400, so a re-post can neither file nor change one; a proposal the verification did not file that it finds under a right-size's rollback key is moved to <key>:displaced:<its id> (event dedupe_key_displaced) and the verification files its own. status "superseded" withdraws the proposal the dedupe key names instead; withdrawing one somebody approved or set aside erases that decision and takes the area's permission (403 otherwise). Any member who may write may propose; a scoped token needs the area's permission. Answers 201 when the dedupe key was new and 200 when it named an existing proposal. A caller confined to part of the organisation (see GET /api/v1/org/decisions) files, refreshes and withdraws only inside its reach: what it posts, the proposal its dedupe key names and every twin the filing would withdraw must be inside it, and any one outside answers 404, the same answer as a dedupe key the organisation does not hold. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Release a held decision
Source: https://docs.ankra.ai/api-reference/decisions/release-a-held-decision

https://platform.ankra.app/openapi.json post /api/v1/org/decisions/{decision_id}/release
Returns a held proposal to approved; one the cost autopilot filed runs on its next pass once its run_after has passed. Allowed from held. A cost proposal whose approval is older than seven days is refused with 409 (error_code approval_expired) and returned to proposed: a hold does not restart the seven days, so it runs only on a fresh approval against today's figures. A ladder between its waves counts from the wave it last verified. Gated on the area's permission: billing.manage for cost, security.manage for security. The token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Run an approved decision proposal
Source: https://docs.ankra.ai/api-reference/decisions/run-an-approved-decision-proposal

https://platform.ankra.app/openapi.json post /api/v1/org/decisions/{decision_id}/execute
Dispatches the platform operation the proposal's kind maps to (addon_upgrade rewrites the add-on's chart version in its stack; off_hours_schedule creates the stop and start power schedules; waste_cleanup files the platform cleanup job of the cloud waste finding, which snapshots a stopped server before deleting it, releases an unassigned IP or idle load balancer, deletes an unattached volume, and sets a released persistent volume to Delete (after reading it live, and with clusters.write on its cluster), both only with the written consent this request carries; right_size_ladder files its next wave as a right_size child proposal, approved by the caller, and runs it, staying running until that wave's verification concludes; how many nodes of a group one wave moves is the server's split of the wave's count, a plan's own canary split is taken only when it is no coarser, and the group is read before each wave so a count that is not the number of nodes it runs is refused) as the caller, and records the receipt. The proposal is answered as the run left it: running with its operation_id when there is a platform execution to wait on, succeeded when the operation finished inside the call, or failed with the refusal on its receipt. Only an approved proposal runs, and only once: a concurrent execute finds it running. A cost approval older than seven days whose change never started is refused with 409 (error_code approval_expired) and returned to proposed, so it runs only on a fresh approval. Gated on the area's permission: billing.manage for cost, security.manage for security. The token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect. A plan marked consent_required (at its top or under plan.parameters) runs only when the body carries consent "no_snapshot_acknowledged" or, for a waste_cleanup, the value naming its finding's kind (consent_by_kind on the waste consent policy); without it the answer is 422 with error_code consent_required and the proposal stays approved.

# Set a decision proposal aside
Source: https://docs.ankra.ai/api-reference/decisions/set-a-decision-proposal-aside

https://platform.ankra.app/openapi.json post /api/v1/org/decisions/{decision_id}/set-aside
Records that the caller declined the proposal, with their reason. Allowed from proposed, approved or held (withdraws the approval before anything ran) and failed. Gated on the area's permission: billing.manage for cost, security.manage for security. The token stands in for the browser route's CSRF double-submit. Bearer-PAT twin of the browser route of the same name under /org; the console's session cookie is not accepted here and the browser route answers a token with a login redirect.

# Get an application's deploy provenance mode
Source: https://docs.ankra.ai/api-reference/deploy-provenance/get-an-applications-deploy-provenance-mode

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/provenance-policy
The deploy provenance mode the application's deploys use and where it came from: the application's own choice, the organisation's default, or Ankra's default. Requires pipelines.read.

# Get the organisation's deploy provenance default
Source: https://docs.ankra.ai/api-reference/deploy-provenance/get-the-organisations-deploy-provenance-default

https://platform.ankra.app/openapi.json get /api/v1/org/provenance/policy
The deploy provenance mode applications follow when they choose none. Null means the organisation chose no default, so Ankra's applies: off for an application created before verified provenance shipped, warn for one created since. Requires pipelines.read.

# List the organisation's provenance signing keys
Source: https://docs.ankra.ai/api-reference/deploy-provenance/list-the-organisations-provenance-signing-keys

https://platform.ankra.app/openapi.json get /api/v1/org/provenance/keys
Every generation of the key the organisation's pipelines sign provenance with, oldest first: the active one signs, trusted ones still verify, revoked ones verify nothing. The public keys verify an attestation by hand with cosign verify-attestation --type predicate_type. Listing never creates a key. Requires pipelines.read.

# Revoke a provenance signing key
Source: https://docs.ankra.ai/api-reference/deploy-provenance/revoke-a-provenance-signing-key

https://platform.ankra.app/openapi.json post /api/v1/org/provenance/keys/revoke
Revokes one key generation: nothing it signed verifies from then on, so an enforcing application refuses every image it attested until it is published again. Revoking the active key makes the next attestation create a successor. Revoking a revoked key changes nothing. Recorded in the audit log. Requires security.manage.

# Rotate the organisation's provenance signing key
Source: https://docs.ankra.ai/api-reference/deploy-provenance/rotate-the-organisations-provenance-signing-key

https://platform.ankra.app/openapi.json post /api/v1/org/provenance/keys/rotate
Creates the next key generation, which signs every attestation from then on. Older generations keep verifying what they signed until they are revoked, so images published before the rotation still deploy. Recorded in the audit log. Requires security.manage.

# Set an application's deploy provenance mode
Source: https://docs.ankra.ai/api-reference/deploy-provenance/set-an-applications-deploy-provenance-mode

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/provenance-policy
Stores the application's own deploy provenance mode: off, warn (deploy and file a finding for an image without verified provenance) or enforce (refuse such a deploy and pin verified images to their digest). A mode of null clears the choice, so the application follows the organisation's default. Recorded in the audit log. Requires security.manage.

# Set the organisation's deploy provenance default
Source: https://docs.ankra.ai/api-reference/deploy-provenance/set-the-organisations-deploy-provenance-default

https://platform.ankra.app/openapi.json put /api/v1/org/provenance/policy
Stores the deploy provenance mode applications follow when they choose none: off, warn or enforce. A mode of null clears the default. Recorded in the audit log. Requires security.manage.

# Verify images against an application's provenance policy
Source: https://docs.ankra.ai/api-reference/deploy-provenance/verify-images-against-an-applications-provenance-policy

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/provenance/verify
A dry-run: checks each image exactly as the application's deploy would - signed provenance from this organisation's pipeline, a trusted key, this application, a gate that passed the digest - and answers what a deploy under the application's mode would do. Nothing is deployed, no finding is filed and no key is created. Images outside the application's registry are reported, never judged. Requires pipelines.read.

# Create a host join token
Source: https://docs.ankra.ai/api-reference/deploy-targets/create-a-host-join-token

https://platform.ankra.app/openapi.json post /api/v1/org/environments/{environment_name}/host-join-tokens
Mints a single-use token a host registers with (`ankra targets register`), creating the environment when the organisation has none of that name. The token is in this answer exactly once and only its hash is stored. Requires pipelines.manage.

# Get a deployment
Source: https://docs.ankra.ai/api-reference/deploy-targets/get-a-deployment

https://platform.ankra.app/openapi.json get /api/v1/org/deployments/{deployment_id}
One deployment with the outcome on each host target it went to. Requires pipelines.read.

# Get a host target
Source: https://docs.ankra.ai/api-reference/deploy-targets/get-a-host-target

https://platform.ankra.app/openapi.json get /api/v1/org/host-targets/{host_target_id}
One host target with its derived status and what the host last reported about itself. Requires pipelines.read.

# Get the release signing key
Source: https://docs.ankra.ai/api-reference/deploy-targets/get-the-release-signing-key

https://platform.ankra.app/openapi.json get /api/v1/org/release-signing-key
The public key the organisation's releases are signed with, which a host pins at registration. Answers configured false while the organisation has no key; a key that could not be read is a 500, never that answer. Requires pipelines.read.

# List deployments
Source: https://docs.ankra.ai/api-reference/deploy-targets/list-deployments

https://platform.ankra.app/openapi.json get /api/v1/org/deployments
The releases a pipeline deploy stage sent to host targets, newest first by keyset, optionally narrowed to an environment or a pipeline repository. Requires pipelines.read.

# List environments
Source: https://docs.ankra.ai/api-reference/deploy-targets/list-environments

https://platform.ankra.app/openapi.json get /api/v1/org/environments
The organisation's deploy environments by name. An environment is created by the first host join token minted for it. Requires pipelines.read.

# List host targets
Source: https://docs.ankra.ai/api-reference/deploy-targets/list-host-targets

https://platform.ankra.app/openapi.json get /api/v1/org/host-targets
The organisation's host targets, active ones first and revoked ones after, optionally narrowed to one environment. Requires pipelines.read.

# Revoke a host target
Source: https://docs.ankra.ai/api-reference/deploy-targets/revoke-a-host-target

https://platform.ankra.app/openapi.json post /api/v1/org/host-targets/{host_target_id}/revoke
Revokes a host target: its identity token and every session stop working, it is offered no further deploy jobs, and its name is free for a replacement host. Releases already on the host keep running. Revoking a revoked target changes nothing. Requires pipelines.manage.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/vms
Adds a standalone VM with the given `name` and `instance_type` on the cluster network; its location defaults to the bastion's. On a running cluster its creation starts at once and the result carries the `operation_id`; on a stopped cluster it is created at the next start. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Add node group
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/node-groups
Adds a worker node group with the given `name`, `instance_type` and `count` (default 1), plus optional labels, taints and autoscaling settings. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Create a DigitalOcean cluster
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/create-a-digitalocean-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean
Creates a DigitalOcean cluster from the request and starts provisioning it in the background, answering 201 with the new cluster's `cluster_id` and `name`. A configuration that fails validation answers 400 with the reason, and an organisation whose billing is restricted is refused with 402.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/digitalocean/{cluster_id}/vms/{vm_id}
Deletes a standalone VM: it is handed to teardown and its server is removed at the provider. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Delete node group
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/digitalocean/{cluster_id}/node-groups/{group_name}
Removes a node group by draining and deleting its workers one at a time through their PodDisruptionBudgets; a worker whose drain is refused stays in service and the operation fails with the reason. Pass `force_drain=true` to take the whole group down regardless. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result. Requires `clusters.delete`.

# Deprovision a DigitalOcean cluster
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/deprovision-a-digitalocean-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/digitalocean/{cluster_id}
Deletes the cluster and its cloud resources. A delete that would remove persistent volumes, or cannot tell whether it does, is refused with 409 unless `accept_volume_data_loss=true` is passed (see the deprovision-volumes read); `force=true` tolerates infrastructure that can no longer be reached. Active operations on the cluster are cancelled and the response carries the teardown's `operation_id`.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `digitalocean_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself.

# Get bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/get-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.read`. Returns the cluster's stored bastion SSH source allowlist, as the update on the same path stored it. `configured` tells a cleared list (true, empty) from one that was never set (false, empty); both leave SSH open from anywhere.

# Get current Kubernetes version
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/get-current-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/k8s-version
Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Get current worker count
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/get-current-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/worker-count
Returns the cluster's current worker count and the minimum and maximum it can be scaled to.

# Get disabled K3s components
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/get-disabled-k3s-components

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/k3s-disabled-components
Read the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), on top of the provider shape's own defaults. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states (a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider) answer 409 with a detail message.

# Latest restorable state snapshot of a DigitalOcean cluster
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/latest-restorable-state-snapshot-of-a-digitalocean-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the DigitalOcean cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List available DigitalOcean droplet sizes
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/list-available-digitalocean-droplet-sizes

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/sizes
Lists DigitalOcean droplet sizes for the credential in `credential_id` with vCPUs, memory, disk, monthly price and regions; with `region` set, sizes not offered there are marked unavailable.

# List available DigitalOcean regions
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/list-available-digitalocean-regions

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/regions
Lists the DigitalOcean regions visible to the DigitalOcean credential given in `credential_id`, with each region's availability and the droplet sizes it offers.

# List node groups
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/node-groups
Lists the cluster's worker node groups with each group's instance type, node count, autoscaling bounds, labels and taints.

# List nodes
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/nodes
Lists the cluster's machines with each one's role, node group, instance type, location, state, private and public IPs, the kubelet version it reports and, where recorded, the provider's own status.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/vms
Lists the cluster's standalone VMs (servers on the cluster network that are not Kubernetes nodes) with their instance type, location, state, addresses and provider ID.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/control-plane
Returns the control-plane count, the counts the cluster supports, the control planes' instance type, and whether a count or instance-type change is possible right now, with the reason when it is not.

# Read node
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/nodes/{node_id}
Returns one machine of the cluster with its definition, its latest recorded info and data, and its dependencies and relationships. Answers 404 when the node is not part of the cluster.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `digitalocean_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/access-info
Returns what you need to reach the cluster's machines over SSH: the bastion's public IP, the control-plane IPs and the cluster name.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/ssh-keys
Returns the SSH key credentials authorised on the cluster's servers (`ssh_key_credential_ids`) and the organisation's SSH key credentials that can be attached.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/vms/{vm_id}/instance-type
Resizes a standalone VM in place to the given `instance_type`. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/control-plane/instance-type
Changes the instance type of every control plane. On a running cluster the control planes are resized one at a time behind an etcd quorum check and a drain, and the response carries the `operation_id` to follow (clusters with fewer than three control planes are refused); on a stopped cluster the new type is applied at the next start and no operation is returned.

# Resize node group
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/node-groups/{group_name}/instance-type
Changes the instance type of every worker in the node group. Each node is power-cycled, so the workers are drained and resized in bounded batches; `force_drain` bypasses PodDisruptionBudgets for that drain. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/ssh-keys/resync
Re-applies the cluster's configured SSH keys to its servers and returns the IDs of the resources queued for the update.

# Scale DigitalOcean cluster workers
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/scale-digitalocean-cluster-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/scale-workers
Sets the cluster's worker count to `worker_count` and returns the previous and new counts. A scale-down drains the removed workers through their PodDisruptionBudgets unless `force_drain` is true. Requires `clusters.operate`.

# Scale node group
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/node-groups/{group_name}/scale
Sets the node group's node count to `count`. A scale-down drains the removed workers through their PodDisruptionBudgets; `force_drain` bypasses them for this request. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Start a DigitalOcean cluster
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/start-a-digitalocean-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/start
Recreate the DigitalOcean cloud resources for a stopped cluster and reconcile it back to a running state.

# Stop a DigitalOcean cluster
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/stop-a-digitalocean-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/stop
Initiate async deletion of DigitalOcean cloud resources (droplets, VPCs, firewalls, SSH keys) without removing the cluster from the database.

# The persistent volumes deleting a DigitalOcean cluster removes
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/the-persistent-volumes-deleting-a-digitalocean-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/digitalocean/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/digitalocean/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none.

# Update bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/update-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.write`. Replaces the cluster's bastion SSH source allowlist and dispatches the bastion update that applies it: the bastion's SSH port then accepts only the listed IPv4 sources, the platform's own egress addresses and private network sources, and drops everything else. An empty list clears the allowlist. Clusters that never set one keep SSH open from anywhere.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/control-plane
Changes the number of control planes to `count`. On a running cluster the control plane can only grow, and the new control planes join live (`mode` `rolling`, with an `operation_id` to follow); a reduction is applied offline to a stopped cluster and takes effect at its next start.

# Update disabled K3s components
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/update-disabled-k3s-components

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/k3s-disabled-components
Replace the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), for example ["traefik"] on a cluster that brings its own ingress. k3s distribution only. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states answer 409 with a detail message: a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider, a list that drops a stored entry (re-enabling a bundled component is not supported yet, so the list only grows), a list that adds coredns (load-bearing for in-cluster DNS), and any change while a node update, version upgrade or node restart is in progress on the cluster.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/node-groups/{group_name}/labels
Replaces the Kubernetes labels on every node in the node group with the given `labels` map. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/node-groups/{group_name}/taints
Replaces the taints on every node in the node group with the given `taints` list (each a `key`, an optional `value` and an `effect` of `NoSchedule`, `PreferNoSchedule` or `NoExecute`). By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/digitalocean/{cluster_id}/ssh-keys
Replaces the SSH key credentials authorised on the cluster's servers with `ssh_key_credential_ids` and starts rolling the keys out. An unknown or repeated credential, or two credentials carrying the same public key, is refused with 409.

# Upgrade Kubernetes version
Source: https://docs.ankra.ai/api-reference/digitalocean-clusters/upgrade-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/digitalocean/{cluster_id}/upgrade-k8s-version
Upgrades the cluster to `target_version`, which must be in the supported version catalogue and must not downgrade or skip a minor version. The cluster must be online with no change in progress; the nodes are upgraded as a rolling operation whose `operation_id` is returned, and `force` continues past a node drain that PodDisruptionBudgets refuse.

# Create a DigitalOcean API credential
Source: https://docs.ankra.ai/api-reference/digitalocean-credentials/create-a-digitalocean-api-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/digitalocean
Creates a DigitalOcean API credential from `name` and `api_token`. The token is checked against the DigitalOcean API before it is stored in Vault; an invalid token answers 400. Requires `credentials.write`; answers 201.

# Create an SSH key credential
Source: https://docs.ankra.ai/api-reference/digitalocean-credentials/create-an-ssh-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/digitalocean/ssh-key
Creates an SSH key credential from `name` and either `ssh_public_key` or `generate=true`; a generated RSA-4096 key pair's private key is returned once, in this response. A public key the organisation already stores under another credential is refused with 400. Requires `credentials.write`; answers 201.

# Get DigitalOcean credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/digitalocean-credentials/get-digitalocean-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/digitalocean/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the DigitalOcean API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get DigitalOcean credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/digitalocean-credentials/get-digitalocean-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/digitalocean/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the DigitalOcean limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# List DigitalOcean API credentials
Source: https://docs.ankra.ai/api-reference/digitalocean-credentials/list-digitalocean-api-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/digitalocean
Lists the organisation's DigitalOcean API credentials with their metadata; the secret material is never returned.

# List SSH key credentials
Source: https://docs.ankra.ai/api-reference/digitalocean-credentials/list-ssh-key-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/digitalocean/ssh-keys
Lists the organisation's SSH key credentials. The list is the same under every cloud provider. Each item carries the stored public key with the fingerprint (as `ssh-keygen -l` prints it), key type and comment derived from it; a stored value that is not a readable key keeps its row, with a null `fingerprint` and `fingerprint_error` saying why.

# Create a DNS credential
Source: https://docs.ankra.ai/api-reference/dns-credentials/create-a-dns-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/dns
Bearer token authentication; RBAC permission `credentials.write`. Creates the org-scoped credential a cluster's custom DNS zones reference by credential_name. The webhook provider url carries the DNS provider's token, so it is stored in Vault and never echoed.

# List DNS credentials
Source: https://docs.ankra.ai/api-reference/dns-credentials/list-dns-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/dns
Bearer PAT authentication; RBAC permission `credentials.read`. Returns credential metadata only; the webhook provider url is never returned.

# Create an organisation DNS record
Source: https://docs.ankra.ai/api-reference/dns/create-an-organisation-dns-record

https://platform.ankra.app/openapi.json post /api/v1/org/dns/records
Adds a CNAME, A, AAAA or TXT record under the organisation's DNS zone, where `name` is the label in front of the zone. An AAAA record takes an IPv6 address and needs the zone on Ankra Cloud. Organisation admins only. The record is published asynchronously and starts in the `pending` state; answers 400 when the zone is not active yet or the record conflicts with an existing one.

# Declare a custom DNS zone for every cluster in the organisation
Source: https://docs.ankra.ai/api-reference/dns/declare-a-custom-dns-zone-for-every-cluster-in-the-organisation

https://platform.ankra.app/openapi.json post /api/v1/org/custom-dns-zones
The DNS zones every cluster in the organisation serves with the organisation's own external-dns webhook credential, alongside the delegated zone Ankra serves itself. A zone declared here behaves like the generated domain: each cluster - the ones that exist and the ones created later - gets its own external-dns deployment for it, pinned to that zone with its own cluster-derived txt owner id. A cluster's own declaration of the same zone (the per-cluster custom-dns-zones route) takes precedence over the organisation-wide one on that cluster. A zone that overlaps the zone Ankra already serves for the organisation - its delegated zone on the shared platform root, or the whole domain when a custom Ankra domain is registered - is refused with 400.

# Delete an organisation DNS record
Source: https://docs.ankra.ai/api-reference/dns/delete-an-organisation-dns-record

https://platform.ankra.app/openapi.json delete /api/v1/org/dns/records/{record_id}
Marks the record for deletion and answers 204; it is removed from DNS asynchronously. Organisation admins only.

# Get the organisation's DNS zone
Source: https://docs.ankra.ai/api-reference/dns/get-the-organisations-dns-zone

https://platform.ankra.app/openapi.json get /api/v1/org/dns/zone
Returns the organisation's own delegated DNS zone, its FQDN and provisioning state; the state is `none` when the organisation has no zone yet. Record names created through this API hang off this zone.

# List Cloud DNS zones in the authenticated organisation
Source: https://docs.ankra.ai/api-reference/dns/list-cloud-dns-zones-in-the-authenticated-organisation

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-dns/zones
Lists zones in the Cloud account linked to the authenticated Platform organisation. Requires members.read.

# List organisation DNS records
Source: https://docs.ankra.ai/api-reference/dns/list-organisation-dns-records

https://platform.ankra.app/openapi.json get /api/v1/org/dns/records
Lists the CNAME, A, AAAA and TXT records the organisation manages under its own DNS zone, with each record's publishing state. Any organisation member can read them.

# List the organisation's cluster DNS zones
Source: https://docs.ankra.ai/api-reference/dns/list-the-organisations-cluster-dns-zones

https://platform.ankra.app/openapi.json get /api/v1/org/dns/cluster-zones
List every cluster-level DNS domain in the organisation with its reconciliation state - the inventory an administrator clears before changing the organisation's dns_root_domain.

# List the organisation's custom DNS zones
Source: https://docs.ankra.ai/api-reference/dns/list-the-organisations-custom-dns-zones

https://platform.ankra.app/openapi.json get /api/v1/org/custom-dns-zones
The DNS zones every cluster in the organisation serves with the organisation's own external-dns webhook credential, alongside the delegated zone Ankra serves itself. A zone declared here behaves like the generated domain: each cluster - the ones that exist and the ones created later - gets its own external-dns deployment for it, pinned to that zone with its own cluster-derived txt owner id. A cluster's own declaration of the same zone (the per-cluster custom-dns-zones route) takes precedence over the organisation-wide one on that cluster.

# Read a proxied zone access policy
Source: https://docs.ankra.ai/api-reference/dns/read-a-proxied-zone-access-policy

https://platform.ankra.app/openapi.json get /api/v1/org/cloud-dns/zones/{zone_id}/access
Reads the effective policy for a zone owned by the authenticated organisation's Cloud account. Requires members.read.

# Set a proxied zone access policy
Source: https://docs.ankra.ai/api-reference/dns/set-a-proxied-zone-access-policy

https://platform.ankra.app/openapi.json put /api/v1/org/cloud-dns/zones/{zone_id}/access
Sets public or organisation-only access for a Cloud proxied zone. Optional roles restrict access to matching active members. Requires members.manage; Cloud checks account ownership and DNS bypass rules.

# Update an organisation DNS record
Source: https://docs.ankra.ai/api-reference/dns/update-an-organisation-dns-record

https://platform.ankra.app/openapi.json patch /api/v1/org/dns/records/{record_id}
Changes a record's `content` and, when given, its `ttl`; the name and record type cannot change. Organisation admins only. The record returns to `pending` until the change is published.

# Verify the organisation's custom DNS zones
Source: https://docs.ankra.ai/api-reference/dns/verify-the-organisations-custom-dns-zones

https://platform.ankra.app/openapi.json get /api/v1/org/custom-dns-zones/verification
Probes what public DNS answers today for every custom DNS zone the organisation declares - organisation-wide and bound to single clusters - and reports an honest three-state verdict per zone: verified, misconfigured with the observed-vs-expected facts, or unknown when a probe could not be completed. Read-only end to end: it verifies what the customer's DNS resolves and names the record they would need to create themselves; it never writes DNS records anywhere.

# Withdraw an organisation-wide custom DNS zone
Source: https://docs.ankra.ai/api-reference/dns/withdraw-an-organisation-wide-custom-dns-zone

https://platform.ankra.app/openapi.json delete /api/v1/org/custom-dns-zones/{zone}
Withdraws the organisation-wide declaration. The scheduler's next pass republishes every affected cluster's custom-dns stack without it, which removes those external-dns deployments; clusters that declared the zone themselves keep it, and the zone and the records already published into it are untouched.

# Cancel a batch of executions
Source: https://docs.ankra.ai/api-reference/executions/cancel-a-batch-of-executions

https://platform.ankra.app/openapi.json post /api/v1/org/executions/cancel
Cancels each execution in `execution_ids` that is still running, and reports which ids were cancelled, which were not found in the organisation and which were not running.

# Cancel a step within an execution
Source: https://docs.ankra.ai/api-reference/executions/cancel-a-step-within-an-execution

https://platform.ankra.app/openapi.json post /api/v1/org/executions/{execution_id}/steps/{step_id}/cancel
Cancels one pending, blocked or running step of an execution; the step moves to `cancelling`. Answers 409 when the step is in any other state.

# Cancel an execution
Source: https://docs.ankra.ai/api-reference/executions/cancel-an-execution

https://platform.ankra.app/openapi.json post /api/v1/org/executions/{execution_id}/cancel
Cancels the execution if it is still running and returns its resulting status; an execution that already finished is left unchanged. Answers 404 when the execution does not belong to the organisation.

# Get execution detail
Source: https://docs.ankra.ai/api-reference/executions/get-execution-detail

https://platform.ankra.app/openapi.json get /api/v1/org/executions/{execution_id}
Returns one execution with its steps and their status. Answers 404 when the execution does not belong to the organisation.

# Get execution status events
Source: https://docs.ankra.ai/api-reference/executions/get-execution-status-events

https://platform.ankra.app/openapi.json get /api/v1/org/executions/{execution_id}/events
Returns the execution's step status changes in chronological order, each with the step id, status and time.

# Get execution step results
Source: https://docs.ankra.ai/api-reference/executions/get-execution-step-results

https://platform.ankra.app/openapi.json get /api/v1/org/executions/{execution_id}/result
Returns the result payload recorded by each of the execution's steps, oldest first.

# List execution steps
Source: https://docs.ankra.ai/api-reference/executions/list-execution-steps

https://platform.ankra.app/openapi.json get /api/v1/org/executions/{execution_id}/steps
Returns the execution's steps as a list, each with its status. Answers 404 when the execution does not belong to the organisation.

# List executions
Source: https://docs.ankra.ai/api-reference/executions/list-executions

https://platform.ankra.app/openapi.json get /api/v1/org/executions
Returns a page of the organisation's executions, newest first, filterable by cluster, scope, status, target resource and attention state. Internal executions and silent reconciles are left out unless `include_internal_executions` or `include_silent_reconciles` is set; an unknown `cluster_id` answers 404.

# Retry a terminal execution
Source: https://docs.ankra.ai/api-reference/executions/retry-a-terminal-execution

https://platform.ankra.app/openapi.json post /api/v1/org/executions/{execution_id}/retry
Starts a new execution that repeats a failed, cancelled or critical execution's steps, and returns the new execution. Answers 409 when the execution is in any other state, when none of its steps has a target resource left to act on, when one of its steps is still running or cancelling, or while any execution in its retry tree (the execution it was retried from, every retry of that one, and their retries) is still live: one retry tree has at most one live execution.

# Create a Helm registry
Source: https://docs.ankra.ai/api-reference/helm/create-a-helm-registry

https://platform.ankra.app/openapi.json post /api/v1/org/helm/registries
Adds an HTTP or OCI Helm registry to the organisation, optionally authenticated with an existing registry credential. Naming a credential the organisation holds also requires credentials.reveal, because the registry is then reached with that credential at the URL the caller chose; without it the create answers 403 "Using a stored credential for a registry needs permission to reveal credentials." Validation problems (duplicate name or URL, unknown credential) come back in the `errors` list with a 200 status.

# Create a registry credential
Source: https://docs.ankra.ai/api-reference/helm/create-a-registry-credential

https://platform.ankra.app/openapi.json post /api/v1/org/helm/credentials
Stores a username and password as a named credential that a Helm registry can reference by `credential_name`. Validation problems, such as a duplicate name, come back as `success: false` with an `errors` list rather than an error status.

# Delete a Helm registry
Source: https://docs.ankra.ai/api-reference/helm/delete-a-helm-registry

https://platform.ankra.app/openapi.json delete /api/v1/org/helm/registries/{registry_name}
Marks the registry and the charts indexed from it for deletion and returns `marked_for_deletion_at`.

# Delete a registry credential
Source: https://docs.ankra.ai/api-reference/helm/delete-a-registry-credential

https://platform.ankra.app/openapi.json delete /api/v1/org/helm/credentials/{credential_name}
Deletes the named registry credential. Credentials the platform manages for the organisation cannot be deleted and answer 409.

# Get a file from a Helm chart version
Source: https://docs.ankra.ai/api-reference/helm/get-a-file-from-a-helm-chart-version

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts/chart/{repository_name}/{chart_name}/{chart_version}/file
Returns one file from the chart version's archive, base64-encoded, selected by the required `path` query parameter. Answers 404 when the version has not been indexed and 400 for an invalid path.

# Get a Helm chart version
Source: https://docs.ankra.ai/api-reference/helm/get-a-helm-chart-version

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts/chart/{repository_name}/{chart_name}/{chart_version}
Returns the details of one chart version. Set `values=true` or `readme=true` to also receive the chart's default values or README, base64-encoded.

# Get a Helm registry
Source: https://docs.ankra.ai/api-reference/helm/get-a-helm-registry

https://platform.ankra.app/openapi.json get /api/v1/org/helm/registries/{registry_name}
Returns the registry with a page of its indexed charts, its indexing state, next scheduled sync, recent sync jobs and last sync error. Answers 404 for an unknown registry.

# Get a registry credential
Source: https://docs.ankra.ai/api-reference/helm/get-a-registry-credential

https://platform.ankra.app/openapi.json get /api/v1/org/helm/credentials/{credential_name}
Returns the credential's name, username and provider; the password is never returned. Requires the `credentials.reveal` permission.

# Get Helm chart default values
Source: https://docs.ankra.ai/api-reference/helm/get-helm-chart-default-values

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts/chart/{repository_name}/{chart_name}/{chart_version}/values
Returns the chart version's default values file, base64-encoded in `values_base64`: the equivalent of `helm show values`.

# List clusters using a Helm chart
Source: https://docs.ankra.ai/api-reference/helm/list-clusters-using-a-helm-chart

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts/clusters/{repository_name}/{chart_name}
Lists the organisation's clusters that run the chart as an add-on, with the installed version and owning stack for each, paginated. The response also carries the chart's latest indexed version.

# List files in a Helm chart version
Source: https://docs.ankra.ai/api-reference/helm/list-files-in-a-helm-chart-version

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts/chart/{repository_name}/{chart_name}/{chart_version}/files
Lists the files contained in the chart version's archive. Answers 404 when the version has not been indexed and 413 when the archive is too large to open.

# List Helm chart releases
Source: https://docs.ankra.ai/api-reference/helm/list-helm-chart-releases

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts/releases/{repository_name}/{chart_name}
Lists the chart's upstream release notes (version, notes, authors, link), newest first, paginated.

# List Helm charts
Source: https://docs.ankra.ai/api-reference/helm/list-helm-charts

https://platform.ankra.app/openapi.json get /api/v1/org/helm/charts
Lists the Helm chart versions indexed from the registries available to the organisation, paginated, with optional `search` and `connected` filters. Each chart carries the catalogue add-on it matches, when there is one.

# List Helm registries
Source: https://docs.ankra.ai/api-reference/helm/list-helm-registries

https://platform.ankra.app/openapi.json get /api/v1/org/helm/registries
Lists the Helm registries available to the organisation, paginated, with search and sorting.

# List registry credentials
Source: https://docs.ankra.ai/api-reference/helm/list-registry-credentials

https://platform.ankra.app/openapi.json get /api/v1/org/helm/credentials
Lists the organisation's Helm registry credentials. Usernames and passwords are never returned.

# List registry sync jobs
Source: https://docs.ankra.ai/api-reference/helm/list-registry-sync-jobs

https://platform.ankra.app/openapi.json get /api/v1/org/helm/registries/{registry_name}/sync-jobs
Lists the registry's sync jobs, paginated, with filters for status, job type and search. Answers 404 for an unknown registry.

# Render a chart version's manifests with helm template
Source: https://docs.ankra.ai/api-reference/helm/render-a-chart-versions-manifests-with-helm-template

https://platform.ankra.app/openapi.json post /api/v1/org/helm/charts/template
Renders a chart version's manifests server-side, like `helm template`, with optional base64-encoded values, release name and namespace; no cluster is contacted. A values problem answers 422 with Helm's error text.

# Sync a Helm registry
Source: https://docs.ankra.ai/api-reference/helm/sync-a-helm-registry

https://platform.ankra.app/openapi.json post /api/v1/org/helm/registries/{registry_name}/sync
Queues a re-index of the registry and returns the number of jobs created. Answers 409 when a sync is already running and 400 when the registry is not in a state that can be synced.

# Update a Helm registry
Source: https://docs.ankra.ai/api-reference/helm/update-a-helm-registry

https://platform.ankra.app/openapi.json put /api/v1/org/helm/registries/{registry_name}
Changes the registry's `read_job_interval`, the only setting that can be updated.

# Update a registry credential
Source: https://docs.ankra.ai/api-reference/helm/update-a-registry-credential

https://platform.ankra.app/openapi.json put /api/v1/org/helm/credentials/{credential_name}
Replaces the credential's username and password. Credentials the platform manages for the organisation cannot be changed and answer 409.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/vms
Adds a standalone VM with the given `name` and `instance_type` on the cluster network; its location defaults to the bastion's. On a running cluster its creation starts at once and the result carries the `operation_id`; on a stopped cluster it is created at the next start. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Add node group
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/node-groups
Adds a worker node group with the given `name`, `instance_type` and `count` (default 1), plus optional labels, taints and autoscaling settings. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Converge Hetzner external cloud provider
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/converge-hetzner-external-cloud-provider

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/external-cloud-provider/converge
Store external_cloud_provider=true on every Kubernetes node definition of a Hetzner k3s cluster whose definitions say false while its nodes already run for the hcloud cloud controller manager (a cluster created by the Python lane). The flag is an instruction to the day-2 lanes, so it is only written when EVERY node, read from the platform's node census (the k8s-sync mirror, nodes seen in the last 30 minutes), already carries the external shape: the kubelet argument cloud-provider=external in its k3s.io/node-args annotation, on a k3s server also --disable-cloud-controller and servicelb disabled, and an hcloud:// providerID. Only the stored definitions change: no node is restarted, re-tainted or re-registered and no job is dispatched. Anything else answers 409 with a detail message naming each node to remediate first and why; a node the census cannot vouch for (no fresh node at all, a node missing from the census, a node without a readable k3s.io/node-args annotation, a Kubernetes node resource that is not up or has no stored definition) is refused the same way rather than assumed wired. The other invalid states (a cluster of another provider or distribution, no Kubernetes node resources, a node update, version upgrade or node restart in progress) also answer 409. A cluster whose definitions already all say true answers 200 without reading the census.

# Create a Hetzner cluster
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/create-a-hetzner-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner
Creates a Hetzner cluster from the request, after checking server-type availability in the chosen location with Hetzner, and starts provisioning it in the background, answering 201 with the new cluster's `cluster_id` and `name`. A configuration that fails validation answers 400 with the reason, and an organisation whose billing is restricted is refused with 402.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/hetzner/{cluster_id}/vms/{vm_id}
Deletes a standalone VM: it is handed to teardown and its server is removed at the provider. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Delete node group
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/hetzner/{cluster_id}/node-groups/{group_name}
Removes a node group by draining and deleting its workers one at a time through their PodDisruptionBudgets; a worker whose drain is refused stays in service and the operation fails with the reason. Pass `force_drain=true` to take the whole group down regardless. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result. Requires `clusters.delete`.

# Deprovision a Hetzner cluster
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/deprovision-a-hetzner-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/hetzner/{cluster_id}
Deletes the cluster and its cloud resources. A delete that would remove persistent volumes, or cannot tell whether it does, is refused with 409 unless `accept_volume_data_loss=true` is passed (see the deprovision-volumes read); `force=true` tolerates infrastructure that can no longer be reached. Active operations on the cluster are cancelled and the response carries the teardown's `operation_id`.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `hetzner_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself.

# Get bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/get-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.read`. Returns the cluster's stored bastion SSH source allowlist, as the update on the same path stored it. `configured` tells a cleared list (true, empty) from one that was never set (false, empty); both leave SSH open from anywhere.

# Get current Kubernetes version
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/get-current-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/k8s-version
Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Get current worker count
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/get-current-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/worker-count
Returns the cluster's current worker count and the minimum and maximum it can be scaled to.

# Get disabled K3s components
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/get-disabled-k3s-components

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/k3s-disabled-components
Read the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), on top of the provider shape's own defaults. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states (a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider) answer 409 with a detail message.

# Latest restorable state snapshot of a Hetzner cluster
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/latest-restorable-state-snapshot-of-a-hetzner-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the Hetzner cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List available Hetzner locations
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/list-available-hetzner-locations

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/locations
Lists the Hetzner Cloud locations visible to the Hetzner credential given in `credential_id`.

# List available Hetzner server types
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/list-available-hetzner-server-types

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/server-types
Lists Hetzner Cloud server types for the credential in `credential_id` with cores, memory, disk, architecture, CPU type and monthly price (null when Hetzner lists none). `available` says whether the type can be ordered in the optional `location`, or in any location when none is given; deprecated types are never available.

# List node groups
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/node-groups
Lists the cluster's worker node groups with each group's instance type, node count, autoscaling bounds, labels and taints.

# List nodes
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/nodes
Lists the cluster's machines with each one's role, node group, instance type, location, state, private and public IPs, the kubelet version it reports and, where recorded, the provider's own status.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/vms
Lists the cluster's standalone VMs (servers on the cluster network that are not Kubernetes nodes) with their instance type, location, state, addresses and provider ID.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/control-plane
Returns the control-plane count, the counts the cluster supports, the control planes' instance type, and whether a count or instance-type change is possible right now, with the reason when it is not.

# Read node
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/nodes/{node_id}
Returns one machine of the cluster with its definition, its latest recorded info and data, and its dependencies and relationships. Answers 404 when the node is not part of the cluster.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `hetzner_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/access-info
Returns what you need to reach the cluster's machines over SSH: the bastion's public IP, the control-plane IPs and the cluster name.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/ssh-keys
Returns the SSH key credentials authorised on the cluster's servers (`ssh_key_credential_ids`) and the organisation's SSH key credentials that can be attached.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/vms/{vm_id}/instance-type
Resizes a standalone VM in place to the given `instance_type`. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/control-plane/instance-type
Changes the instance type of every control plane. On a running cluster the control planes are resized one at a time behind an etcd quorum check and a drain, and the response carries the `operation_id` to follow (clusters with fewer than three control planes are refused); on a stopped cluster the new type is applied at the next start and no operation is returned.

# Resize node group
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/node-groups/{group_name}/instance-type
Changes the instance type of every worker in the node group. Each node is power-cycled, so the workers are drained and resized in bounded batches; `force_drain` bypasses PodDisruptionBudgets for that drain. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/ssh-keys/resync
Re-applies the cluster's configured SSH keys to its servers and returns the IDs of the resources queued for the update.

# Scale Hetzner cluster workers
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/scale-hetzner-cluster-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/scale-workers
Sets the cluster's worker count to `worker_count` and returns the previous and new counts. A scale-down drains the removed workers through their PodDisruptionBudgets unless `force_drain` is true. Requires `clusters.operate`.

# Scale node group
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/node-groups/{group_name}/scale
Sets the node group's node count to `count`. A scale-down drains the removed workers through their PodDisruptionBudgets; `force_drain` bypasses them for this request. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Start a Hetzner cluster
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/start-a-hetzner-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/start
Recreate the Hetzner cloud resources for a stopped cluster and reconcile it back to a running state.

# Stop a Hetzner cluster
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/stop-a-hetzner-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/stop
Initiate async deletion of Hetzner cloud resources (servers, networks, SSH keys) without removing the cluster from the database.

# The persistent volumes deleting a Hetzner cluster removes
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/the-persistent-volumes-deleting-a-hetzner-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/hetzner/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/hetzner/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none.

# Update bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/update-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.write`. Replaces the cluster's bastion SSH source allowlist and dispatches the bastion update that applies it: the bastion's SSH port then accepts only the listed IPv4 sources, the platform's own egress addresses and private network sources, and drops everything else. An empty list clears the allowlist. Clusters that never set one keep SSH open from anywhere.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/control-plane
Changes the number of control planes to `count`. On a running cluster the control plane can only grow, and the new control planes join live (`mode` `rolling`, with an `operation_id` to follow); a reduction is applied offline to a stopped cluster and takes effect at its next start.

# Update disabled K3s components
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/update-disabled-k3s-components

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/k3s-disabled-components
Replace the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), for example ["traefik"] on a cluster that brings its own ingress. k3s distribution only. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states answer 409 with a detail message: a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider, a list that drops a stored entry (re-enabling a bundled component is not supported yet, so the list only grows), a list that adds coredns (load-bearing for in-cluster DNS), and any change while a node update, version upgrade or node restart is in progress on the cluster.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/node-groups/{group_name}/labels
Replaces the Kubernetes labels on every node in the node group with the given `labels` map. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/node-groups/{group_name}/taints
Replaces the taints on every node in the node group with the given `taints` list (each a `key`, an optional `value` and an `effect` of `NoSchedule`, `PreferNoSchedule` or `NoExecute`). By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/hetzner/{cluster_id}/ssh-keys
Replaces the SSH key credentials authorised on the cluster's servers with `ssh_key_credential_ids` and starts rolling the keys out. An unknown or repeated credential, or two credentials carrying the same public key, is refused with 409.

# Upgrade Kubernetes version
Source: https://docs.ankra.ai/api-reference/hetzner-clusters/upgrade-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/hetzner/{cluster_id}/upgrade-k8s-version
Upgrades the cluster to `target_version`, which must be in the supported version catalogue and must not downgrade or skip a minor version. The cluster must be online with no change in progress; the nodes are upgraded as a rolling operation whose `operation_id` is returned, and `force` continues past a node drain that PodDisruptionBudgets refuse.

# Create a Hetzner API credential
Source: https://docs.ankra.ai/api-reference/hetzner-credentials/create-a-hetzner-api-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/hetzner
Creates a Hetzner API credential from `name` and `api_token`. The token is checked against the Hetzner API before it is stored in Vault; an invalid token answers 400. Requires `credentials.write`; answers 201.

# Create an SSH key credential
Source: https://docs.ankra.ai/api-reference/hetzner-credentials/create-an-ssh-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/hetzner/ssh-key
Creates an SSH key credential from `name` and either `ssh_public_key` or `generate=true`; a generated RSA-4096 key pair's private key is returned once, in this response. A public key the organisation already stores under another credential is refused with 400. Requires `credentials.write`; answers 201.

# Get Hetzner credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/hetzner-credentials/get-hetzner-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/hetzner/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the Hetzner API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get Hetzner credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/hetzner-credentials/get-hetzner-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/hetzner/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the Hetzner limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# List Hetzner API credentials
Source: https://docs.ankra.ai/api-reference/hetzner-credentials/list-hetzner-api-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/hetzner
Lists the organisation's Hetzner API credentials with their metadata; the secret material is never returned.

# List SSH key credentials
Source: https://docs.ankra.ai/api-reference/hetzner-credentials/list-ssh-key-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/hetzner/ssh-keys
Lists the organisation's SSH key credentials. The list is the same under every cloud provider. Each item carries the stored public key with the fingerprint (as `ssh-keygen -l` prints it), key type and comment derived from it; a stored value that is not a readable key keeps its row, with a null `fingerprint` and `fingerprint_error` saying why.

# Get HPE Morpheus credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/hpe-morpheus-credentials/get-hpe-morpheus-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/morpheus/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the HPE Morpheus API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get HPE Morpheus credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/hpe-morpheus-credentials/get-hpe-morpheus-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/morpheus/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the HPE Morpheus limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Adopt a stack into a stack profile
Source: https://docs.ankra.ai/api-reference/imported-clusters/adopt-a-stack-into-a-stack-profile

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks/adopt-profile
Records a stack the cluster already runs as a deployment of a stack profile version, so later profile rollouts can track it. Only the profile link is written: nothing is deployed or changed on the cluster. Requires `stacks.write`; the response lists the add-ons and manifests that differ between the live stack and the profile version.

# Change an add-on's chart version by rewriting it in its owning stack
Source: https://docs.ankra.ai/api-reference/imported-clusters/change-an-add-ons-chart-version-by-rewriting-it-in-its-owning-stack

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_name}/upgrade
Moves one installed add-on to the given chart version. The owning stack is read as the specification that reproduces it, the member's chart_version is changed, and only that member is written back, so nothing else in the stack is touched. A lower version is a downgrade and is refused with CHART_VERSION_DOWNGRADE unless confirmed_chart_downgrades names that exact move. Answers the stack write payload (operation_id to watch). 404 when the cluster or add-on is unknown, 409 when no Ankra stack owns the add-on, it already runs that version, or its chart version kept changing while the upgrade was being written (read the add-on again and retry).

# Clone a stack to this cluster
Source: https://docs.ankra.ai/api-reference/imported-clusters/clone-a-stack-to-this-cluster

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks/clone
Copies a stack from a source cluster onto this cluster, optionally under a new name, optionally including its add-on configurations, and deploys it when `deploy_after_clone` is set. Requires `stacks.read` on the source and `stacks.write` resolved in the destination organisation on the destination cluster. Source organisation permissions do not grant destination access. Project-pinned and service-account tokens cannot clone across organisations; token permission scopes still apply. The destination write gate follows body validation so it can resolve the target organisation; cloning with `include_data` also copies the stack's data through a restore point and additionally requires `backups.operate`.

# Create a cluster power schedule
Source: https://docs.ankra.ai/api-reference/imported-clusters/create-a-cluster-power-schedule

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/power-schedules
The bearer twin of the portal's power-schedule create (`ankra cluster power-schedules create`). Files a one-off (`schedule_kind` once, fires at `run_at`) or repeated (`schedule_kind` cron, fires per `cron_expression` in `timezone`) stop or start of a provider-managed cluster. The body is decoded and validated exactly like the portal route's, and the response is the cluster's refreshed schedule listing.

# Create a cluster stack
Source: https://docs.ankra.ai/api-reference/imported-clusters/create-a-cluster-stack

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks
Creates a stack on the cluster from a specification holding exactly one stack, deploys it, and commits it to the cluster's GitOps repository when one is connected. The response carries validation errors and warnings, the commit, and the `operation_id` of the deployment; a failed Git push answers `422`. On a sandbox cluster the deployment is simulated and settled before the response, so the operation has already succeeded. Requires `stacks.write` on the cluster; a caller without it is refused with `403`.

# Create a stack from a stack profile
Source: https://docs.ankra.ai/api-reference/imported-clusters/create-a-stack-from-a-stack-profile

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks/from-profile
Instantiates a stack profile version on the cluster with the parameter values you supply, creating a stack draft and deploying it when `deploy` is set. Requires `stacks.write`; missing or invalid parameters, unresolvable variables and draft errors answer `400`, and a deprecated version answers `409`.

# Delete a cluster power schedule
Source: https://docs.ankra.ai/api-reference/imported-clusters/delete-a-cluster-power-schedule

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/imported/{cluster_id}/power-schedules/{schedule_id}
The bearer twin of the portal's power-schedule delete (`ankra cluster power-schedules delete`). Soft-deletes one schedule.

# Delete a cluster stack
Source: https://docs.ankra.ai/api-reference/imported-clusters/delete-a-cluster-stack

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}
Marks the stack for deletion so its resources are removed from the cluster, and commits the change to the cluster's GitOps repository when one is connected. Returns when the stack was marked and the commit; on a sandbox cluster the removal is simulated and settled before the response. A stack a managed service owns is refused with `409` until the service is retired. Requires `stacks.delete` on the cluster; a caller without it is refused with `403`.

# Discard a stack draft
Source: https://docs.ankra.ai/api-reference/imported-clusters/discard-a-stack-draft

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/imported/{cluster_id}/drafts/stacks/{draft_id}
Discards one stack draft on the cluster without deploying it; the deployed stack, if any, is left untouched. A draft an Ankra AI chat is still bound to, or one the AI wrote moments ago, is protected: the answer is `200` with `already_discarded` true and `reason` `protected`, and nothing is written, unless `force` is true. Discarding a draft that is already gone answers `200` with `already_discarded` true and the original reason. Answers `404` with code `DRAFT_UNKNOWN` for a draft that never existed on the cluster, and `409` for the installation draft of a managed service, which is removed by retiring the service.

# Disconnect a manifest from a stack
Source: https://docs.ankra.ai/api-reference/imported-clusters/disconnect-a-manifest-from-a-stack

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/manifests/{manifest_name}/disconnect
Disconnects (removes) a manifest from a stack.

Mirrors the web UI disconnect endpoint but is exposed on the bearer-token
CLI API so `ankra cluster manifests delete` can remove a manifest's
resources from the cluster.

Requires `stacks.delete` on the cluster; a caller without it is refused with `403`.

# Export the cluster specification
Source: https://docs.ankra.ai/api-reference/imported-clusters/export-the-cluster-specification

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/iac
Returns the full ImportCluster YAML (base64-encoded) for a cluster.

Mirrors the web UI endpoint but uses bearer-token auth for CLI access.
Returns 404 when the cluster has no resources to generate IaC from.

# Generate a cluster agent token
Source: https://docs.ankra.ai/api-reference/imported-clusters/generate-a-cluster-agent-token

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/cluster-agent/token
Mints a new identity token for the cluster agent, registering the agent first if it has none, and returns it with the Helm install command. Requires `agents.manage`; sandbox clusters answer `400`.

# Get add-on settings
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-add-on-settings

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_name}/settings
Returns the add-on's deployment settings (sync policy, retries, sync windows and similar), with defaults filled in, plus the predefined settings profiles you can apply.

# Get add-on values
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-add-on-values

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_name}/configuration
Returns the addon's DB-stored values (plaintext, base64-encoded).

Unlike the web UI v2 endpoint this never queries the cluster agent or
Argo CD; the CLI only needs the values for Helm-style --set mutation.

# Get manifest content
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-manifest-content

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/manifests/{manifest_name}/configuration
Returns the manifest's base64-encoded content.

Used by `ankra cluster manifests upgrade` to preserve manifest_base64 when
the user supplies only metadata changes (e.g. --namespace).

# Get stack history
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-stack-history

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/history
Returns the version history of each add-on and manifest in the stack, up to `max_versions` entries per resource (1 to 100, default 50). Filter to one kind with `resource_type` (`addon` or `manifest`).

# Get the cluster agent
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-the-cluster-agent

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/agent
Returns the cluster agent's version, whether it is online, when it last checked in, and its upgrade state, including whether automatic upgrades are turned off. Answers `404` when no agent is registered.

# Get the cluster agent token
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-the-cluster-agent-token

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/cluster-agent/token
Returns the cluster agent's identity token together with the Helm install command that uses it. Answers `404` when no token exists for the cluster.

# Get the cluster metrics source
Source: https://docs.ankra.ai/api-reference/imported-clusters/get-the-cluster-metrics-source

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/metrics-source
Returns the cluster's registered metrics source: provider, endpoint, state, flavor, health, the credential name it resolves to (back-filled from the cluster's only prometheus_credential when the source never named one), and that credential's name, state and username.

Mirrors the web UI endpoint but uses bearer-token auth for CLI access. The credential's password and token are never returned.
Returns 404 when the cluster has no metrics source; 400 with the detail "Unknown metrics provider, please check the metrics source configuration." when the stored source resolves to no provider (today: a definition without an endpoint); and 502 with a detail naming the credential when the named credential or its secret cannot be resolved.

# List available add-ons
Source: https://docs.ankra.ai/api-reference/imported-clusters/list-available-add-ons

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/addons/available
Returns the Helm charts available to your organisation for installing as add-ons, each with its latest version and description. Answers `404` when the cluster is not in your organisation.

# List cluster stacks
Source: https://docs.ankra.ai/api-reference/imported-clusters/list-cluster-stacks

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks
Returns a paginated list of the stacks on the cluster, optionally filtered by `search`. `page_size` accepts 1 to 100 and defaults to 25; answers `404` when the cluster is not in your organisation.

# Move resources between stacks
Source: https://docs.ankra.ai/api-reference/imported-clusters/move-resources-between-stacks

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/move
Moves manifests/addons from one stack to another on the same cluster.

Mirrors the web UI move endpoint but is exposed on the bearer-token
CLI API so `ankra cluster stacks move` can re-home deployed resources
without uninstalling them.

# Read a shared stack draft
Source: https://docs.ankra.ai/api-reference/imported-clusters/read-a-shared-stack-draft

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/drafts/stacks/{draft_id}
Requires stack read access to this organisation and cluster. Draft author evidence is additive and reads never backfill attribution.

# Read a stack draft
Source: https://docs.ankra.ai/api-reference/imported-clusters/read-a-stack-draft

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/drafts/stacks/{draft_id}
Returns one stack draft on the cluster with the full content of the members it holds, including the manifest bodies and add-on values the stack listing elides. Use it to review a draft, or to promote the draft of an already-deployed stack through `PATCH /stacks/{stack_name}` with its `draft_id`. Answers `404` with code `DRAFT_UNKNOWN` for a draft that never existed on the cluster, and `410` with code `DRAFT_TOMBSTONED` for one that was discarded or deployed.

# Read shared stack draft changes
Source: https://docs.ankra.ai/api-reference/imported-clusters/read-shared-stack-draft-changes

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/drafts/stacks/{draft_id}/diff
Requires stack read access to this organisation and cluster. Draft author evidence is additive and reads never backfill attribution.

# Reconcile a cluster
Source: https://docs.ankra.ai/api-reference/imported-clusters/reconcile-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/reconcile
Plans and starts the work needed to bring the cluster back in line with its stored specification. Answers `404` when the cluster is not in your organisation. Requires `clusters.operate`.

# Remove one stack variable
Source: https://docs.ankra.ai/api-reference/imported-clusters/remove-one-stack-variable

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables/{variable_name}
Removes one stack variable. Removing a variable the stack does not hold answers 200 with changed false. The edit is merged into the deployed variables under the cluster lock, so keys it does not name are never overwritten, including a key the application image-tag lane moved a moment earlier. It is a live write: a pending draft of the stack is neither read nor published, and the stack's description, deploy wave and members are kept. A pending draft of the stack picks this write up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Requires `stacks.write` on the cluster.

# Remove one stack variable (browser session)
Source: https://docs.ankra.ai/api-reference/imported-clusters/remove-one-stack-variable-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables/{variable_name}
Removes one stack variable. Removing a variable the stack does not hold answers 200 with changed false. The edit is merged into the deployed variables under the cluster lock, so keys it does not name are never overwritten, including a key the application image-tag lane moved a moment earlier. It is a live write: a pending draft of the stack is neither read nor published, and the stack's description, deploy wave and members are kept. A pending draft of the stack picks this write up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Requires `stacks.write` on the cluster. Browser-session twin of the /api/v1 route; a write also requires the X-Ankra-CSRF header.

# Rename a cluster stack
Source: https://docs.ankra.ai/api-reference/imported-clusters/rename-a-cluster-stack

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/rename-stack
Renames a stack on the cluster and commits the change to the cluster's GitOps repository when one is connected. Answers `409` while the stack has unpublished drafts, when the new name is taken, or while a managed service that has not been retired owns the stack. Requires `stacks.write` on the cluster; a caller without it is refused with `403`.

# Replace a cluster power schedule
Source: https://docs.ankra.ai/api-reference/imported-clusters/replace-a-cluster-power-schedule

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/imported/{cluster_id}/power-schedules/{schedule_id}
The bearer twin of the portal's power-schedule update (`ankra cluster power-schedules update`). A full replace, not a patch: `enabled` must always be sent, `stop_mode` must be restated for a stop schedule, and `timezone` for a cron schedule. The response is the cluster's refreshed schedule listing.

# Set and remove stack variables
Source: https://docs.ankra.ai/api-reference/imported-clusters/set-and-remove-stack-variables

https://platform.ankra.app/openapi.json patch /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables
Sets and removes several stack variables in one atomic write. The edit is merged into the deployed variables under the cluster lock, so keys it does not name are never overwritten, including a key the application image-tag lane moved a moment earlier. It is a live write: a pending draft of the stack is neither read nor published, and the stack's description, deploy wave and members are kept. A pending draft of the stack picks this write up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Requires `stacks.write` on the cluster.

# Set and remove stack variables (browser session)
Source: https://docs.ankra.ai/api-reference/imported-clusters/set-and-remove-stack-variables-browser-session

https://platform.ankra.app/openapi.json patch /org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables
Sets and removes several stack variables in one atomic write. The edit is merged into the deployed variables under the cluster lock, so keys it does not name are never overwritten, including a key the application image-tag lane moved a moment earlier. It is a live write: a pending draft of the stack is neither read nor published, and the stack's description, deploy wave and members are kept. A pending draft of the stack picks this write up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Requires `stacks.write` on the cluster. Browser-session twin of the /api/v1 route; a write also requires the X-Ankra-CSRF header.

# Set one stack variable
Source: https://docs.ankra.ai/api-reference/imported-clusters/set-one-stack-variable

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables/{variable_name}
Sets one stack variable. The edit is merged into the deployed variables under the cluster lock, so keys it does not name are never overwritten, including a key the application image-tag lane moved a moment earlier. It is a live write: a pending draft of the stack is neither read nor published, and the stack's description, deploy wave and members are kept. A pending draft of the stack picks this write up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Requires `stacks.write` on the cluster.

# Set one stack variable (browser session)
Source: https://docs.ankra.ai/api-reference/imported-clusters/set-one-stack-variable-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables/{variable_name}
Sets one stack variable. The edit is merged into the deployed variables under the cluster lock, so keys it does not name are never overwritten, including a key the application image-tag lane moved a moment earlier. It is a live write: a pending draft of the stack is neither read nor published, and the stack's description, deploy wave and members are kept. A pending draft of the stack picks this write up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Requires `stacks.write` on the cluster. Browser-session twin of the /api/v1 route; a write also requires the X-Ankra-CSRF header.

# Set what a cluster is called and what it is for
Source: https://docs.ankra.ai/api-reference/imported-clusters/set-what-a-cluster-is-called-and-what-it-is-for

https://platform.ankra.app/openapi.json patch /api/v1/org/clusters/imported/{cluster_id}/environment
The bearer twin of the portal's environment control (`ankra cluster update --environment`): sets the environment label and, when the body carries one, the criticality that decides how loudly the cluster reports, in a single transaction. A body without a criticality leaves the stored one untouched and answers with the environment alone. An ImportCluster file's metadata.environment is applied only when the import creates the cluster, so this is how a cluster moves between environments afterwards. A person's own token records the label as that person's choice of what the cluster is for (`environment_source` person). A service account's token records it as automation, which confirms nothing, leaves the recorded source alone when the label does not change, and may not take production away from the cluster: moving it off a production label or lowering a production criticality answers 403. Requires `clusters.write` at the cluster.

# Set what a cluster is called and what it is for (browser session)
Source: https://docs.ankra.ai/api-reference/imported-clusters/set-what-a-cluster-is-called-and-what-it-is-for-browser-session

https://platform.ankra.app/openapi.json patch /org/clusters/imported/{cluster_id}/environment
Sets the environment label and, when the body carries one, the criticality that decides how loudly the cluster reports. Both are written in a single transaction because to the operator they are one decision: picking an environment without a matching criticality is how a cluster ends up labelled for testing while the insight scanner still grades every finding on it at production weight. A body without a criticality leaves the stored one untouched and answers with the environment alone, which is the shape every caller written before the two settings were merged sends and expects. Requires `clusters.write`.

# The cluster's node-local storage for a scale_to_zero stop
Source: https://docs.ankra.ai/api-reference/imported-clusters/the-clusters-node-local-storage-for-a-scale_to_zero-stop

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/power-schedules/node-local-storage
The bearer twin of the portal's node-local storage read (`ankra cluster power-schedules create|update` reads it before a scale_to_zero stop). Answers which persistent volume claims keep their data on a worker's own disk, which a scale_to_zero stop deletes at every stop. A failed or empty inventory read is unknown, never none.

# The cluster's power schedules
Source: https://docs.ankra.ai/api-reference/imported-clusters/the-clusters-power-schedules

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/power-schedules
The bearer twin of the portal's power-schedule list (`ankra cluster power-schedules list`). Answers the cluster's scheduled stop/start entries, newest first.

# The stack's deployed variables
Source: https://docs.ankra.ai/api-reference/imported-clusters/the-stacks-deployed-variables

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables
The stack's deployed variables, deploy wave and description, read from the live stack only. Unlike the stack listing, a pending draft never contributes to this read; `has_pending_draft` says whether one exists. A pending draft picks live variable writes up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it.

# The stack's deployed variables (browser session)
Source: https://docs.ankra.ai/api-reference/imported-clusters/the-stacks-deployed-variables-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables
The stack's deployed variables, deploy wave and description, read from the live stack only. Unlike the stack listing, a pending draft never contributes to this read; `has_pending_draft` says whether one exists. A pending draft picks live variable writes up when it is next reconciled against the deployed stack, and publishing the draft merges its variables with the live stack key by key: only a variable the draft itself changed keeps the draft's value. A variable added live after the draft last reconciled is one the draft never saw, so it is kept: publishing the draft cannot remove it. Browser-session twin of the /api/v1 route; a write also requires the X-Ankra-CSRF header.

# Uninstall an add-on
Source: https://docs.ankra.ai/api-reference/imported-clusters/uninstall-an-add-on

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_resource_id}
Uninstalls an add-on from the cluster: in-flight changes to it are cancelled and it is marked for removal. Pass `delete=true` to remove it permanently and `force=true` to force-delete an add-on that is stuck uninstalling. On a stopped cluster a permanent, unforced removal is recorded and pushed to Git at once, and the add-on is uninstalled once the cluster is running or online (`pending_cluster_start` is true).

# Update a cluster stack
Source: https://docs.ankra.ai/api-reference/imported-clusters/update-a-cluster-stack

https://platform.ankra.app/openapi.json patch /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}
Surgical partial update of a stack's addons/manifests.

Accepts the same body as the web UI endpoint. Callers must set
partial_stack=true to merge-update (vs replace) the named stack. Requires `stacks.write` on the cluster; a caller without it is refused with `403`.

# Update add-on settings
Source: https://docs.ankra.ai/api-reference/imported-clusters/update-add-on-settings

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_name}/settings
Updates the add-on's deployment settings with the members you supply and commits the change to the cluster's GitOps repository when one is connected. Requires `stacks.write`; invalid settings answer `400`.

# Update cluster agent settings
Source: https://docs.ankra.ai/api-reference/imported-clusters/update-cluster-agent-settings

https://platform.ankra.app/openapi.json patch /api/v1/org/clusters/imported/{cluster_id}/agent/settings
Turn the cluster agent's automatic upgrades on or off. With them on (the default) the platform's fleet rollout applies each new agent release as soon as the cluster has no write execution running; with them off the rollout skips this agent until they are turned back on, which is how a team fences a cluster off from agent releases for a freeze window. The bearer twin of the portal's cluster settings switch (ankra cluster agent auto-upgrade enable|disable, MCP set_cluster_agent_auto_upgrade). POST .../agent/upgrade still applies a release on demand whichever way the switch sits. Every change writes a set_agent_auto_upgrade audit row naming who made it, the previous and new value and the reason when one is given.

# Upgrade the cluster agent
Source: https://docs.ankra.ai/api-reference/imported-clusters/upgrade-the-cluster-agent

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/agent/upgrade
Sends the cluster agent an upgrade command and returns its acknowledgement. Without a body it installs the latest stable release, or re-renders the agent at the release it runs when that is newer, so a canary on a release candidate is never walked back. `version` names an exact release; one older than the running release answers `409` unless `allow_downgrade` is set, and a release that is neither published nor running answers `422`. Requires `agents.manage`; answers `503` when the cluster is offline or has no agent and `504` when the agent does not respond in time.

# Withdraw a pending add-on removal
Source: https://docs.ankra.ai/api-reference/imported-clusters/withdraw-a-pending-add-on-removal

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_resource_id}/withdraw-removal
Takes back the removal of an add-on that was removed while its cluster was stopped and is still waiting for the cluster to start. The add-on is declared in the cluster's Git repository again and comes back with the rest of the stack when the cluster starts.

# Introduction
Source: https://docs.ankra.ai/api-reference/introduction

Automate cluster operations, integrate with CI/CD, and build on the Ankra platform via REST.

Automate cluster operations, integrate with your CI/CD, and build on top of the Ankra platform.

The Ankra REST API lets you programmatically manage Ankra resources - such as clusters and add-ons - run operations, and retrieve statuses from your own tools, scripts, and pipelines.

***

## Quickstart

### 1) Generate an API token

1. Click your profile avatar (bottom-left) in the Ankra dashboard.
2. **Profile → API Tokens → Create**.
3. Name the token (choose MCP access only if an MCP client will use it) and **copy it somewhere safe**.

> You won’t be able to view the token again after closing the dialog.

> [!NOTE]
>
> That is a **personal** token: it acts as you, and it stops working if you leave the organisation. For anything that runs without a person behind it - CI/CD, Terraform, an agent - create a [service token](/guides/service-tokens) instead. It is owned by the organisation, carries a role you pick rather than all of your authority, and survives offboarding.

### 2) Make your first request

**Bash (cURL)**

```bash theme={null}
export ANKRA_API_TOKEN="<your-token>"

curl -sS \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Accept: application/json" \
  https://platform.ankra.app/api/v1/clusters
```

**Python**

```python theme={null}
import requests

headers = {"Authorization": "Bearer <your-token>"}
resp = requests.get("https://platform.ankra.app/api/v1/clusters", headers=headers)
resp.raise_for_status()
print(resp.json())
```

**Node.js**

```javascript theme={null}
const res = await fetch("https://platform.ankra.app/api/v1/clusters", {
  headers: { Authorization: "Bearer <your-token>" }
});
if (!res.ok) throw new Error(await res.text());
console.log(await res.json());
```

***

## Authentication

Use an API token in the `Authorization` header:

```http theme={null}
Authorization: Bearer <your-token>
```

* Tokens are created in the dashboard or with `ankra tokens create`. A token acts with its owner's role (a service token with the role it was given); scopes only add [MCP server](/platform/mcp-server) access.
* Revoke a personal token anytime from **Profile → API Tokens**, and a [service token](/guides/service-tokens) from **Organisation → Service tokens**.
* Prefer separate tokens for different use cases (e.g., CLI vs. CI/CD).
* A service token is pinned to its organisation: the `X-Ankra-Organisation-Id` override that `ankra --org` uses is refused for it.

### Security best practices

* Treat tokens like passwords - never commit them to source control.
* Grant only the minimum required permissions.
* Rotate/revoke tokens regularly and immediately if you suspect compromise.
* Store tokens as secrets in your CI/CD system (e.g., GitHub Actions, GitLab CI, Jenkins).
* Use a [service token](/guides/service-tokens) for automation, so the credential is not tied to one
  person's membership and can be reviewed and revoked by any administrator.

**CLI example (authenticate once):**

```bash theme={null}
export ANKRA_API_TOKEN="<your-token>"
```

**GitHub Actions example:**

```yaml theme={null}
env:
  ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
```

***

## Errors

The API uses standard HTTP status codes. Error responses include a machine-readable body to help diagnose issues.

| Code | Meaning |
| - | - |
| 200 | Success |
| 400 | Bad request / validation |
| 401 | Missing or invalid token |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 429 | Too many requests (rate limit) |
| 5xx | Server errors |

***

## Pagination & filtering

Endpoints that return collections may support pagination and filters. Refer to the endpoint’s page for available query parameters and response shapes.

***

## Versioning

This reference covers the **v1** API (`/api/v1`). Breaking changes are introduced only in new major versions; minor, non-breaking updates may be added to v1.

***

## Help & support

* Check the endpoint pages for required parameters and examples.
* Review token permissions if you receive 401/403 errors.
* If you’re stuck, [contact support](/platform/support).


# Apply a Kubernetes resource
Source: https://docs.ankra.ai/api-reference/kubernetes/apply-a-kubernetes-resource

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/resources/apply
Applies a Kubernetes manifest to the cluster through the cluster agent, optionally as a dry run. Requires `kubernetes.write` on the cluster. A dry-run preview of a Secret carries value digests, never the values.

# Delete a Kubernetes resource
Source: https://docs.ankra.ai/api-reference/kubernetes/delete-a-kubernetes-resource

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/resources/delete
Deletes one Kubernetes resource, identified by `kind`, `name` and (for namespaced kinds) `namespace`, through the cluster agent; supports `dry_run` and `grace_period_seconds`. Requires `kubernetes.write` on the cluster. A dry-run preview of a Secret carries value digests, never the values.

# Delete a Kubernetes resource with identity preconditions (browser session)
Source: https://docs.ankra.ai/api-reference/kubernetes/delete-a-kubernetes-resource-with-identity-preconditions-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/{cluster_id}/kubernetes/resources/delete-guarded
Requires a supporting agent. Older agents refuse the guarded command rather than performing an unguarded deletion.

# Get a Helm release
Source: https://docs.ankra.ai/api-reference/kubernetes/get-a-helm-release

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/kubernetes/helm/releases/{namespace}/{name}
Returns the details of one Helm release on the cluster, read live through the cluster agent. Requires `kubernetes.read` on the cluster; answers 404 when the release does not exist. Credential-shaped values, Secret values in the rendered manifests and credentials in the notes are withheld unless `reveal_values` is set and the caller holds `kubernetes.secrets_reveal`; `secret_values` says which.

# Get Helm release history
Source: https://docs.ankra.ai/api-reference/kubernetes/get-helm-release-history

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/kubernetes/helm/releases/{namespace}/{name}/history
Returns the revision history of a Helm release, up to `limit` revisions (default 25, maximum 200), read through the cluster agent. Requires `kubernetes.read` on the cluster.

# Get Kubernetes resources
Source: https://docs.ankra.ai/api-reference/kubernetes/get-kubernetes-resources

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/resources/get
Reads one or more batches of Kubernetes resources by kind, with optional name, namespace, label and field selectors and pagination. Requires `kubernetes.read`; results may be served from Ankra's cache, including stale cached data when the cluster is unreachable. Secret values come back as digests unless `reveal_secret_values` is set on a read of one Secret by name and the caller holds `kubernetes.secrets_reveal`; each item's `secret_values` says which.

# List Helm releases
Source: https://docs.ankra.ai/api-reference/kubernetes/list-helm-releases

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/resources/helm/get
Lists Helm releases on the cluster through the cluster agent, per namespace or across all namespaces, with optional name filter and pagination. Requires `kubernetes.read` on the cluster.

# List pods
Source: https://docs.ankra.ai/api-reference/kubernetes/list-pods

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/kubernetes/pods
Returns a page of the cluster's pods from Ankra's synchronised cache, with filters for namespace, name, node and phase, plus sorting. Requires `kubernetes.read`; the response reports how stale the cached data is and lists the cluster's namespaces.

# Patch a Kubernetes resource
Source: https://docs.ankra.ai/api-reference/kubernetes/patch-a-kubernetes-resource

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/resources/patch
Patches one Kubernetes resource through the cluster agent, using a strategic merge patch by default (`patch_type` selects another), optionally as a dry run. Requires `kubernetes.write` on the cluster. A dry-run preview of a Secret carries value digests, never the values.

# Roll back a Helm release
Source: https://docs.ankra.ai/api-reference/kubernetes/roll-back-a-helm-release

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/helm/releases/{namespace}/{name}/rollback
Rolls a Helm release back to the given `revision` through the cluster agent, waiting for resources to be ready by default (`timeout_seconds` defaults to 600, maximum 3600). Requires `kubernetes.write`; a release managed by an Ankra add-on is refused with 409 and must be rolled back through the add-on.

# Run a Prometheus range query
Source: https://docs.ankra.ai/api-reference/kubernetes/run-a-prometheus-range-query

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/metrics/query_range
Runs a PromQL range query against the cluster's configured metrics source, over either a relative `range` or explicit `start`/`end` timestamps. Requires `kubernetes.read`; answers 404 when the cluster has no metrics source, and queries are briefly cached and rate limited per organisation (429 with a retry hint).

# Run an instant Prometheus query
Source: https://docs.ankra.ai/api-reference/kubernetes/run-an-instant-prometheus-query

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/metrics/query
Runs a PromQL instant query against the cluster's configured metrics source and returns the result series. Requires `kubernetes.read`; answers 404 when the cluster has no metrics source, and identical queries are briefly cached and rate limited per organisation (429 with a retry hint).

# Stream pod logs
Source: https://docs.ankra.ai/api-reference/kubernetes/stream-pod-logs

https://platform.ankra.app/openapi.json get /api/v1/clusters/{cluster_id}/kubernetes/pod/logs
Streams a pod's container logs as server-sent events through the cluster agent, following new lines by default (`follow=false` returns the current log and ends). Requires `kubernetes.read` and `kubernetes.logs` on the cluster; the viewer role does not hold `kubernetes.logs`. `previous=true` reads the last terminated container and never follows.

# Uninstall a Helm release
Source: https://docs.ankra.ai/api-reference/kubernetes/uninstall-a-helm-release

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/resources/helm/uninstall
Uninstalls the named Helm release from the given namespace through the cluster agent. Requires `kubernetes.write` on the cluster.

# Upgrade a Helm release
Source: https://docs.ankra.ai/api-reference/kubernetes/upgrade-a-helm-release

https://platform.ankra.app/openapi.json post /api/v1/clusters/{cluster_id}/kubernetes/helm/releases/{namespace}/{name}/upgrade
Upgrades a Helm release to `chart_ref` with exactly the supplied `values_yaml`, which replaces the release's current values (an omitted `chart_version` keeps the installed chart version). Requires `kubernetes.write`; a release managed by an Ankra add-on is refused with 409 and must be changed through the add-on. By default the request waits for the agent's answer; with `async` true it answers 202 with an `operation_id` and the upgrade's verdict is recorded on that operation.

# Add a managed node pool
Source: https://docs.ankra.ai/api-reference/managed-clusters/add-a-managed-node-pool

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools
Bearer PAT authentication; RBAC permission `clusters.write`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Add a managed node pool (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/add-a-managed-node-pool-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/node-pools
Browser session authentication; RBAC permission `clusters.write`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Create a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/create-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}
Bearer PAT authentication; RBAC permission `clusters.create`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Create a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/create-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}
Browser session authentication; RBAC permission `clusters.create`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Create a provider network
Source: https://docs.ankra.ai/api-reference/managed-clusters/create-a-provider-network

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/networks
Provision a provider network with the scoping credential so the create wizard can offer an inline create-network flow. GKE creates an auto subnet-mode VPC (a subnetwork in every region, like the GCP default network) and waits for the compute operation to finish; other providers answer 400. The GCP service account needs the compute.networks.create permission (for example via the Compute Network Admin role, roles/compute.networkAdmin); a credential without it answers 400 with the provider's permission message. The response is the created network in the options catalog's private_networks shape. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Create a provider network (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/create-a-provider-network-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/networks
Provision a provider network with the scoping credential so the create wizard can offer an inline create-network flow. GKE creates an auto subnet-mode VPC (a subnetwork in every region, like the GCP default network) and waits for the compute operation to finish; other providers answer 400. The GCP service account needs the compute.networks.create permission (for example via the Compute Network Admin role, roles/compute.networkAdmin); a credential without it answers 400 with the provider's permission message. The response is the created network in the options catalog's private_networks shape. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Delete a managed node pool
Source: https://docs.ankra.ai/api-reference/managed-clusters/delete-a-managed-node-pool

https://platform.ankra.app/openapi.json delete /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}
Bearer PAT authentication; RBAC permission `clusters.write`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Delete a managed node pool (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/delete-a-managed-node-pool-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}
Browser session authentication; RBAC permission `clusters.write`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Delete the provider cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/delete-the-provider-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/delete-provider-cluster
Bearer PAT authentication; RBAC permission `clusters.delete`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Delete the provider cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/delete-the-provider-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/delete-provider-cluster
Browser session authentication; RBAC permission `clusters.delete`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Deprovision a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/deprovision-a-managed-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/managed/{provider}/{cluster_id}
Bearer PAT authentication; RBAC permission `clusters.delete`. For Kapsule this legacy DELETE is disconnect-only; provider deletion requires the explicit delete-provider-cluster endpoint. provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference.

# Deprovision a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/deprovision-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/managed/{provider}/{cluster_id}
Browser session authentication; RBAC permission `clusters.delete`. For Kapsule this legacy DELETE is disconnect-only; provider deletion requires the explicit delete-provider-cluster endpoint. provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference.

# Disconnect a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/disconnect-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/disconnect
Bearer PAT authentication; RBAC permission `clusters.delete`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Disconnect a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/disconnect-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/disconnect
Browser session authentication; RBAC permission `clusters.delete`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Discover managed clusters
Source: https://docs.ankra.ai/api-reference/managed-clusters/discover-managed-clusters

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/discover
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Discover managed clusters (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/discover-managed-clusters-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/discover
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Import a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/import-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/import
Bearer PAT authentication; RBAC permission `clusters.create`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Import a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/import-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/import
Browser session authentication; RBAC permission `clusters.create`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# List live node-pool catalog for a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-live-node-pool-catalog-for-a-managed-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools/catalog
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List live node-pool catalog for a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-live-node-pool-catalog-for-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/{cluster_id}/node-pools/catalog
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List managed-cluster upgrades
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-managed-cluster-upgrades

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/{cluster_id}/upgrades
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List managed-cluster upgrades (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-managed-cluster-upgrades-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/{cluster_id}/upgrades
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List managed node pools
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-managed-node-pools

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List managed node pools (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-managed-node-pools-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/{cluster_id}/node-pools
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List managed-provider options
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-managed-provider-options

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/options
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# List managed-provider options (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-managed-provider-options-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/options
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# List options using the cluster's stored provider context
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-options-using-the-clusters-stored-provider-context

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/{cluster_id}/options
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# List options using the cluster's stored provider context (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/list-options-using-the-clusters-stored-provider-context-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/{cluster_id}/options
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Preflight a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/preflight-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/preflight
Bearer PAT authentication; RBAC permission `clusters.create`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Preflight a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/preflight-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/preflight
Browser session authentication; RBAC permission `clusters.create`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters. For `ankracloud_k8s` with no `credential_id`, the organisation's built-in Ankra Cloud credential is used: the request answers 404 while the organisation's `ankra_cloud_provider` feature flag is off, and 503 with Retry-After when the built-in credential cannot be created or renewed right now.

# Read managed-cluster status
Source: https://docs.ankra.ai/api-reference/managed-clusters/read-managed-cluster-status

https://platform.ankra.app/openapi.json get /api/v1/clusters/managed/{provider}/{cluster_id}/status
Bearer PAT authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Read managed-cluster status (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/read-managed-cluster-status-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/managed/{provider}/{cluster_id}/status
Browser session authentication; RBAC permission `clusters.read`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Replace a managed node pool with a new size
Source: https://docs.ankra.ai/api-reference/managed-clusters/replace-a-managed-node-pool-with-a-new-size

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}/replace
Bearer PAT authentication; RBAC permission `clusters.write`. Requests a blue/green replacement of the node pool with a new instance size: a scheduler job creates a replacement pool with the requested size (same count, labels, taints, zone, and autoscaling), waits for it to become ready, deletes the replaced pool, and rebinds the stored definition to the replacement pool, named by `replacement_pool_name` when the request gives one and deterministically from the pool and size otherwise; the answer carries the name. No managed provider supports in-place pool resizing, so the 202 answer only accepts the intent.

# Replace a managed node pool with a new size (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/replace-a-managed-node-pool-with-a-new-size-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}/replace
Browser session authentication; RBAC permission `clusters.write`. Requests a blue/green replacement of the node pool with a new instance size: a scheduler job creates a replacement pool with the requested size (same count, labels, taints, zone, and autoscaling), waits for it to become ready, deletes the replaced pool, and rebinds the stored definition to the replacement pool, named by `replacement_pool_name` when the request gives one and deterministically from the pool and size otherwise; the answer carries the name. No managed provider supports in-place pool resizing, so the 202 answer only accepts the intent.

# Scale a managed node pool
Source: https://docs.ankra.ai/api-reference/managed-clusters/scale-a-managed-node-pool

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}/scale
Bearer PAT authentication; RBAC permission `clusters.operate`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Scale a managed node pool (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/scale-a-managed-node-pool-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}/scale
Browser session authentication; RBAC permission `clusters.operate`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Start a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/start-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/start
Bearer PAT authentication; RBAC permission `clusters.operate`. Requests the provider-native cluster start; only providers advertising `supports_stop_start` in capabilities (AKS today) support it, others answer 400. The provider completes the transition asynchronously and subsequent status reads converge the resulting power state.

# Start a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/start-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/start
Browser session authentication; RBAC permission `clusters.operate`. Requests the provider-native cluster start; only providers advertising `supports_stop_start` in capabilities (AKS today) support it, others answer 400. The provider completes the transition asynchronously and subsequent status reads converge the resulting power state.

# Stop a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/stop-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/stop
Bearer PAT authentication; RBAC permission `clusters.operate`. Requests the provider-native cluster stop; only providers advertising `supports_stop_start` in capabilities (AKS today) support it, others answer 400. The provider completes the transition asynchronously and subsequent status reads converge the resulting power state.

# Stop a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/stop-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/stop
Browser session authentication; RBAC permission `clusters.operate`. Requests the provider-native cluster stop; only providers advertising `supports_stop_start` in capabilities (AKS today) support it, others answer 400. The provider completes the transition asynchronously and subsequent status reads converge the resulting power state.

# Update managed node-pool autoscaling
Source: https://docs.ankra.ai/api-reference/managed-clusters/update-managed-node-pool-autoscaling

https://platform.ankra.app/openapi.json patch /api/v1/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}
Bearer PAT authentication; RBAC permission `clusters.write`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Update managed node-pool autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/update-managed-node-pool-autoscaling-browser-session

https://platform.ankra.app/openapi.json patch /org/clusters/managed/{provider}/{cluster_id}/node-pools/{node_pool_name}
Browser session authentication; RBAC permission `clusters.write`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Upgrade a managed cluster
Source: https://docs.ankra.ai/api-reference/managed-clusters/upgrade-a-managed-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/managed/{provider}/{cluster_id}/upgrade
Bearer PAT authentication; RBAC permission `clusters.operate`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Upgrade a managed cluster (browser session)
Source: https://docs.ankra.ai/api-reference/managed-clusters/upgrade-a-managed-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/managed/{provider}/{cluster_id}/upgrade
Browser session authentication; RBAC permission `clusters.operate`. For Kapsule, provider_cluster_id is the opaque region-qualified `regions/{region}/clusters/{id}` reference. CNI is immutable. Imported/unknown provenance is disconnect-only; provider deletion is allowed by default only for created clusters.

# Check MCP server health
Source: https://docs.ankra.ai/api-reference/mcp-servers/check-mcp-server-health

https://platform.ankra.app/openapi.json get /api/v1/org/mcp-servers/{server_id}/health
Connects to the server now and reports whether it answered, with the names of the allowed tools it offers. A server that cannot be reached is still a 200, with status error and the reason. Only http and sse servers can be probed.

# Delete an MCP server
Source: https://docs.ankra.ai/api-reference/mcp-servers/delete-an-mcp-server

https://platform.ankra.app/openapi.json delete /api/v1/org/mcp-servers/{server_id}
Removes the server from the organisation, so AI agents can no longer call its tools. Requires the ai.manage permission.

# Disable an MCP server
Source: https://docs.ankra.ai/api-reference/mcp-servers/disable-an-mcp-server

https://platform.ankra.app/openapi.json post /api/v1/org/mcp-servers/{server_id}/disable
Turns the server off without deleting it: AI agents stop calling its tools until it is enabled again. Requires the ai.manage permission.

# Enable an MCP server
Source: https://docs.ankra.ai/api-reference/mcp-servers/enable-an-mcp-server

https://platform.ankra.app/openapi.json post /api/v1/org/mcp-servers/{server_id}/enable
Turns the server on, so AI agents can call its allowed tools again. Requires the ai.manage permission.

# Get an MCP server
Source: https://docs.ankra.ai/api-reference/mcp-servers/get-an-mcp-server

https://platform.ankra.app/openapi.json get /api/v1/org/mcp-servers/{server_id}
Returns one registered MCP server: its URL, transport, env key names, allowed tools, permission tier, adapter and cluster scope. Env values are never returned.

# Grant an MCP tool to a role
Source: https://docs.ankra.ai/api-reference/mcp-servers/grant-an-mcp-tool-to-a-role

https://platform.ankra.app/openapi.json post /api/v1/org/mcp-servers/{server_id}/grants
Lets members with the given role use one of the server's tools. The role defaults to member. Requires the ai.manage permission.

# List curated MCP adapters
Source: https://docs.ankra.ai/api-reference/mcp-servers/list-curated-mcp-adapters

https://platform.ankra.app/openapi.json get /api/v1/org/mcp-servers/catalog
Returns the curated MCP integrations Ankra knows how to connect: each adapter's transport, default or example URL, the credential headers it needs, and the tools it recommends. The list is built into Ankra and the same for every organisation.

# List MCP server tools
Source: https://docs.ankra.ai/api-reference/mcp-servers/list-mcp-server-tools

https://platform.ankra.app/openapi.json get /api/v1/org/mcp-servers/{server_id}/tools
Connects to the server now and returns every tool it offers, including tools outside allowed_tools, with Ankra's read or write verdict, whether the tool is allowed and the roles it is granted to. Use it to widen a narrowed allowed_tools list. A server that cannot be reached is still a 200, with status error and the reason.

# List MCP servers
Source: https://docs.ankra.ai/api-reference/mcp-servers/list-mcp-servers

https://platform.ankra.app/openapi.json get /api/v1/org/mcp-servers
Lists the MCP servers registered in the organisation, sorted by name, with their status and how many tool grants each one has. Any member can read it.

# List MCP tool grants
Source: https://docs.ankra.ai/api-reference/mcp-servers/list-mcp-tool-grants

https://platform.ankra.app/openapi.json get /api/v1/org/mcp-servers/{server_id}/grants
Lists which roles may use which of the server's tools, sorted by tool name and role.

# Register an MCP server
Source: https://docs.ankra.ai/api-reference/mcp-servers/register-an-mcp-server

https://platform.ankra.app/openapi.json post /api/v1/org/mcp-servers
Registers an MCP server for the organisation's AI agents. A remote server (http or sse) must have a public http(s) URL. An env key that looks like a credential must reference a secret by marker (${SECRET_SLOT:<slot_id>}, or ${VAULT:<path>} naming one of the organisation's own secret slots): a plain value, or a ${VAULT:<path>} outside the organisation's secret slots, is refused, so create a secret slot first and pass its sentinel. Env values are never returned. Requires the ai.manage permission.

# Revoke an MCP tool grant
Source: https://docs.ankra.ai/api-reference/mcp-servers/revoke-an-mcp-tool-grant

https://platform.ankra.app/openapi.json delete /api/v1/org/mcp-servers/{server_id}/grants/{tool_name}/{role}
Removes one tool grant, so members with that role can no longer use the tool. Requires the ai.manage permission.

# Update an MCP server
Source: https://docs.ankra.ai/api-reference/mcp-servers/update-an-mcp-server

https://platform.ankra.app/openapi.json put /api/v1/org/mcp-servers/{server_id}
Changes the fields the body names and keeps the rest. env replaces every env entry, while env_patch changes only the keys it names. An explicit null clears allowed_tools, adapter_key or cluster_allow_list. The name and transport cannot change: register a new server for that. The same URL and secret-marker rules as registration apply. Requires the ai.manage permission.

# Create a notification route
Source: https://docs.ankra.ai/api-reference/notifications/create-a-notification-route

https://platform.ankra.app/openapi.json post /api/v1/org/notifications/routes
Creates a routing rule that sends matching notifications to a destination: an alert integration (webhook or channel) or a push audience of organisation members. Answers 404 when the destination, a named member or `cluster_id` does not belong to the organisation.

# Delete a notification route
Source: https://docs.ankra.ai/api-reference/notifications/delete-a-notification-route

https://platform.ankra.app/openapi.json delete /api/v1/org/notifications/routes/{route_id}
Deletes a routing rule and answers 204. Answers 404 when the route does not exist in the organisation.

# List notification routes
Source: https://docs.ankra.ai/api-reference/notifications/list-notification-routes

https://platform.ankra.app/openapi.json get /api/v1/org/notifications/routes
Lists the organisation's notification routing rules: which notification kinds, severities and clusters each rule matches, the destination it delivers to, its priority and whether it is enabled.

# Preview notification routing
Source: https://docs.ankra.ai/api-reference/notifications/preview-notification-routing

https://platform.ankra.app/openapi.json post /api/v1/org/notifications/routes/preview
Shows which destinations a hypothetical notification would reach, and why, without sending anything. `kind` and `severity` are required; `cluster_id`, `source_id` and `alert_id` narrow the notification being previewed.

# Test a notification route
Source: https://docs.ankra.ai/api-reference/notifications/test-a-notification-route

https://platform.ankra.app/openapi.json post /api/v1/org/notifications/routes/{route_id}/test
Queues a sample delivery through the route and answers 202 with the `delivery_id`. A push route is tested against the caller's own registered mobile devices (one delivery each, in `delivery_ids`) and answers 400 when the caller has none.

# Update a notification route
Source: https://docs.ankra.ai/api-reference/notifications/update-a-notification-route

https://platform.ankra.app/openapi.json patch /api/v1/org/notifications/routes/{route_id}
Updates the fields sent in the body of a routing rule and leaves the rest unchanged. A new destination or cluster is checked against the organisation first; answers 404 when the route does not exist.

# Create an object storage bucket
Source: https://docs.ankra.ai/api-reference/object-storage-buckets/create-an-object-storage-bucket

https://platform.ankra.app/openapi.json post /api/v1/org/object-storage-buckets
Bearer PAT authentication; RBAC permission `credentials.write`. Creates a bucket on one of the organisation's provider credentials (Hetzner, Scaleway, DigitalOcean or UpCloud). Answers 202 with the bucket in `provisioning`; the platform creates it and the bucket moves to `ready` or `error`. Hetzner needs an Object Storage key pair, passed here or already stored on the Hetzner credential; every other provider mints its keys from the credential and refuses a supplied pair.

# Delete an object storage bucket
Source: https://docs.ankra.ai/api-reference/object-storage-buckets/delete-an-object-storage-bucket

https://platform.ankra.app/openapi.json delete /api/v1/org/object-storage-buckets/{bucket_id}
Bearer PAT authentication; RBAC permission `credentials.delete`. An ordinary delete forgets the bucket and drops the keys Ankra holds for it, leaving the bucket and its objects on the provider. `destroy_provider_resources=true` also empties and deletes the bucket when Ankra recorded creating it and removes what Ankra minted for it; a bucket still provisioning is always torn down. A bucket that already existed under the requested name is refused at provisioning and never emptied or deleted, and a bucket provisioned before Ankra recorded its creations is kept as well. A teardown that fails brings the bucket back in `error` so it can be retried.

# Get an object storage bucket
Source: https://docs.ankra.ai/api-reference/object-storage-buckets/get-an-object-storage-bucket

https://platform.ankra.app/openapi.json get /api/v1/org/object-storage-buckets/{bucket_id}
Bearer PAT authentication; RBAC permission `credentials.read` (read-class). Key material is never returned.

# List object storage buckets
Source: https://docs.ankra.ai/api-reference/object-storage-buckets/list-object-storage-buckets

https://platform.ankra.app/openapi.json get /api/v1/org/object-storage-buckets
Bearer PAT authentication; RBAC permission `credentials.read` (read-class). Lists the organisation's live object storage buckets, newest first. Key material and the Vault path it lives under are never returned.

# Generate an onboarding website
Source: https://docs.ankra.ai/api-reference/onboarding/generate-an-onboarding-website

https://platform.ankra.app/openapi.json post /org/onboarding/websites
Generate a website from a short prompt on the organisation's website_generation AI lane and deploy it to the cluster: served from a stack (target starter) or committed to a new GitHub repository and deployed as an application (target repository). Answers 202 at once; poll the website for its state. Browser-session route; requires the X-Ankra-CSRF header.

# Get an onboarding website
Source: https://docs.ankra.ai/api-reference/onboarding/get-an-onboarding-website

https://platform.ankra.app/openapi.json get /org/onboarding/websites/{website_id}
One generated website and its progress. Browser-session route.

# List onboarding websites
Source: https://docs.ankra.ai/api-reference/onboarding/list-onboarding-websites

https://platform.ankra.app/openapi.json get /org/onboarding/websites
The organisation's generated websites on one cluster, latest first. Browser-session route.

# List the onboarding website starters
Source: https://docs.ankra.ai/api-reference/onboarding/list-the-onboarding-website-starters

https://platform.ankra.app/openapi.json get /org/onboarding/website-templates
The website starters the onboarding wizard offers, the order of their categories, and the themes any of them can wear. The same for every organisation. Browser-session route.

# (Removed) Cancel a job within an operation
Source: https://docs.ankra.ai/api-reference/operations/removed-cancel-a-job-within-an-operation

https://platform.ankra.app/openapi.json post /api/v1/org/operations/{operation_id}/jobs/{job_id}/cancel
This endpoint has been removed and always answers 410 Gone. Use `POST /api/v1/org/executions/{execution_id}/steps/{step_id}/cancel` instead.

# (Removed) Cancel an operation
Source: https://docs.ankra.ai/api-reference/operations/removed-cancel-an-operation

https://platform.ankra.app/openapi.json post /api/v1/org/operations/{operation_id}/cancel
This endpoint has been removed and always answers 410 Gone. Use `POST /api/v1/org/executions/{execution_id}/cancel` instead.

# Create a custom role (members.manage)
Source: https://docs.ankra.ai/api-reference/organisation-iam/create-a-custom-role-membersmanage

https://platform.ankra.app/openapi.json post /api/v1/org/organisation/roles
Creates a custom role in the organisation from a `slug`, `name`, optional `description`, a list of `permissions` and optional Kubernetes `kube_grants`. Requires `members.manage`.

# Create a GitHub Actions trust policy
Source: https://docs.ankra.ai/api-reference/organisation-iam/create-a-github-actions-trust-policy

https://platform.ankra.app/openapi.json post /api/v1/org/organisation/oidc-trust-policies
Requires members.manage in the authenticated organisation; service accounts are refused. Creating a policy provisions its service account and refuses role escalation. Removing a policy revokes tokens issued by it. Browser mutations require the session CSRF token.

# Create a GitHub Actions trust policy for a browser session
Source: https://docs.ankra.ai/api-reference/organisation-iam/create-a-github-actions-trust-policy-for-a-browser-session

https://platform.ankra.app/openapi.json post /org/organisation/oidc-trust-policies
Requires members.manage in the authenticated organisation; service accounts are refused. Creating a policy provisions its service account and refuses role escalation. Removing a policy revokes tokens issued by it. Browser mutations require the session CSRF token.

# Grant a scoped role to a member (members.manage)
Source: https://docs.ankra.ai/api-reference/organisation-iam/grant-a-scoped-role-to-a-member-membersmanage

https://platform.ankra.app/openapi.json post /api/v1/org/organisation/assignments
Assigns a built-in role (`role_slug`) or custom role (`role_id`) to a member at `scope_type` `organisation`, `cluster` or `cluster_group` (with `scope_id` for the latter two). Requires `members.manage`; returns 409 when the same assignment already exists.

# List GitHub Actions trust policies
Source: https://docs.ankra.ai/api-reference/organisation-iam/list-github-actions-trust-policies

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/oidc-trust-policies
Requires members.manage in the authenticated organisation; service accounts are refused. Creating a policy provisions its service account and refuses role escalation. Removing a policy revokes tokens issued by it. Browser mutations require the session CSRF token.

# List GitHub Actions trust policies for a browser session
Source: https://docs.ankra.ai/api-reference/organisation-iam/list-github-actions-trust-policies-for-a-browser-session

https://platform.ankra.app/openapi.json get /org/organisation/oidc-trust-policies
Requires members.manage in the authenticated organisation; service accounts are refused. Creating a policy provisions its service account and refuses role escalation. Removing a policy revokes tokens issued by it. Browser mutations require the session CSRF token.

# List member role assignments (members.read)
Source: https://docs.ankra.ai/api-reference/organisation-iam/list-member-role-assignments-membersread

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/members/{ankra_user_id}/assignments
Lists the role assignments of one organisation member, each with its role and scope. Requires `members.read`.

# List organisation role assignments (members.read)
Source: https://docs.ankra.ai/api-reference/organisation-iam/list-organisation-role-assignments-membersread

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/assignments
Lists the live role assignments of every active member of the organisation in one read, at organisation, cluster and cluster-group scope, each with the member's `ankra_user_id` and `user_id`. Ordered by member, then age. At most 5000 assignments are returned (`limit`); `truncated` is true when the organisation holds more, and the per-member listing stays complete for one person. Requires `members.read`.

# List organisation roles (members.read)
Source: https://docs.ankra.ai/api-reference/organisation-iam/list-organisation-roles-membersread

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/roles
Lists the built-in role definitions together with the organisation's custom roles. Requires `members.read`.

# List the organisations of the person signed in to Ankra Cloud
Source: https://docs.ankra.ai/api-reference/organisation-iam/list-the-organisations-of-the-person-signed-in-to-ankra-cloud

https://platform.ankra.app/openapi.json get /api/v1/cloud/me/organisations
Read-only organisation directory for Ankra Cloud. The credential is the identity provider's access token of the person, issued for the dedicated directory audience to an authorised Ankra Cloud client; personal access tokens and browser sessions are not accepted. Answers the organisations the person is an active member of, and an empty list for a person with none. No session is created and no organisation is selected.

# Reconcile a Cloud workspace organisation and membership
Source: https://docs.ankra.ai/api-reference/organisation-iam/reconcile-a-cloud-workspace-organisation-and-membership

https://platform.ankra.app/openapi.json post /api/v1/cloud/workspaces/sync
Dedicated Cloud machine authentication. Target organisations are created once or adopted through server-managed configuration. Complete monotonic snapshots own member names, roles, and revocations; no organisation ID is accepted from the caller.

# Remove a GitHub Actions trust policy
Source: https://docs.ankra.ai/api-reference/organisation-iam/remove-a-github-actions-trust-policy

https://platform.ankra.app/openapi.json delete /api/v1/org/organisation/oidc-trust-policies/{policy_id}
Requires members.manage in the authenticated organisation; service accounts are refused. Creating a policy provisions its service account and refuses role escalation. Removing a policy revokes tokens issued by it. Browser mutations require the session CSRF token.

# Remove a GitHub Actions trust policy for a browser session
Source: https://docs.ankra.ai/api-reference/organisation-iam/remove-a-github-actions-trust-policy-for-a-browser-session

https://platform.ankra.app/openapi.json delete /org/organisation/oidc-trust-policies/{policy_id}
Requires members.manage in the authenticated organisation; service accounts are refused. Creating a policy provisions its service account and refuses role escalation. Removing a policy revokes tokens issued by it. Browser mutations require the session CSRF token.

# Replace custom role permissions (members.manage)
Source: https://docs.ankra.ai/api-reference/organisation-iam/replace-custom-role-permissions-membersmanage

https://platform.ankra.app/openapi.json patch /api/v1/org/organisation/roles/{role_id}
Replaces a custom role's name, description, permissions and Kubernetes grants with the values sent; members holding the role get the new permissions. Requires `members.manage`.

# Retire a custom role and its assignments (members.manage)
Source: https://docs.ankra.ai/api-reference/organisation-iam/retire-a-custom-role-and-its-assignments-membersmanage

https://platform.ankra.app/openapi.json delete /api/v1/org/organisation/roles/{role_id}
Deletes a custom role that no active member holds. While anyone still holds it the delete is refused with 409 `{"detail": "<N people> still hold <role name>. Give them another role first.", "reason": "role_in_use"}`: give them another role first. Requires `members.manage`; returns 404 when the role does not exist.

# Revoke a scoped role assignment (members.manage)
Source: https://docs.ankra.ai/api-reference/organisation-iam/revoke-a-scoped-role-assignment-membersmanage

https://platform.ankra.app/openapi.json delete /api/v1/org/organisation/assignments/{assignment_id}
Revokes one role assignment. Requires `members.manage`; the last organisation-wide owner assignment cannot be removed.

# Claim an email domain for single sign-on
Source: https://docs.ankra.ai/api-reference/organisation/claim-an-email-domain-for-single-sign-on

https://platform.ankra.app/openapi.json post /org/organisation/{organisation_id}/sso/domains
Claims an email domain for the connection and answers the TXT record (`_ankra-challenge.<domain>`) that proves the organisation controls it. Public email providers cannot be claimed, and a domain another organisation has already verified is refused.

# Configure the organisation's identity provider
Source: https://docs.ankra.ai/api-reference/organisation/configure-the-organisations-identity-provider

https://platform.ankra.app/openapi.json put /org/organisation/{organisation_id}/sso
Connects the organisation's own OpenID Connect identity provider, or replaces its issuer and client. The client secret is forwarded to the identity broker and stored nowhere in Ankra, so it is required on the first save and whenever the issuer or client ID changes. The configuring administrator becomes the connection's first break-glass member.

# Create a new organisation
Source: https://docs.ankra.ai/api-reference/organisation/create-a-new-organisation

https://platform.ankra.app/openapi.json post /api/v1/org/organisation
Creates a new organisation on the free plan with the calling user as its owner, from a `name` and optional `country`. Returns 201 with the new organisation.

# Delete organisation logo
Source: https://docs.ankra.ai/api-reference/organisation/delete-organisation-logo

https://platform.ankra.app/openapi.json delete /org/organisation/{organisation_id}/logo
Removes the organisation's logo. Requires `organisation.manage`.

# Delete user from organisation
Source: https://docs.ankra.ai/api-reference/organisation/delete-user-from-organisation

https://platform.ankra.app/openapi.json delete /api/v1/org/organisation/user
Removes a user (`user_id`) from an organisation (`organisation_id`). Users may remove themselves; removing someone else requires `members.manage`, and the last user of an organisation cannot be removed.

# Ensure the cluster repository webhook
Source: https://docs.ankra.ai/api-reference/organisation/ensure-the-cluster-repository-webhook

https://platform.ankra.app/openapi.json post /org/clusters/{cluster_id}/webhook/ensure
Browser session authentication; ensures the cluster's connected GitOps repository carries the platform webhook, creating or repairing it (the repository-settings 'ensure webhook' action). Rate limited per cluster: a burst answers 429 with Retry-After. A cluster with no connected repository answers 404 with the reason in detail. Browser route only; there is no bearer-PAT twin yet (the route census's twin-gap ratchet lists it).

# Export the organisation audit log
Source: https://docs.ankra.ai/api-reference/organisation/export-the-organisation-audit-log

https://platform.ankra.app/openapi.json get /org/organisation/audit-logs/export
Downloads the organisation audit log as a CSV (default) or JSON attachment (`format=csv|json`), using the same filters as the listing. Requires `audit.read`; at most 100,000 rows are exported, and a truncated CSV is flagged with the `X-Ankra-Export-Truncated: true` header while JSON carries a `truncated` field.

# Export the organisation audit log with an API token
Source: https://docs.ankra.ai/api-reference/organisation/export-the-organisation-audit-log-with-an-api-token

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/audit-logs/export
Bearer twin of GET /org/organisation/audit-logs/export for scheduled jobs such as SIEM forwarding. Accepts a personal or service-account API token; the token (its scopes and its role) must hold audit.read in the organisation. Same filters, formats, 100000-row cap and organisation scope as the session export. The organisation is the token's own, or the one named by the X-Ankra-Organisation-Id header when the token's user is a member of it; a service-account token cannot leave its organisation.

# Get organisation details
Source: https://docs.ankra.ai/api-reference/organisation/get-organisation-details

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/{organisation_id}
Returns one organisation the calling user belongs to, with its members. Returns 404 when the organisation does not exist or the caller is not a member.

# Get organisation logo
Source: https://docs.ankra.ai/api-reference/organisation/get-organisation-logo

https://platform.ankra.app/openapi.json get /api/v1/org/organisation/{organisation_id}/logo
Returns the organisation's logo image with its stored content type, or 404 when none is set. The logo is readable by active members of the organisation, and by any caller while the organisation publishes a stack profile that caller can see (public, or shared with the caller's organisation), which is how stack profile cards show the publisher's logo. Anyone else gets the same 404 as an organisation without a logo. Responses carry an `ETag` and honour `If-None-Match` (304); adding a `v` query parameter makes the response cacheable for a year.

# Get organisation logo (browser session)
Source: https://docs.ankra.ai/api-reference/organisation/get-organisation-logo-browser-session

https://platform.ankra.app/openapi.json get /org/organisation/{organisation_id}/logo
Returns the organisation's logo image with its stored content type, or 404 when none is set. The logo is readable by active members of the organisation, and by any caller while the organisation publishes a stack profile that caller can see (public, or shared with the caller's organisation), which is how stack profile cards show the publisher's logo. Anyone else gets the same 404 as an organisation without a logo. Responses carry an `ETag` and honour `If-None-Match` (304); adding a `v` query parameter makes the response cacheable for a year.

# Get organisation single sign-on settings
Source: https://docs.ankra.ai/api-reference/organisation/get-organisation-single-sign-on-settings

https://platform.ankra.app/openapi.json get /org/organisation/{organisation_id}/sso
The organisation's single sign-on settings: the connected identity provider, its policy, the claimed email domains with the DNS records that prove them, the group-to-role mappings, the redirect URI to register with the provider and the organisation's sign-in link. Requires organisation.manage. `is_available` is false while single sign-on is switched off for the installation.

# Invite user to organisation
Source: https://docs.ankra.ai/api-reference/organisation/invite-user-to-organisation

https://platform.ankra.app/openapi.json post /api/v1/org/organisation/invite
Invites a user by email into an organisation with the role `member`, `admin` or `read-only` and emails them the invitation. Only organisation admins may invite (403 otherwise); returns 400 when an invite already exists or the plan's member limit is reached.

# List organisations
Source: https://docs.ankra.ai/api-reference/organisation/list-organisations

https://platform.ankra.app/openapi.json get /api/v1/org/organisation
Lists the organisations the calling user is an active member of, sorted by name, with the user's role in each.

# List the audit log of one cluster
Source: https://docs.ankra.ai/api-reference/organisation/list-the-audit-log-of-one-cluster

https://platform.ankra.app/openapi.json get /org/clusters/{cluster_id}/audit-logs
Returns one cluster's slice of the organisation audit log, paginated with `page` and `page_size` (default 50) and filterable like the organisation listing. Requires `audit.read`; returns 404 when the cluster is not in the organisation.

# Remove a claimed email domain
Source: https://docs.ankra.ai/api-reference/organisation/remove-a-claimed-email-domain

https://platform.ankra.app/openapi.json delete /org/organisation/{organisation_id}/sso/domains/{domain_id}
Removes a claimed domain. The last verified domain of an enabled connection cannot be removed, because every sign-in through the connection would then be refused.

# Remove organisation single sign-on
Source: https://docs.ankra.ai/api-reference/organisation/remove-organisation-single-sign-on

https://platform.ankra.app/openapi.json delete /org/organisation/{organisation_id}/sso
Removes the organisation's single sign-on connection. Members keep the state they are in - suspended members stay suspended - and accounts that existed only through the connection are released so their owners can sign up again with the same address.

# Replace the group-to-role mappings
Source: https://docs.ankra.ai/api-reference/organisation/replace-the-group-to-role-mappings

https://platform.ankra.app/openapi.json put /org/organisation/{organisation_id}/sso/group-mappings
Replaces the group-to-role mappings. While any exist, every sign-in the provider vouches for sets the member's role from the groups the provider asserts: the highest mapped role wins, a member in no mapped group gets the default role, and owner is never mapped.

# Store organisation logo
Source: https://docs.ankra.ai/api-reference/organisation/store-organisation-logo

https://platform.ankra.app/openapi.json put /org/organisation/{organisation_id}/logo
Uploads the organisation's logo as the multipart `file` field, replacing any existing one. Accepts PNG, JPEG or WebP up to 512 KiB within a maximum pixel size; requires `organisation.manage`.

# Switch user organisation
Source: https://docs.ankra.ai/api-reference/organisation/switch-user-organisation

https://platform.ankra.app/openapi.json post /api/v1/org/organisation/switch
Switches the calling user's active organisation to `organisation_id`. Returns 403 when the user is not permitted to join that organisation.

# Update organisation single sign-on policy
Source: https://docs.ankra.ai/api-reference/organisation/update-organisation-single-sign-on-policy

https://platform.ankra.app/openapi.json patch /org/organisation/{organisation_id}/sso
Changes the single sign-on policy: whether it is enabled, whether it is required for members on the verified domains, just-in-time membership and its default role, the re-verification window after which a member the provider no longer vouches for is suspended, and the break-glass members who keep their other sign-in methods. Enabling needs a verified domain; requiring needs one successful single sign-on login first; the break-glass list can never be emptied.

# Verify a claimed email domain by its DNS record
Source: https://docs.ankra.ai/api-reference/organisation/verify-a-claimed-email-domain-by-its-dns-record

https://platform.ankra.app/openapi.json post /org/organisation/{organisation_id}/sso/domains/{domain_id}/verify
Looks up the domain's challenge record and marks the domain verified when the record is published. Until then the answer is 422 with the record to publish; DNS changes can take a few minutes to appear.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/ovh-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/vms
Adds a standalone VM with the given `name` and `instance_type` on the cluster network; its location defaults to the bastion's. On a running cluster its creation starts at once and the result carries the `operation_id`; on a stopped cluster it is created at the next start. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Add node group
Source: https://docs.ankra.ai/api-reference/ovh-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/node-groups
Adds a worker node group with the given `name`, `instance_type` and `count` (default 1), plus optional labels, taints and autoscaling settings. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/ovh-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Create an OVH cluster
Source: https://docs.ankra.ai/api-reference/ovh-clusters/create-an-ovh-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh
Creates an OVH cluster from the request and starts provisioning it in the background, answering 201 with the new cluster's `cluster_id` and `name`. A configuration that fails validation answers 400 with the reason, and an organisation whose billing is restricted is refused with 402. A cluster name already in use answers 409 and an unknown credential 404.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/ovh-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/ovh/{cluster_id}/vms/{vm_id}
Deletes a standalone VM: it is handed to teardown and its server is removed at the provider. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Delete node group
Source: https://docs.ankra.ai/api-reference/ovh-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/ovh/{cluster_id}/node-groups/{group_name}
Removes a node group by draining and deleting its workers one at a time through their PodDisruptionBudgets; a worker whose drain is refused stays in service and the operation fails with the reason. Pass `force_drain=true` to take the whole group down regardless. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result. Requires `clusters.delete`.

# Deprovision an OVH cluster
Source: https://docs.ankra.ai/api-reference/ovh-clusters/deprovision-an-ovh-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/ovh/{cluster_id}
Deletes the cluster and its cloud resources. A delete that would remove persistent volumes, or cannot tell whether it does, is refused with 409 unless `accept_volume_data_loss=true` is passed (see the deprovision-volumes read); `force=true` tolerates infrastructure that can no longer be reached. Active operations on the cluster are cancelled and the response carries the teardown's `operation_id`.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/ovh-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/ovh-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `ovh_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/ovh-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself.

# Get bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/ovh-clusters/get-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.read`. Returns the cluster's stored bastion SSH source allowlist, as the update on the same path stored it. `configured` tells a cleared list (true, empty) from one that was never set (false, empty); both leave SSH open from anywhere.

# Get current Kubernetes version
Source: https://docs.ankra.ai/api-reference/ovh-clusters/get-current-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/k8s-version
Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Get current worker count
Source: https://docs.ankra.ai/api-reference/ovh-clusters/get-current-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/worker-count
Returns the cluster's current worker count and the minimum and maximum it can be scaled to.

# Get disabled K3s components
Source: https://docs.ankra.ai/api-reference/ovh-clusters/get-disabled-k3s-components

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/k3s-disabled-components
Read the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), on top of the provider shape's own defaults. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states (a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider) answer 409 with a detail message.

# Latest restorable state snapshot of a OVH cluster
Source: https://docs.ankra.ai/api-reference/ovh-clusters/latest-restorable-state-snapshot-of-a-ovh-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the OVH cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List node groups
Source: https://docs.ankra.ai/api-reference/ovh-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/node-groups
Lists the cluster's worker node groups with each group's instance type, node count, autoscaling bounds, labels and taints.

# List nodes
Source: https://docs.ankra.ai/api-reference/ovh-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/nodes
Lists the cluster's machines with each one's role, node group, instance type, location, state, private and public IPs, the kubelet version it reports and, where recorded, the provider's own status.

# List OVH flavors available to a credential in a region
Source: https://docs.ankra.ai/api-reference/ovh-clusters/list-ovh-flavors-available-to-a-credential-in-a-region

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/flavors
Return the OVH Cloud instance flavors the supplied credential's project can deploy in the given region. Only available flavors are valid for cluster creation.

# List OVH regions available to a credential
Source: https://docs.ankra.ai/api-reference/ovh-clusters/list-ovh-regions-available-to-a-credential

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/regions
Return the OVH Cloud regions the supplied credential's project can deploy in. Only these regions are valid for cluster creation.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/ovh-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/vms
Lists the cluster's standalone VMs (servers on the cluster network that are not Kubernetes nodes) with their instance type, location, state, addresses and provider ID.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/ovh-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/control-plane
Returns the control-plane count, the counts the cluster supports, the control planes' instance type, and whether a count or instance-type change is possible right now, with the reason when it is not.

# Read node
Source: https://docs.ankra.ai/api-reference/ovh-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/nodes/{node_id}
Returns one machine of the cluster with its definition, its latest recorded info and data, and its dependencies and relationships. Answers 404 when the node is not part of the cluster.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/ovh-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `ovh_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/ovh-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/access-info
Returns what you need to reach the cluster's machines over SSH: the bastion's public IP, the control-plane IPs and the cluster name.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/ovh-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/ssh-keys
Returns the SSH key credentials authorised on the cluster's servers (`ssh_key_credential_ids`) and the organisation's SSH key credentials that can be attached.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/ovh-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/vms/{vm_id}/instance-type
Resizes a standalone VM in place to the given `instance_type`. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/ovh-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/control-plane/instance-type
Changes the instance type of every control plane. On a running cluster the control planes are resized one at a time behind an etcd quorum check and a drain, and the response carries the `operation_id` to follow (clusters with fewer than three control planes are refused); on a stopped cluster the new type is applied at the next start and no operation is returned.

# Resize node group
Source: https://docs.ankra.ai/api-reference/ovh-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/node-groups/{group_name}/instance-type
Changes the instance type of every worker in the node group. Each node is power-cycled, so the workers are drained and resized in bounded batches; `force_drain` bypasses PodDisruptionBudgets for that drain. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/ovh-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/ssh-keys/resync
Re-applies the cluster's configured SSH keys to its servers and returns the IDs of the resources queued for the update.

# Scale node group
Source: https://docs.ankra.ai/api-reference/ovh-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/node-groups/{group_name}/scale
Sets the node group's node count to `count`. A scale-down drains the removed workers through their PodDisruptionBudgets; `force_drain` bypasses them for this request. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Scale OVH cluster workers
Source: https://docs.ankra.ai/api-reference/ovh-clusters/scale-ovh-cluster-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/scale-workers
Sets the cluster's worker count to `worker_count` and returns the previous and new counts. A scale-down drains the removed workers through their PodDisruptionBudgets unless `force_drain` is true. Requires `clusters.operate`.

# Start an OVH cluster
Source: https://docs.ankra.ai/api-reference/ovh-clusters/start-an-ovh-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/start
Recreate the OVH cloud resources for a stopped cluster and reconcile it back to a running state.

# Stop an OVH cluster
Source: https://docs.ankra.ai/api-reference/ovh-clusters/stop-an-ovh-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/stop
Initiate async deletion of OVH cloud resources (servers, networks, SSH keys) without removing the cluster from the database.

# The persistent volumes deleting a OVH cluster removes
Source: https://docs.ankra.ai/api-reference/ovh-clusters/the-persistent-volumes-deleting-a-ovh-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/ovh/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/ovh/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none.

# Update bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.write`. Replaces the cluster's bastion SSH source allowlist and dispatches the bastion update that applies it: the bastion's SSH port then accepts only the listed IPv4 sources, the platform's own egress addresses and private network sources, and drops everything else. An empty list clears the allowlist. Clusters that never set one keep SSH open from anywhere.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/control-plane
Changes the number of control planes to `count`. On a running cluster the control plane can only grow, and the new control planes join live (`mode` `rolling`, with an `operation_id` to follow); a reduction is applied offline to a stopped cluster and takes effect at its next start.

# Update disabled K3s components
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-disabled-k3s-components

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/k3s-disabled-components
Replace the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), for example ["traefik"] on a cluster that brings its own ingress. k3s distribution only. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states answer 409 with a detail message: a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider, a list that drops a stored entry (re-enabling a bundled component is not supported yet, so the list only grows), a list that adds coredns (load-bearing for in-cluster DNS), and any change while a node update, version upgrade or node restart is in progress on the cluster.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/node-groups/{group_name}/labels
Replaces the Kubernetes labels on every node in the node group with the given `labels` map. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/node-groups/{group_name}/taints
Replaces the taints on every node in the node group with the given `taints` list (each a `key`, an optional `value` and an `effect` of `NoSchedule`, `PreferNoSchedule` or `NoExecute`). By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update OVH gateway model
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-ovh-gateway-model

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/gateway-model
Invalid states (unsupported model, non-OVH cluster, no recorded managed gateway, no active network resource) answer 409 with a detail message.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/ovh-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/ovh/{cluster_id}/ssh-keys
Replaces the SSH key credentials authorised on the cluster's servers with `ssh_key_credential_ids` and starts rolling the keys out. An unknown or repeated credential, or two credentials carrying the same public key, is refused with 409.

# Upgrade Kubernetes version
Source: https://docs.ankra.ai/api-reference/ovh-clusters/upgrade-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/ovh/{cluster_id}/upgrade-k8s-version
Upgrades the cluster to `target_version`, which must be in the supported version catalogue and must not downgrade or skip a minor version. The cluster must be online with no change in progress; the nodes are upgraded as a rolling operation whose `operation_id` is returned, and `force` continues past a node drain that PodDisruptionBudgets refuse.

# Create an OVH API credential
Source: https://docs.ankra.ai/api-reference/ovh-credentials/create-an-ovh-api-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/ovh
Creates an OVH credential from `name`, `application_key`, `application_secret`, `consumer_key` and `project_id`. The keys are checked against the OVH API before they are stored in Vault; credentials that fail the check answer 400. Requires `credentials.write`; answers 201.

# Create an SSH key credential
Source: https://docs.ankra.ai/api-reference/ovh-credentials/create-an-ssh-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/ovh/ssh-key
Creates an SSH key credential from `name` and either `ssh_public_key` or `generate=true`; a generated RSA-4096 key pair's private key is returned once, in this response. A public key the organisation already stores under another credential is refused with 400. Requires `credentials.write`; answers 201.

# Get OVH credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/ovh-credentials/get-ovh-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/ovh/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the OVH API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get OVH credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/ovh-credentials/get-ovh-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/ovh/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the OVH limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# List OVH API credentials
Source: https://docs.ankra.ai/api-reference/ovh-credentials/list-ovh-api-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/ovh
Lists the organisation's OVH API credentials with their metadata; the secret material is never returned.

# List SSH key credentials
Source: https://docs.ankra.ai/api-reference/ovh-credentials/list-ssh-key-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/ovh/ssh-keys
Lists the organisation's SSH key credentials. The list is the same under every cloud provider. Each item carries the stored public key with the fingerprint (as `ssh-keygen -l` prints it), key type and comment derived from it; a stored value that is not a readable key keeps its row, with a null `fingerprint` and `fingerprint_error` saying why.

# Add a pull request to a repository's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/add-a-pull-request-to-a-repositorys-merge-train

https://platform.ankra.app/openapi.json post /api/v1/org/pipeline-repositories/{repository_id}/merge-train/entries
Puts a pull request at the end of the repository's merge train. Ankra tests it squashed onto the base branch and the pull requests ahead of it, exactly as the merge will land, and merges it through the host's own merge when that run passes. A pull request already in the train answers its entry with 200. A pull request based on the branch of another pull request in the train is stacked on it: tested on its car and merged after it, retargeted onto the base branch first; one based on a pull request that is not in the train is refused with 409. Must be called by a person, not a service account token. The caller must also be an organisation administrator, the pull request's author, or a member with write access to the repository on GitHub, as GitHub reports it for the caller's OAuth-verified GitHub identity. Requires pipelines.operate.

# Add a pull request to an application's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/add-a-pull-request-to-an-applications-merge-train

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/merge-train/entries
Puts a pull request at the end of the repository's merge train. Ankra tests it squashed onto the base branch and the pull requests ahead of it, exactly as the merge will land, and merges it through the host's own merge when that run passes. A pull request already in the train answers its entry with 200. A pull request based on the branch of another pull request in the train is stacked on it: tested on its car and merged after it, retargeted onto the base branch first; one based on a pull request that is not in the train is refused with 409. Addressed by application: the merge train of the pipeline repository the application is connected to. Must be called by a person, not a service account token. The caller must also be an organisation administrator, the pull request's author, or a member with write access to the repository on GitHub, as GitHub reports it for the caller's OAuth-verified GitHub identity. Requires pipelines.operate.

# Add or re-weight a CI pool member
Source: https://docs.ankra.ai/api-reference/pipelines/add-or-re-weight-a-ci-pool-member

https://platform.ankra.app/openapi.json put /api/v1/org/ci-settings/pool/{cluster_id}
Lists one cluster in the organisation's CI pool, or changes its weight. The cluster must be a live cluster of this organisation whose agent advertises pipeline steps, and in no other organisation's pool. Answers 201 when the cluster was newly listed. Organisation admins only. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication; writes also need the X-Ankra-CSRF header).

# Change a repository's CI cluster
Source: https://docs.ankra.ai/api-reference/pipelines/change-a-repositorys-ci-cluster

https://platform.ankra.app/openapi.json patch /api/v1/org/pipelines/repositories/{repository_id}
Changes a connected repository's CI cluster override (or clears it with null), its Workspaces-only mode, or both, without disconnecting the repository. The cluster must be a live cluster of this organisation whose agent advertises pipeline steps. It changes where the repository's next runs go: runs already queued or running keep the cluster they were pinned to. A Workspaces-only repository starts no pipeline run from any trigger, posts no commit status or check run and records no pipeline definition, while workspaces keep working; turning the mode on is refused with 409 while a run is queued or running. Needs pipelines.manage. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Compare a repository version with the tracked branch
Source: https://docs.ankra.ai/api-reference/pipelines/compare-a-repository-version-with-the-tracked-branch

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-source
Resolves an immutable tag through owned successful publish outputs, then reads the source provider graph against the actual tracked branch head. Missing, ambiguous and unavailable evidence has no commit count. Requires pipelines.read. Read-only.

# Compare an application version with the tracked branch
Source: https://docs.ankra.ai/api-reference/pipelines/compare-an-application-version-with-the-tracked-branch

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-source
Resolves an immutable tag through owned successful publish outputs, then reads the source provider graph against the actual tracked branch head. Missing, ambiguous and unavailable evidence has no commit count. Requires pipelines.read. Read-only.

# Connect a repository
Source: https://docs.ankra.ai/api-reference/pipelines/connect-a-repository

https://platform.ankra.app/openapi.json post /api/v1/org/pipelines/repositories
Connects a repository to the organisation. By default it becomes a pipeline repository: its committed .ankra/pipeline.yaml is read from the default branch through the named credential and recorded as the definition of record, and pushes, pull requests and tags start runs. With workspaces_only true it is connected for Ankra Workspaces only: the pipeline file is not read, no definition is recorded, no run is started from any trigger and no commit status or check run is posted, which suits a repository whose pipeline already runs in another organisation. A disconnected repository with the same identity is revived. Needs pipelines.manage. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Count application releases in flight
Source: https://docs.ankra.ai/api-reference/pipelines/count-application-releases-in-flight

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-release-queue
Organisation, repository and application scoped. Requires pipelines.read. Counts do not use pagination; deployment identity never certifies live readiness. No execution output is exposed.

# Count repository releases in flight
Source: https://docs.ankra.ai/api-reference/pipelines/count-repository-releases-in-flight

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-release-queue
Organisation, repository and application scoped. Requires pipelines.read. Counts do not use pagination; deployment identity never certifies live readiness. No execution output is exposed.

# Dismiss a pipeline authority request
Source: https://docs.ankra.ai/api-reference/pipelines/dismiss-a-pipeline-authority-request

https://platform.ankra.app/openapi.json post /api/v1/org/pipelines/authority-requests/{id}/dismiss
Declines a pending request with a reason the run's check run and run page then show. Requires pipelines.manage and a human actor: a service-account token is refused. A request already approved, dismissed or superseded answers 409.

# Get a repository's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/get-a-repositorys-merge-train

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/merge-train
The repository's Ankra merge train: whether it is enabled and how many cars it tests at once, the pull requests in it in order with each car's base, tree and pipeline run, and the most recently settled entries. Requires pipelines.read. Read-only.

# Get a repository's merge train lead time
Source: https://docs.ankra.ai/api-reference/pipelines/get-a-repositorys-merge-train-lead-time

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/merge-train/lead-time
How long the repository's merged pull requests took from ready to production over the last day and the last week: p50 and p90 with the count, each segment's spread (admission wait, queue, failed cars, the car that passed, merge, deploy), failed car runs by class, the merges not deployed or not recorded yet, and the three slowest with the segment that held each up. Recorded by the pipeline_lead_time maintenance loop. Requires pipelines.read. Read-only.

# Get a repository's test quarantine
Source: https://docs.ankra.ai/api-reference/pipelines/get-a-repositorys-test-quarantine

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/quarantine
The repository's flaky test quarantine: whether it is on and its thresholds, the tests quarantined now, and the ones released in the last 30 days. A quarantined test still runs and is reported; a failing run step whose only failed tests are quarantined settles as a success. Requires pipelines.read. Read-only.

# Get a run's resource suggestions
Source: https://docs.ankra.ai/api-reference/pipelines/get-a-runs-resource-suggestions

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-runs/{run_id}/resource-suggestions
Right-sizing advice for the stages of the pipeline definition a run was planned from: for each stage, the 95th percentile of what its latest successful attempts used, plus 25% headroom, against what it asks for, with how many samples it rests on. Memory is sized from the kernel's memory peak; a stage whose peak reached its limit is at_limit with no suggestion. CPU is sized from mean cores and suggests the request. Only the caller's organisation's runs are counted. Requires pipelines.read. Read-only: nothing is written back to the definition.

# Get a test's history on a repository branch
Source: https://docs.ankra.ai/api-reference/pipelines/get-a-tests-history-on-a-repository-branch

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/history
One test's outcome in the newest runs of a branch that recorded it, and its flaky and failure rates over them. Requires pipelines.read. Read-only.

# Get a test's history on an application branch
Source: https://docs.ankra.ai/api-reference/pipelines/get-a-tests-history-on-an-application-branch

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-tests/history
One test's outcome in the newest runs of a branch that recorded it, and its flaky and failure rates over them. Requires pipelines.read. Read-only.

# Get an application run's resource suggestions
Source: https://docs.ankra.ai/api-reference/pipelines/get-an-application-runs-resource-suggestions

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/resource-suggestions
The same advice addressed by application. Right-sizing advice for the stages of the pipeline definition a run was planned from: for each stage, the 95th percentile of what its latest successful attempts used, plus 25% headroom, against what it asks for, with how many samples it rests on. Memory is sized from the kernel's memory peak; a stage whose peak reached its limit is at_limit with no suggestion. CPU is sized from mean cores and suggests the request. Only the caller's organisation's runs are counted. Requires pipelines.read. Read-only: nothing is written back to the definition.

# Get an application's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/get-an-applications-merge-train

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/merge-train
The repository's Ankra merge train: whether it is enabled and how many cars it tests at once, the pull requests in it in order with each car's base, tree and pipeline run, and the most recently settled entries. Addressed by application: the merge train of the pipeline repository the application is connected to. Requires pipelines.read. Read-only.

# Get an application's merge train lead time
Source: https://docs.ankra.ai/api-reference/pipelines/get-an-applications-merge-train-lead-time

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/merge-train/lead-time
How long the repository's merged pull requests took from ready to production over the last day and the last week: p50 and p90 with the count, each segment's spread (admission wait, queue, failed cars, the car that passed, merge, deploy), failed car runs by class, the merges not deployed or not recorded yet, and the three slowest with the segment that held each up. Recorded by the pipeline_lead_time maintenance loop. Requires pipelines.read. Read-only. Addressed by application: the lead time of the pipeline repository the application is connected to.

# Get an application's test quarantine
Source: https://docs.ankra.ai/api-reference/pipelines/get-an-applications-test-quarantine

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-tests/quarantine
The repository's flaky test quarantine: whether it is on and its thresholds, the tests quarantined now, and the ones released in the last 30 days. A quarantined test still runs and is reported; a failing run step whose only failed tests are quarantined settles as a success. Requires pipelines.read. Read-only.

# Get the recorded test timings of a repository's stage
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-recorded-test-timings-of-a-repositorys-stage

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/timings
The mean recorded duration of each file or test of one stage across the newest runs of a branch, for a sharding script to balance by. Requires pipelines.read. Read-only.

# Get the recorded test timings of an application's stage
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-recorded-test-timings-of-an-applications-stage

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-tests/timings
The mean recorded duration of each file or test of one stage across the newest runs of a branch, for a sharding script to balance by. Requires pipelines.read. Read-only.

# Get the test results of a repository pipeline run
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-test-results-of-a-repository-pipeline-run

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-runs/{run_id}/tests
The test reports the run's steps declared with test_results and what became of each, the tests by outcome across them, and the failed, flaky and slowest tests. Requires pipelines.read. Read-only.

# Get the test results of an application pipeline run
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-test-results-of-an-application-pipeline-run

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/tests
The test reports the run's steps declared with test_results and what became of each, the tests by outcome across them, and the failed, flaky and slowest tests. Requires pipelines.read. Read-only.

# Get the time a repository's pipeline saved
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-time-a-repositorys-pipeline-saved

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-time-saved
The CI time one repository's runs did not spend over the last 7 or 30 days, in total, by reason and by UTC day. Each saving is estimated when the run is planned or skipped, from the stage's own history in the same repository: the median of its newest 20 successful runs among the repository's newest 300 concluded runs (a promoted step uses its duration in the run it was promoted from; a whole run uses the median total of the newest 20 successful runs of the same trigger). CPU-minutes are requested CPU times duration. A stage with no history is counted as unknown, never as a saving. The time is runner time, not wall-clock time. Requires pipelines.read. Read-only.

# Get the time a run saved
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-time-a-run-saved

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-runs/{run_id}/time-saved
The CI time one run did not spend: the stages a path filter left out, the stages skipped because a stage they need was left out, the steps a promoted publish did not run again, or the whole run when its trigger's paths excluded it. Each saving is estimated when the run is planned or skipped, from the stage's own history in the same repository: the median of its newest 20 successful runs among the repository's newest 300 concluded runs (a promoted step uses its duration in the run it was promoted from; a whole run uses the median total of the newest 20 successful runs of the same trigger). CPU-minutes are requested CPU times duration. A stage with no history is counted as unknown, never as a saving. The time is runner time, not wall-clock time. Requires pipelines.read. Read-only.

# Get the time an application run saved
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-time-an-application-run-saved

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/time-saved
The same savings addressed by application. Each saving is estimated when the run is planned or skipped, from the stage's own history in the same repository: the median of its newest 20 successful runs among the repository's newest 300 concluded runs (a promoted step uses its duration in the run it was promoted from; a whole run uses the median total of the newest 20 successful runs of the same trigger). CPU-minutes are requested CPU times duration. A stage with no history is counted as unknown, never as a saving. The time is runner time, not wall-clock time. Requires pipelines.read. Read-only.

# Get the time an application's pipeline saved
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-time-an-applications-pipeline-saved

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-time-saved
The same window summary addressed by application. Each saving is estimated when the run is planned or skipped, from the stage's own history in the same repository: the median of its newest 20 successful runs among the repository's newest 300 concluded runs (a promoted step uses its duration in the run it was promoted from; a whole run uses the median total of the newest 20 successful runs of the same trigger). CPU-minutes are requested CPU times duration. A stage with no history is counted as unknown, never as a saving. The time is runner time, not wall-clock time. Requires pipelines.read. Read-only.

# Get the time the organisation's pipelines saved
Source: https://docs.ankra.ai/api-reference/pipelines/get-the-time-the-organisations-pipelines-saved

https://platform.ankra.app/openapi.json get /api/v1/org/pipelines/time-saved
The CI time every pipeline repository the caller may see did not spend over the last 7 or 30 days, in total, by reason, by repository and by UTC day. Each saving is estimated when the run is planned or skipped, from the stage's own history in the same repository: the median of its newest 20 successful runs among the repository's newest 300 concluded runs (a promoted step uses its duration in the run it was promoted from; a whole run uses the median total of the newest 20 successful runs of the same trigger). CPU-minutes are requested CPU times duration. A stage with no history is counted as unknown, never as a saving. The time is runner time, not wall-clock time. Requires pipelines.read. Read-only.

# List a repository's pipeline caches
Source: https://docs.ankra.ai/api-reference/pipelines/list-a-repositorys-pipeline-caches

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-caches
The keyed cache volumes a pipeline repository keeps between runs, most recently used first by keyset. Each cache carries the cluster its volume lives on, when it lapses the organisation's cache retention, and whether its deletion has already been dispatched. Requires pipelines.read. Read-only.

# List a repository's test quarantine candidates
Source: https://docs.ankra.ai/api-reference/pipelines/list-a-repositorys-test-quarantine-candidates

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/quarantine/candidates
The tests of the repository's default branch that reach its quarantine thresholds over the last 30 days and are not quarantined, most flaky first. Only the branch's own runs count, never a pull request check. Requires pipelines.read. Read-only.

# List an application's pipeline caches
Source: https://docs.ankra.ai/api-reference/pipelines/list-an-applications-pipeline-caches

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-caches
The same listing addressed by application: the keyed cache volumes of the pipeline repository the application is connected to, most recently used first by keyset. Requires pipelines.read. Read-only.

# List an application's test quarantine candidates
Source: https://docs.ankra.ai/api-reference/pipelines/list-an-applications-test-quarantine-candidates

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-tests/quarantine/candidates
The tests of the repository's default branch that reach its quarantine thresholds over the last 30 days and are not quarantined, most flaky first. Only the branch's own runs count, never a pull request check. Requires pipelines.read. Read-only.

# List connected pipeline repositories
Source: https://docs.ankra.ai/api-reference/pipelines/list-connected-pipeline-repositories

https://platform.ankra.app/openapi.json get /api/v1/org/pipelines/repositories
Pages the organisation's connected repositories, newest first. provider, owner and name narrow the listing, so provider=github&owner=<owner>&name=<name> finds the repository a checkout's origin names, with its merge train settings, in one request. Needs pipelines.read. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# List pipeline authority requests
Source: https://docs.ankra.ai/api-reference/pipelines/list-pipeline-authority-requests

https://platform.ankra.app/openapi.json get /api/v1/org/pipelines/authority-requests
The approvals inbox: every request a pipeline run raised for protected settings (services, network, caches, resources, timeouts, permissions, secrets) no administrator has approved, newest first by keyset. Filter by status, repository or application. Requires pipelines.read. Approve one through POST /api/v1/org/pipelines/definitions/{definition_id}/approve; dismiss one through its dismiss route.

# Move a pull request to the front of a repository's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/move-a-pull-request-to-the-front-of-a-repositorys-merge-train

https://platform.ankra.app/openapi.json post /api/v1/org/pipeline-repositories/{repository_id}/merge-train/entries/{entry_id}/front
Puts a pull request ahead of every car in the merge train that is still queued, building or testing. Cars that already passed or are being merged ahead of it stay ahead. Every car it passes is rebuilt on top of it and its running test is stopped, so only an organisation administrator may move a pull request to the front, and a service account token is refused. An entry already at the front is answered unchanged. Requires pipelines.operate and organisation.manage.

# Move a pull request to the front of an application's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/move-a-pull-request-to-the-front-of-an-applications-merge-train

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/merge-train/entries/{entry_id}/front
Puts a pull request ahead of every car in the merge train that is still queued, building or testing. Cars that already passed or are being merged ahead of it stay ahead. Every car it passes is rebuilt on top of it and its running test is stopped, so only an organisation administrator may move a pull request to the front, and a service account token is refused. An entry already at the front is answered unchanged. Requires pipelines.operate and organisation.manage.

# Quarantine a flaky test of a repository
Source: https://docs.ankra.ai/api-reference/pipelines/quarantine-a-flaky-test-of-a-repository

https://platform.ankra.app/openapi.json post /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/quarantine
Quarantines one test of the repository. The quarantine must be on, and the test's default-branch record over the last 30 days must reach the repository's thresholds (min_flaky_rate over at least min_samples observed runs); its suite, name and file are copied from its newest recorded run. The decision is audited. Requires pipelines.manage.

# Quarantine a flaky test of an application
Source: https://docs.ankra.ai/api-reference/pipelines/quarantine-a-flaky-test-of-an-application

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/pipeline-tests/quarantine
Quarantines one test of the repository. The quarantine must be on, and the test's default-branch record over the last 30 days must reach the repository's thresholds (min_flaky_rate over at least min_samples observed runs); its suite, name and file are copied from its newest recorded run. The decision is audited. Requires pipelines.manage.

# Read a pipeline authority request
Source: https://docs.ankra.ai/api-reference/pipelines/read-a-pipeline-authority-request

https://platform.ankra.app/openapi.json get /api/v1/org/pipelines/authority-requests/{id}
One request: the run that raised it, the protected settings it asks for against the approved authority, where it stands and who decided it. Requires pipelines.read.

# Read a repository release for a merged pull request
Source: https://docs.ankra.ai/api-reference/pipelines/read-a-repository-release-for-a-merged-pull-request

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-runs/{run_id}/release
Reads the checked run and provider-confirmed full merge commit, then the exact owned push run on the tracked branch. Failed releases remain visible. A missing exact run is null; a newer commit is never substituted. Requires pipelines.read. Read-only.

# Read an application release for a merged pull request
Source: https://docs.ankra.ai/api-reference/pipelines/read-an-application-release-for-a-merged-pull-request

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/release
Reads the checked run and provider-confirmed full merge commit, then the exact owned push run on the tracked branch. Failed releases remain visible. A missing exact run is null; a newer commit is never substituted. Requires pipelines.read. Read-only.

# Read application deployment requests for this exact release
Source: https://docs.ankra.ai/api-reference/pipelines/read-application-deployment-requests-for-this-exact-release

https://platform.ankra.app/openapi.json get /api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/deployments
Organisation, repository and application scoped. Requires pipelines.read. Counts do not use pagination; deployment identity never certifies live readiness. No execution output is exposed.

# Read repository deployment requests for this exact release
Source: https://docs.ankra.ai/api-reference/pipelines/read-repository-deployment-requests-for-this-exact-release

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/pipeline-runs/{run_id}/deployments
Organisation, repository and application scoped. Requires pipelines.read. Counts do not use pagination; deployment identity never certifies live readiness. No execution output is exposed.

# Read the CPU and memory of the organisation's CI clusters
Source: https://docs.ankra.ai/api-reference/pipelines/read-the-cpu-and-memory-of-the-organisations-ci-clusters

https://platform.ankra.app/openapi.json get /api/v1/org/ci-settings/capacity/resources
The CPU and memory of the nodes each member of the organisation's CI pool places pipelines on: their summed allocatable, what every pod on them requests, and the part pipeline pods request, from the platform's mirror of each cluster. Members come primary first, as in the capacity read's pool_members. It is read apart from the capacity read because it reads every node and running pod of each cluster; each cluster's answer is reused for up to a minute. A member whose nodes could not be read answers state unknown with every figure null. Readable by any member. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read the organisation's CI cluster pool
Source: https://docs.ankra.ai/api-reference/pipelines/read-the-organisations-ci-cluster-pool

https://platform.ankra.app/openapi.json get /api/v1/org/ci-settings/pool
The clusters the organisation's pipeline runs are spread across, with each member's weight. The declared ci_cluster_id is always a member. Readable by any member. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication; writes also need the X-Ankra-CSRF header).

# Read the organisation's CI usage history
Source: https://docs.ankra.ai/api-reference/pipelines/read-the-organisations-ci-usage-history

https://platform.ankra.app/openapi.json get /api/v1/org/ci-settings/capacity/history
How the organisation's CI clusters have been used over a window of 24h, 7d or 30d, per cluster and per time bucket: steps started, the time-weighted average and peak number of steps running, the CPU and memory those steps requested and the CPU they used, and how long they waited for a slot. It is folded from the organisation's pipeline steps on its own clusters (steps Ankra's builders ran are not counted), so it reaches back no further than run_retention_days. A requested or used figure is null when steps ran and none recorded it and zero when nothing ran; request_coverage and usage_coverage give the share of step running time that recorded it. The slot count and node capacity at the time are not recorded; read today's from the capacity route. Readable by any member. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Read the organisation's pipeline capacity
Source: https://docs.ankra.ai/api-reference/pipelines/read-the-organisations-pipeline-capacity

https://platform.ankra.app/openapi.json get /api/v1/org/ci-settings/capacity
How much pipeline work the organisation's pipeline cluster can run at once and how much is waiting. ci_worker_count is the number of CI slots the cluster's agent runs: a slot is one pipeline step the agent watches at a time, not a node, and the nodes those steps land on come from the cluster's node group autoscaler. steps_in_flight_on_cluster counts every step occupying a slot on that cluster. The organisation_* counts are this organisation's own runs and steps: runs queued, runs counted against max_parallel_runs, pending steps, and the pending steps held back because every slot is taken (zero whenever a slot is free). is_live_resize_supported reports whether the cluster's agent applies a changed worker count without restarting. cluster_id and cluster_name are null, and the cluster's numbers zero, when no pipeline cluster is chosen. Readable by any member. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication).

# Release a repository's test quarantine
Source: https://docs.ankra.ai/api-reference/pipelines/release-a-repositorys-test-quarantine

https://platform.ankra.app/openapi.json post /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/quarantine/{quarantine_id}/release
Releases one live quarantine of the repository, so the test's failures fail its step again. The release is audited with its optional reason. Requires pipelines.manage.

# Release an application's test quarantine
Source: https://docs.ankra.ai/api-reference/pipelines/release-an-applications-test-quarantine

https://platform.ankra.app/openapi.json post /api/v1/org/applications/{application_id}/pipeline-tests/quarantine/{quarantine_id}/release
Releases one live quarantine of the repository, so the test's failures fail its step again. The release is audited with its optional reason. Requires pipelines.manage.

# Remove a CI pool member
Source: https://docs.ankra.ai/api-reference/pipelines/remove-a-ci-pool-member

https://platform.ankra.app/openapi.json delete /api/v1/org/ci-settings/pool/{cluster_id}
Unlists one cluster from the organisation's CI pool and answers the pool that remains. Runs already pinned to it finish there. Unlisting the declared ci_cluster_id removes only its weight: it stays the implicit primary member. Organisation admins only. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication; writes also need the X-Ankra-CSRF header).

# Remove a pull request from a repository's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/remove-a-pull-request-from-a-repositorys-merge-train

https://platform.ankra.app/openapi.json delete /api/v1/org/pipeline-repositories/{repository_id}/merge-train/entries/{entry_id}
Takes a pull request out of the repository's merge train and stops its car's run. A pull request being merged right now cannot be taken out. The member who put the entry in may take it out; anyone else must be an organisation administrator, the pull request's author, or a member with write access to the repository on GitHub, as GitHub reports it for the caller's OAuth-verified GitHub identity. Requires pipelines.operate.

# Remove a pull request from an application's merge train
Source: https://docs.ankra.ai/api-reference/pipelines/remove-a-pull-request-from-an-applications-merge-train

https://platform.ankra.app/openapi.json delete /api/v1/org/applications/{application_id}/merge-train/entries/{entry_id}
Takes a pull request out of the repository's merge train and stops its car's run. A pull request being merged right now cannot be taken out. Addressed by application: the merge train of the pipeline repository the application is connected to. The member who put the entry in may take it out; anyone else must be an organisation administrator, the pull request's author, or a member with write access to the repository on GitHub, as GitHub reports it for the caller's OAuth-verified GitHub identity. Requires pipelines.operate.

# Replace the organisation's CI cluster pool
Source: https://docs.ankra.ai/api-reference/pipelines/replace-the-organisations-ci-cluster-pool

https://platform.ankra.app/openapi.json put /api/v1/org/ci-settings/pool
Makes the listed members exactly the given list, in one transaction. Every member must be a live cluster of this organisation whose agent advertises pipeline steps, and in no other organisation's pool. Runs already pinned to an unlisted member finish there. Organisation admins only. A browser session twin is mounted at the same path without the /api/v1 prefix (cookie authentication; writes also need the X-Ankra-CSRF header).

# Review a pipeline definition's authority before approval
Source: https://docs.ankra.ai/api-reference/pipelines/review-a-pipeline-definitions-authority-before-approval

https://platform.ankra.app/openapi.json get /api/v1/org/pipelines/definitions/{id}/review
What an approver reads before approving a definition's protected sections: exactly which authority it declares, how that compares with the approved authority runs fall back to, the default-branch run it was read from, and whether the approve route would accept it now. Requires pipelines.read. Read-only. Literal values that can carry a credential (a stage's with: settings, a service's env values, a webhook URL's path and query) are withheld, and the stored pipeline YAML is never returned.

# Set a repository's merge train settings
Source: https://docs.ankra.ai/api-reference/pipelines/set-a-repositorys-merge-train-settings

https://platform.ankra.app/openapi.json put /api/v1/org/pipeline-repositories/{repository_id}/merge-train/settings
Switches the repository's merge train on or off, sets how many pull requests it tests at once, puts auto-admit in off, shadow or on, and sets the criterion it admits by (green, ready_shadow or ready) and the paths that keep green under ready. Switching the train off empties it: every pull request in it leaves, and its car's run stops. GitHub repositories only. Requires pipelines.manage; switching auto-admit on, its criterion to ready, or its protected paths also needs a human member, not a service account token.

# Set a repository's test quarantine settings
Source: https://docs.ankra.ai/api-reference/pipelines/set-a-repositorys-test-quarantine-settings

https://platform.ankra.app/openapi.json put /api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/quarantine/settings
Turns the repository's flaky test quarantine on or off and sets its thresholds. Every field is optional and an omitted one keeps its stored value. The change is audited with the values before and after. Requires pipelines.manage.

# Set an application's merge train settings
Source: https://docs.ankra.ai/api-reference/pipelines/set-an-applications-merge-train-settings

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/merge-train/settings
Switches the repository's merge train on or off, sets how many pull requests it tests at once, puts auto-admit in off, shadow or on, and sets the criterion it admits by (green, ready_shadow or ready) and the paths that keep green under ready. Switching the train off empties it: every pull request in it leaves, and its car's run stops. Addressed by application: the merge train of the pipeline repository the application is connected to. GitHub repositories only. Requires pipelines.manage; switching auto-admit on, its criterion to ready, or its protected paths also needs a human member, not a service account token.

# Set an application's test quarantine settings
Source: https://docs.ankra.ai/api-reference/pipelines/set-an-applications-test-quarantine-settings

https://platform.ankra.app/openapi.json put /api/v1/org/applications/{application_id}/pipeline-tests/quarantine/settings
Turns the repository's flaky test quarantine on or off and sets its thresholds. Every field is optional and an omitted one keeps its stored value. The change is audited with the values before and after. Requires pipelines.manage.

# Get Proxmox VE credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/proxmox-credentials/get-proxmox-ve-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/proxmox/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the Proxmox VE API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get Proxmox VE credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/proxmox-credentials/get-proxmox-ve-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/proxmox/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the Proxmox VE limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/vms
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Add a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/add-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/vms
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Add node group
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/node-groups
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Add node group (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/add-node-group-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/node-groups
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Check Kubernetes upgrade readiness (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/check-kubernetes-upgrade-readiness-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Create a Scaleway Instances cluster
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/create-a-scaleway-instances-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway
Bearer PAT authentication; RBAC permission `clusters.create`. External cloud provider mode is mandatory; kubeadm accepts only Cilium.

# Create a Scaleway Instances cluster (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/create-a-scaleway-instances-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway
Browser session authentication; RBAC permission `clusters.create`. External cloud provider mode is mandatory; kubeadm accepts only Cilium.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/scaleway/{cluster_id}/vms/{vm_id}
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Delete a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/delete-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/scaleway/{cluster_id}/vms/{vm_id}
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Delete node group
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}
Bearer PAT authentication; RBAC permission `clusters.delete`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Delete node group (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/delete-node-group-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}
Browser session authentication; RBAC permission `clusters.delete`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Deprovision a Scaleway Instances cluster
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/deprovision-a-scaleway-instances-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/scaleway/{cluster_id}
Bearer PAT authentication; RBAC permission `clusters.delete`. Ordered teardown preserves explicitly retained storage and reports orphaned provider IDs.

# Deprovision a Scaleway Instances cluster (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/deprovision-a-scaleway-instances-cluster-browser-session

https://platform.ankra.app/openapi.json delete /org/clusters/scaleway/{cluster_id}
Browser session authentication; RBAC permission `clusters.delete`. Ordered teardown preserves explicitly retained storage and reports orphaned provider IDs.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF.

# Diagnose bastion (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/diagnose-bastion-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/bastion/diagnose
Browser session authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `scaleway_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself.

# Get bastion health (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/get-bastion-health-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/bastion/health
Browser session authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself.

# Get disabled K3s components
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/get-disabled-k3s-components

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/k3s-disabled-components
Read the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), on top of the provider shape's own defaults. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states (a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider) answer 409 with a detail message.

# Latest restorable state snapshot of a Scaleway cluster
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/latest-restorable-state-snapshot-of-a-scaleway-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the Scaleway cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List live cluster Scaleway gateway types
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-live-cluster-scaleway-gateway-types

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/gateway-types
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List live cluster Scaleway gateway types (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-live-cluster-scaleway-gateway-types-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/gateway-types
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List live cluster Scaleway instance types
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-live-cluster-scaleway-instance-types

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/instance-types
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List live cluster Scaleway instance types (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-live-cluster-scaleway-instance-types-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/instance-types
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List node groups
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/node-groups
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# List node groups (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-node-groups-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/node-groups
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# List nodes
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/nodes
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# List nodes (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-nodes-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/nodes
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# List Scaleway gateway types
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-gateway-types

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/gateway-types
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway gateway types (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-gateway-types-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/gateway-types
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway instance types
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-instance-types

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/instance-types
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway instance types (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-instance-types-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/instance-types
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway locations
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-locations

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/locations
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway locations (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-locations-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/locations
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway networks
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-networks

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/networks
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway networks (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-networks-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/networks
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway pricing
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-pricing

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/pricing
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway pricing (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-pricing-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/pricing
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway regions
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-regions

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/regions
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway regions (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-regions-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/regions
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway zones
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-zones

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/zones
Bearer PAT authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List Scaleway zones (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-scaleway-zones-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/zones
Browser session authentication; RBAC permission `clusters.read`. Catalog prices carry currency/SKU metadata and explicit incomplete-pricing reasons.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/vms
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# List standalone VMs (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/list-standalone-vms-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/vms
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Preflight a Scaleway Instances cluster
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/preflight-a-scaleway-instances-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/preflight
Bearer PAT authentication; RBAC permission `clusters.create`. External cloud provider mode is mandatory; kubeadm accepts only Cilium.

# Preflight a Scaleway Instances cluster (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/preflight-a-scaleway-instances-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/preflight
Browser session authentication; RBAC permission `clusters.create`. External cloud provider mode is mandatory; kubeadm accepts only Cilium.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/control-plane
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read control-plane sizing (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-control-plane-sizing-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/control-plane
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read Kubernetes version
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/k8s-version
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read Kubernetes version (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-kubernetes-version-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/k8s-version
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read node
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/nodes/{node_id}
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read node (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-node-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/nodes/{node_id}
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `scaleway_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Read node-group autoscaling
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-node-group-autoscaling

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}/autoscaling
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read node-group autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-node-group-autoscaling-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}/autoscaling
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/access-info
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read private cluster access (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-private-cluster-access-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/access-info
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/ssh-keys
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-ssh-keys-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/ssh-keys
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read worker count
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/worker-count
Bearer PAT authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Read worker count (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/read-worker-count-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/scaleway/{cluster_id}/worker-count
Browser session authentication; RBAC permission `clusters.read`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/vms/{vm_id}/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize a standalone VM (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-a-standalone-vm-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/vms/{vm_id}/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/control-plane/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize control-plane nodes (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-control-plane-nodes-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/control-plane/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize node group
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize node group (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-node-group-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize the public gateway
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-the-public-gateway

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/bastion/instance-type
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resize the public gateway (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resize-the-public-gateway-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/bastion/instance-type
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Restart node
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/restart-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/nodes/{node_id}/restart
Bearer PAT authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Restart node (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/restart-node-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/nodes/{node_id}/restart
Browser session authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/ssh-keys/resync
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Resync SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/resync-ssh-keys-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/ssh-keys/resync
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Scale node group
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}/scale
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Scale node group (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/scale-node-group-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}/scale
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Scale workers
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/scale-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/scale-workers
Bearer PAT authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Scale workers (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/scale-workers-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/scale-workers
Browser session authentication; RBAC permission `clusters.operate`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Start a stopped cluster
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/start-a-stopped-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/start
Bearer PAT authentication; RBAC permission `clusters.operate`.

# Start a stopped cluster (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/start-a-stopped-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/start
Browser session authentication; RBAC permission `clusters.operate`.

# Stop a cluster
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/stop-a-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/stop
Bearer PAT authentication; RBAC permission `clusters.operate`.

# Stop a cluster (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/stop-a-cluster-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/stop
Browser session authentication; RBAC permission `clusters.operate`.

# The persistent volumes deleting a Scaleway cluster removes
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/the-persistent-volumes-deleting-a-scaleway-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/scaleway/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/scaleway/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none. Answers 404 while the organisation's `scaleway_provider` feature flag is off.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/control-plane
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update control-plane count (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-control-plane-count-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/control-plane
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update disabled K3s components
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-disabled-k3s-components

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/k3s-disabled-components
Replace the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), for example ["traefik"] on a cluster that brings its own ingress. k3s distribution only. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states answer 409 with a detail message: a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider, a list that drops a stored entry (re-enabling a bundled component is not supported yet, so the list only grows), a list that adds coredns (load-bearing for in-cluster DNS), and any change while a node update, version upgrade or node restart is in progress on the cluster.

# Update node-group autoscaling
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-node-group-autoscaling

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}/autoscaling
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update node-group autoscaling (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-node-group-autoscaling-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}/autoscaling
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}/labels
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update node-group labels (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-node-group-labels-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}/labels
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/node-groups/{group_name}/taints
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update node-group taints (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-node-group-taints-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/node-groups/{group_name}/taints
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/scaleway/{cluster_id}/ssh-keys
Bearer PAT authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Update SSH keys (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/update-ssh-keys-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/scaleway/{cluster_id}/ssh-keys
Browser session authentication; RBAC permission `clusters.write`. PAT mutations support `wait=false` where implemented; browser mutations require CSRF.

# Upgrade the Kubernetes version
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/upgrade-the-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/scaleway/{cluster_id}/upgrade-k8s-version
Bearer PAT authentication; RBAC permission `clusters.operate`.

# Upgrade the Kubernetes version (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-clusters/upgrade-the-kubernetes-version-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/scaleway/{cluster_id}/upgrade-k8s-version
Browser session authentication; RBAC permission `clusters.operate`.

# Create a Scaleway credential
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/create-a-scaleway-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/scaleway
Bearer PAT authentication; RBAC permission `credentials.write`. The secret is stored in Vault and connection-tested without echoing key material.

# Create a Scaleway credential (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/create-a-scaleway-credential-browser-session

https://platform.ankra.app/openapi.json post /org/credentials/scaleway
Browser session authentication; RBAC permission `credentials.write`. The secret is stored in Vault and connection-tested without echoing key material.

# Create an SSH key credential
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/create-an-ssh-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/scaleway/ssh-key
Creates an SSH key credential from `name` and either `ssh_public_key` or `generate=true`; a generated RSA-4096 key pair's private key is returned once, in this response. A public key the organisation already stores under another credential is refused with 400. Requires `credentials.write`; answers 201.

# Get Scaleway credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/get-scaleway-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/scaleway/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the Scaleway API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail. Answers 404 while the organisation's `scaleway_provider` feature flag is off.

# Get Scaleway credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/get-scaleway-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/scaleway/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the Scaleway limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail. Answers 404 while the organisation's `scaleway_provider` feature flag is off.

# List Scaleway credentials
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/list-scaleway-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/scaleway
Bearer PAT authentication; RBAC permission `credentials.read`. Returns credential metadata only; access_key and secret_key are never returned.

# List Scaleway credentials (browser session)
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/list-scaleway-credentials-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/scaleway
Browser session authentication; RBAC permission `credentials.read`. Returns credential metadata only; access_key and secret_key are never returned.

# List SSH key credentials
Source: https://docs.ankra.ai/api-reference/scaleway-credentials/list-ssh-key-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/scaleway/ssh-keys
Lists the organisation's SSH key credentials. The list is the same under every cloud provider. Each item carries the stored public key with the fingerprint (as `ssh-keygen -l` prints it), key type and comment derived from it; a stored value that is not a readable key keeps its row, with a null `fingerprint` and `fingerprint_error` saying why.

# Create a secret slot
Source: https://docs.ankra.ai/api-reference/secret-slots/create-a-secret-slot

https://platform.ankra.app/openapi.json post /api/v1/org/secret-slots
Stores a secret in Vault and returns its slot, whose sentinel ${SECRET_SLOT:<slot_id>} can stand in for the value in manifests, addon values and MCP server env. Send either value or generate: generate has Ankra create a random value that nobody sees. The value is never returned.

# Delete a secret slot
Source: https://docs.ankra.ai/api-reference/secret-slots/delete-a-secret-slot

https://platform.ankra.app/openapi.json delete /api/v1/org/secret-slots/{slot_id}
Deletes the slot and its stored value. A slot that live resources still reference is refused, and the refusal names the first of them.

# List secret slots
Source: https://docs.ankra.ai/api-reference/secret-slots/list-secret-slots

https://platform.ankra.app/openapi.json get /api/v1/org/secret-slots
Lists the organisation's secret slots, newest first, with each slot's sentinel and the live resources that reference it. Values are stored in Vault and are never returned.

# Replace a secret slot value
Source: https://docs.ankra.ai/api-reference/secret-slots/replace-a-secret-slot-value

https://platform.ankra.app/openapi.json put /api/v1/org/secret-slots/{slot_id}
Replaces the slot's value in place. The slot keeps its id, so every ${SECRET_SLOT:<slot_id>} reference stays valid; its label, hint and expiry do not change. Send exactly one of value or generate. The value is never returned.

# Cancel a security remediation run
Source: https://docs.ankra.ai/api-reference/security/cancel-a-security-remediation-run

https://platform.ankra.app/openapi.json post /api/v1/org/security/remediations/{run_id}/cancel
Stops a live run; the pull request and any running pipeline are left for their reviewers. A finished run is answered unchanged.

# Cancel a security remediation run (browser session)
Source: https://docs.ankra.ai/api-reference/security/cancel-a-security-remediation-run-browser-session

https://platform.ankra.app/openapi.json post /org/security/remediations/{run_id}/cancel
Stops a live run; the pull request and any running pipeline are left for their reviewers. A finished run is answered unchanged.

# Create a security evidence destination
Source: https://docs.ankra.ai/api-reference/security/create-a-security-evidence-destination

https://platform.ankra.app/openapi.json post /api/v1/org/security/evidence/destinations
Stores the credential in Vault, then records the destination (a Vanta document, a Wazuh relay or a signed webhook). URLs must be https; addresses are re-checked at dial time.

# Create a security evidence destination (browser session)
Source: https://docs.ankra.ai/api-reference/security/create-a-security-evidence-destination-browser-session

https://platform.ankra.app/openapi.json post /org/security/evidence/destinations
Stores the credential in Vault, then records the destination (a Vanta document, a Wazuh relay or a signed webhook). URLs must be https; addresses are re-checked at dial time.

# Create code finding disposition
Source: https://docs.ankra.ai/api-reference/security/create-code-finding-disposition

https://platform.ankra.app/openapi.json post /api/v1/org/security/code-dispositions
Records a reviewed Semgrep or Checkov finding of a pipeline repository as a `false_positive` or an `accepted_risk` (which needs `expires_at` within a year), with a required `reason`; the image gate then stops blocking on that rule in that file and names the disposition on every run it lets through. A CRITICAL finding is refused (400), as is a second active disposition of the same finding (409). Requires `security.manage`.

# Create code finding disposition (browser session)
Source: https://docs.ankra.ai/api-reference/security/create-code-finding-disposition-browser-session

https://platform.ankra.app/openapi.json post /org/security/code-dispositions
Records a reviewed Semgrep or Checkov finding of a pipeline repository as a `false_positive` or an `accepted_risk` (which needs `expires_at` within a year), with a required `reason`; the image gate then stops blocking on that rule in that file and names the disposition on every run it lets through. A CRITICAL finding is refused (400), as is a second active disposition of the same finding (409). Requires `security.manage`.

# Create vulnerability disposition policy
Source: https://docs.ankra.ai/api-reference/security/create-vulnerability-disposition-policy

https://platform.ankra.app/openapi.json post /api/v1/org/security/vulnerability-dispositions
Creates a disposition policy from one finding occurrence (`occurrence_id`) that marks matching vulnerabilities as `acknowledged` or `accepted_risk`, with a required `reason`. Acknowledging needs `security.triage` and accepting risk needs `security.manage` plus an `expires_at` review deadline within one year; returns 409 for a duplicate policy or one that matches nothing unless `allow_unmatched` is set.

# Create vulnerability disposition policy (browser session)
Source: https://docs.ankra.ai/api-reference/security/create-vulnerability-disposition-policy-browser-session

https://platform.ankra.app/openapi.json post /org/security/vulnerability-dispositions
Creates a disposition policy from one finding occurrence (`occurrence_id`) that marks matching vulnerabilities as `acknowledged` or `accepted_risk`, with a required `reason`. Acknowledging needs `security.triage` and accepting risk needs `security.manage` plus an `expires_at` review deadline within one year; returns 409 for a duplicate policy or one that matches nothing unless `allow_unmatched` is set.

# Daily security posture trend of one cluster
Source: https://docs.ankra.ai/api-reference/security/daily-security-posture-trend-of-one-cluster

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/trivy/history
Returns the cluster's daily vulnerability posture snapshots, oldest first: finding counts by severity, fixable critical and high counts, workloads, namespaces and risk score. `days` sets the window (default 90, at most 365); a cluster with no snapshots yet returns an empty list.

# Daily security posture trend of one cluster (browser session)
Source: https://docs.ankra.ai/api-reference/security/daily-security-posture-trend-of-one-cluster-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/trivy/history
Returns the cluster's daily vulnerability posture snapshots, oldest first: finding counts by severity, fixable critical and high counts, workloads, namespaces and risk score. `days` sets the window (default 90, at most 365); a cluster with no snapshots yet returns an empty list.

# Download an image's bill of materials
Source: https://docs.ankra.ai/api-reference/security/download-an-images-bill-of-materials

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom/image/export
Download one image's bill of materials, rebuilt from the stored components: a CycloneDX 1.5 JSON document by default, or a flat CSV. Every component of the image is included, unpaged.

# Download an image's bill of materials (browser session)
Source: https://docs.ankra.ai/api-reference/security/download-an-images-bill-of-materials-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom/image/export
Download one image's bill of materials, rebuilt from the stored components: a CycloneDX 1.5 JSON document by default, or a flat CSV. Every component of the image is included, unpaged.

# Email the cluster's security report now
Source: https://docs.ankra.ai/api-reference/security/email-the-clusters-security-report-now

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/security/report-schedule/send-now
Queues the cluster's security report for immediate delivery to its configured recipients; the email goes out within about a minute. Requires `clusters.write`; returns 404 when the cluster has no report schedule.

# Email the cluster's security report now (browser session)
Source: https://docs.ankra.ai/api-reference/security/email-the-clusters-security-report-now-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/imported/{cluster_id}/security/report-schedule/send-now
Queues the cluster's security report for immediate delivery to its configured recipients; the email goes out within about a minute. Requires `clusters.write`; returns 404 when the cluster has no report schedule.

# Enable or disable one compliance framework
Source: https://docs.ankra.ai/api-reference/security/enable-or-disable-one-compliance-framework

https://platform.ankra.app/openapi.json patch /api/v1/org/security/compliance/frameworks/{framework_key}
Enables or disables one compliance framework for the organisation (`enabled`); enabling it records its first snapshot immediately. Requires `security.manage`.

# Enable or disable one compliance framework (browser session)
Source: https://docs.ankra.ai/api-reference/security/enable-or-disable-one-compliance-framework-browser-session

https://platform.ankra.app/openapi.json patch /org/security/compliance/frameworks/{framework_key}
Enables or disables one compliance framework for the organisation (`enabled`); enabling it records its first snapshot immediately. Requires `security.manage`.

# Enable the curated security baseline stack
Source: https://docs.ankra.ai/api-reference/security/enable-the-curated-security-baseline-stack

https://platform.ankra.app/openapi.json post /api/v1/org/security/clusters/{cluster_id}/enable-baseline
Installs the Ankra security baseline stack (trivy-operator and the pod-security manifests) on a cluster through GitOps and returns the stack write result with its commit. Re-running it adds any missing baseline members; returns 409 when the complete baseline is already installed or trivy-operator runs outside it, and requires `security.triage` or `security.manage`.

# Enable the curated security baseline stack (browser session)
Source: https://docs.ankra.ai/api-reference/security/enable-the-curated-security-baseline-stack-browser-session

https://platform.ankra.app/openapi.json post /org/security/clusters/{cluster_id}/enable-baseline
Installs the Ankra security baseline stack (trivy-operator and the pod-security manifests) on a cluster through GitOps and returns the stack write result with its commit. Re-running it adds any missing baseline members; returns 409 when the complete baseline is already installed or trivy-operator runs outside it, and requires `security.triage` or `security.manage`.

# Export the organisation compliance evidence report
Source: https://docs.ankra.ai/api-reference/security/export-the-organisation-compliance-evidence-report

https://platform.ankra.app/openapi.json get /api/v1/org/security/compliance-report
Downloads the organisation's compliance evidence report (posture, findings, dispositions, audit summary, attestation and compliance) as a JSON or sectioned CSV attachment, chosen with `format`. Requires both `security.read` and `audit.read`; the audit window can be bounded with `start_date` and `end_date`.

# Export the organisation compliance evidence report (browser session)
Source: https://docs.ankra.ai/api-reference/security/export-the-organisation-compliance-evidence-report-browser-session

https://platform.ankra.app/openapi.json get /org/security/compliance-report
Downloads the organisation's compliance evidence report (posture, findings, dispositions, audit summary, attestation and compliance) as a JSON or sectioned CSV attachment, chosen with `format`. Requires both `security.read` and `audit.read`; the audit window can be bounded with `start_date` and `end_date`.

# Get cluster access posture
Source: https://docs.ankra.ai/api-reference/security/get-cluster-access-posture

https://platform.ankra.app/openapi.json get /api/v1/org/security/clusters/{cluster_id}/access-posture
Evaluates one cluster's Kubernetes access posture from its kube gateway grants: a standing cluster-wide cluster-admin or admin grant, a grant over the organisation's access policy, the creator's grant left unchanged for 90 days on a GitOps cluster, and a grant identity the cluster's apiserver verified can impersonate users, groups or service accounts (any of them or only named ones). Each finding names the grant and the commands that fix it; checks that could not be evaluated are listed under unknowns. Requires `security.read`; grantee emails appear only when the caller also holds `kube_access.manage`, otherwise a grantee is its grant_id and ankra_user_id.

# Get cluster access posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-cluster-access-posture-browser-session

https://platform.ankra.app/openapi.json get /org/security/clusters/{cluster_id}/access-posture
Evaluates one cluster's Kubernetes access posture from its kube gateway grants: a standing cluster-wide cluster-admin or admin grant, a grant over the organisation's access policy, the creator's grant left unchanged for 90 days on a GitOps cluster, and a grant identity the cluster's apiserver verified can impersonate users, groups or service accounts (any of them or only named ones). Each finding names the grant and the commands that fix it; checks that could not be evaluated are listed under unknowns. Requires `security.read`; grantee emails appear only when the caller also holds `kube_access.manage`, otherwise a grantee is its grant_id and ankra_user_id.

# Get imported cluster add-on security posture
Source: https://docs.ankra.ai/api-reference/security/get-imported-cluster-add-on-security-posture

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/addons/{addon_name}/security
Returns the vulnerability posture of one add-on installed on an imported cluster. Requires `security.read`.

# Get imported cluster add-on security posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-imported-cluster-add-on-security-posture-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/addons/{addon_name}/security
Returns the vulnerability posture of one add-on installed on an imported cluster. Requires `security.read`.

# Get imported cluster pod security posture
Source: https://docs.ankra.ai/api-reference/security/get-imported-cluster-pod-security-posture

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/pods/{namespace}/{pod_name}
Returns the security summary of one running pod on an imported cluster: every container with its CVE posture and bill of materials. Requires `security.read`.

# Get imported cluster pod security posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-imported-cluster-pod-security-posture-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/pods/{namespace}/{pod_name}
Returns the security summary of one running pod on an imported cluster: every container with its CVE posture and bill of materials. Requires `security.read`.

# Get imported cluster stack security posture
Source: https://docs.ankra.ai/api-reference/security/get-imported-cluster-stack-security-posture

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/security
Returns the security summary of one stack on an imported cluster: its CVE posture, the CISA known-exploited findings among them, the bill-of-materials inventory of its running containers, and the same figures per stack member. Requires `security.read`.

# Get imported cluster stack security posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-imported-cluster-stack-security-posture-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security
Returns the security summary of one stack on an imported cluster: its CVE posture, the CISA known-exploited findings among them, the bill-of-materials inventory of its running containers, and the same figures per stack member. Requires `security.read`.

# Get one compliance framework report
Source: https://docs.ankra.ai/api-reference/security/get-one-compliance-framework-report

https://platform.ankra.app/openapi.json get /api/v1/org/security/compliance/frameworks/{framework_key}/report
Returns the scored, control-by-control report for one compliance framework with its month-over-month trend: live by default, or for a recorded month with `month=YYYY-MM`. Requires `security.read`; returns 409 when the framework is disabled and 404 when the month was not recorded.

# Get one compliance framework report (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-one-compliance-framework-report-browser-session

https://platform.ankra.app/openapi.json get /org/security/compliance/frameworks/{framework_key}/report
Returns the scored, control-by-control report for one compliance framework with its month-over-month trend: live by default, or for a recorded month with `month=YYYY-MM`. Requires `security.read`; returns 409 when the framework is disabled and 404 when the month was not recorded.

# Get one imported cluster's aggregated policy violations
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-aggregated-policy-violations

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/policy-violations
Returns the cluster's aggregated Kyverno policy report, read live from the cluster: pass, warn and fail counts per policy, the top offending namespaces and report totals, plus the baseline's current audit or enforce mode. Requires `security.read`; answers 503 when the cluster or its agent cannot be reached.

# Get one imported cluster's aggregated policy violations (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-aggregated-policy-violations-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/policy-violations
Returns the cluster's aggregated Kyverno policy report, read live from the cluster: pass, warn and fail counts per policy, the top offending namespaces and report totals, plus the baseline's current audit or enforce mode. Requires `security.read`; answers 503 when the cluster or its agent cannot be reached.

# Get one imported cluster's compliance view
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-compliance-view

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/compliance
Returns one cluster's compliance benchmark summaries with their failed checks and the aggregated configuration-audit counts, read live from the cluster. Requires `security.read`; answers 503 with `Retry-After` when the cluster or its agent cannot be reached.

# Get one imported cluster's compliance view (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-compliance-view-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/compliance
Returns one cluster's compliance benchmark summaries with their failed checks and the aggregated configuration-audit counts, read live from the cluster. Requires `security.read`; answers 503 with `Retry-After` when the cluster or its agent cannot be reached.

# Get one imported cluster's NetworkPolicy over-privilege score
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-networkpolicy-over-privilege-score

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/network-policy-overprivilege
Scores how over-privileged the cluster's NetworkPolicies are, with ingress and egress scored separately and a remediation row per finding, computed live from the cluster's policy and workload objects. Requires `security.read`; answers 503 when the cluster or its agent cannot be reached.

# Get one imported cluster's NetworkPolicy over-privilege score (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-networkpolicy-over-privilege-score-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/network-policy-overprivilege
Scores how over-privileged the cluster's NetworkPolicies are, with ingress and egress scored separately and a remediation row per finding, computed live from the cluster's policy and workload objects. Requires `security.read`; answers 503 when the cluster or its agent cannot be reached.

# Get one imported cluster's stored security policy mode
Source: https://docs.ankra.ai/api-reference/security/get-one-imported-clusters-stored-security-policy-mode

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/policy-mode
Returns the security-baseline policy mode the platform has stored for the cluster (`off`, `audit` or `enforce`), read from the database without contacting the cluster, so it answers while the cluster is offline. `off` means the policy engine was switched off and is not installed; `null` means no security baseline is installed. Requires `security.read`.

# Get organization security finding detail
Source: https://docs.ankra.ai/api-reference/security/get-organization-security-finding-detail

https://platform.ankra.app/openapi.json get /api/v1/org/security/findings/{finding_id}
Returns one CVE finding with its occurrences, a per-cluster breakdown, the disposition policies that match it, the available fix routes and any base-image bump pull requests already opened for it. Requires `security.read`; returns 404 when the finding does not exist.

# Get organization security finding detail (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-organization-security-finding-detail-browser-session

https://platform.ankra.app/openapi.json get /org/security/findings/{finding_id}
Returns one CVE finding with its occurrences, a per-cluster breakdown, the disposition policies that match it, the available fix routes and any base-image bump pull requests already opened for it. Requires `security.read`; returns 404 when the finding does not exist.

# Get organization security overview
Source: https://docs.ankra.ai/api-reference/security/get-organization-security-overview

https://platform.ankra.app/openapi.json get /api/v1/org/security/overview
Returns the organisation's fleet vulnerability overview: totals and severity counts, fixable severe and CISA known-exploited counts, scanner coverage, the top remediation candidates and the observed trend. Optionally narrowed with `cluster_id` or `addon_slug`; requires `security.read`.

# Get organization security overview (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-organization-security-overview-browser-session

https://platform.ankra.app/openapi.json get /org/security/overview
Returns the organisation's fleet vulnerability overview: totals and severity counts, fixable severe and CISA known-exploited counts, scanner coverage, the top remediation candidates and the observed trend. Optionally narrowed with `cluster_id` or `addon_slug`; requires `security.read`.

# Get the organisation compliance rollup
Source: https://docs.ankra.ai/api-reference/security/get-the-organisation-compliance-rollup

https://platform.ankra.app/openapi.json get /api/v1/org/security/compliance
Returns the organisation's compliance rollup: the trivy-operator benchmark pass and fail totals for each cluster. Clusters that cannot be reached appear as not available rather than failing the request; requires `security.read`.

# Get the organisation compliance rollup (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-the-organisation-compliance-rollup-browser-session

https://platform.ankra.app/openapi.json get /org/security/compliance
Returns the organisation's compliance rollup: the trivy-operator benchmark pass and fail totals for each cluster. Clusters that cannot be reached appear as not available rather than failing the request; requires `security.read`.

# Get the platform advisory page for one CVE
Source: https://docs.ankra.ai/api-reference/security/get-the-platform-advisory-page-for-one-cve

https://platform.ankra.app/openapi.json get /api/v1/org/security/advisories/{cve_id}
The parsed NVD/OSV advisory record for a CVE in one of three states (fetched, pending, missing - an error state carries the reason), the platform's CISA KEV / EPSS intelligence for it, and the organisation's own exposure. A CVE the platform has not read yet is reported pending and queued for the vulnerability_advisories loop, so callers poll until it is fetched or missing.

# Get the platform advisory page for one CVE (browser session)
Source: https://docs.ankra.ai/api-reference/security/get-the-platform-advisory-page-for-one-cve-browser-session

https://platform.ankra.app/openapi.json get /org/security/advisories/{cve_id}
The parsed NVD/OSV advisory record for a CVE in one of three states (fetched, pending, missing - an error state carries the reason), the platform's CISA KEV / EPSS intelligence for it, and the organisation's own exposure. A CVE the platform has not read yet is reported pending and queued for the vulnerability_advisories loop, so callers poll until it is fetched or missing.

# Images with a bill of materials
Source: https://docs.ankra.ai/api-reference/security/images-with-a-bill-of-materials

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom/images
Every image with a stored bill of materials: OS, component count, the workloads, clusters and namespaces running it, and the actionable findings the scanner attributes to it.

# Images with a bill of materials (browser session)
Source: https://docs.ankra.ai/api-reference/security/images-with-a-bill-of-materials-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom/images
Every image with a stored bill of materials: OS, component count, the workloads, clusters and namespaces running it, and the actionable findings the scanner attributes to it.

# List cluster security posture
Source: https://docs.ankra.ai/api-reference/security/list-cluster-security-posture

https://platform.ankra.app/openapi.json get /api/v1/org/security/clusters
Lists every cluster's current security posture, paginated (`page_size` default 50): scanner and posture status, latest report time, and finding counts by disposition and severity. Filter by `search` or `status` and order with `sort` and `order`; requires `security.read`.

# List cluster security posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-cluster-security-posture-browser-session

https://platform.ankra.app/openapi.json get /org/security/clusters
Lists every cluster's current security posture, paginated (`page_size` default 50): scanner and posture status, latest report time, and finding counts by disposition and severity. Filter by `search` or `status` and order with `sort` and `order`; requires `security.read`.

# List code finding dispositions
Source: https://docs.ankra.ai/api-reference/security/list-code-finding-dispositions

https://platform.ankra.app/openapi.json get /api/v1/org/security/code-dispositions
Lists the organisation's repository code finding dispositions (Semgrep and Checkov false positives and accepted risks the Ankra Pipelines image gate honours), newest first, optionally for one application or pipeline repository. Requires `security.read`.

# List code finding dispositions (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-code-finding-dispositions-browser-session

https://platform.ankra.app/openapi.json get /org/security/code-dispositions
Lists the organisation's repository code finding dispositions (Semgrep and Checkov false positives and accepted risks the Ankra Pipelines image gate honours), newest first, optionally for one application or pipeline repository. Requires `security.read`.

# List organization security finding occurrences
Source: https://docs.ankra.ai/api-reference/security/list-organization-security-finding-occurrences

https://platform.ankra.app/openapi.json get /api/v1/org/security/findings/{finding_id}/occurrences
Pages one finding's occurrences by the status predicates its row counts with, so every count on the finding row can be expanded into the rows behind it. Resolved occurrences list newest resolution first; every other status lists in the finding detail's workload order.

# List organization security finding occurrences (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-organization-security-finding-occurrences-browser-session

https://platform.ankra.app/openapi.json get /org/security/findings/{finding_id}/occurrences
Pages one finding's occurrences by the status predicates its row counts with, so every count on the finding row can be expanded into the rows behind it. Resolved occurrences list newest resolution first; every other status lists in the finding detail's workload order.

# List organization security findings
Source: https://docs.ankra.ai/api-reference/security/list-organization-security-findings

https://platform.ankra.app/openapi.json get /api/v1/org/security/findings
Lists the organisation's CVE findings, paginated (`page_size` default 50), with each finding's severity, score, affected clusters and workloads, fixable and disposition counts and exploit intelligence. Filter by `search`, `severity`, `status`, `fixable`, `known_exploited`, `cluster_id`, `addon_slug` or `namespace`, and order with `sort` and `order`; requires `security.read`.

# List organization security findings (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-organization-security-findings-browser-session

https://platform.ankra.app/openapi.json get /org/security/findings
Lists the organisation's CVE findings, paginated (`page_size` default 50), with each finding's severity, score, affected clusters and workloads, fixable and disposition counts and exploit intelligence. Filter by `search`, `severity`, `status`, `fixable`, `known_exploited`, `cluster_id`, `addon_slug` or `namespace`, and order with `sort` and `order`; requires `security.read`.

# List organization security workloads
Source: https://docs.ankra.ai/api-reference/security/list-organization-security-workloads

https://platform.ankra.app/openapi.json get /api/v1/org/security/workloads
Lists the organisation's scanned workloads, paginated (`page_size` default 50), each with its image, add-on attribution, severity counts by disposition, known-exploited count, priority and risk score. Takes the same filters as the findings list; requires `security.read`.

# List organization security workloads (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-organization-security-workloads-browser-session

https://platform.ankra.app/openapi.json get /org/security/workloads
Lists the organisation's scanned workloads, paginated (`page_size` default 50), each with its image, add-on attribution, severity counts by disposition, known-exploited count, priority and risk score. Takes the same filters as the findings list; requires `security.read`.

# List security evidence deliveries
Source: https://docs.ankra.ai/api-reference/security/list-security-evidence-deliveries

https://platform.ankra.app/openapi.json get /api/v1/org/security/evidence/deliveries
The organisation's deliveries newest first, optionally for one destination (at most 100).

# List security evidence deliveries (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-security-evidence-deliveries-browser-session

https://platform.ankra.app/openapi.json get /org/security/evidence/deliveries
The organisation's deliveries newest first, optionally for one destination (at most 100).

# List security evidence destinations
Source: https://docs.ankra.ai/api-reference/security/list-security-evidence-destinations

https://platform.ankra.app/openapi.json get /api/v1/org/security/evidence/destinations
The organisation's evidence destinations; credentials are never returned.

# List security evidence destinations (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-security-evidence-destinations-browser-session

https://platform.ankra.app/openapi.json get /org/security/evidence/destinations
The organisation's evidence destinations; credentials are never returned.

# List security remediation runs
Source: https://docs.ankra.ai/api-reference/security/list-security-remediation-runs

https://platform.ankra.app/openapi.json get /api/v1/org/security/remediations
The organisation's remediation runs, newest first (at most 100), optionally for one finding or one application. Without application_id only runs of one finding are listed, each naming its finding_id; with application_id the application's batched runs (finding_id null) are listed too, and finding_id then also matches a batched run that fixes it.

# List security remediation runs (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-security-remediation-runs-browser-session

https://platform.ankra.app/openapi.json get /org/security/remediations
The organisation's remediation runs, newest first (at most 100), optionally for one finding or one application. Without application_id only runs of one finding are listed, each naming its finding_id; with application_id the application's batched runs (finding_id null) are listed too, and finding_id then also matches a batched run that fixes it.

# List the bill-of-materials components across one stack's workloads
Source: https://docs.ankra.ai/api-reference/security/list-the-bill-of-materials-components-across-one-stacks-workloads

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/sbom
Lists the software components in the images one stack's workloads run, paginated, with per-component finding counts; filter with `search` or `vulnerable`. Requires `security.read`.

# List the bill-of-materials components across one stack's workloads (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-bill-of-materials-components-across-one-stacks-workloads-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/sbom
Lists the software components in the images one stack's workloads run, paginated, with per-component finding counts; filter with `search` or `vulnerable`. Requires `security.read`.

# List the compliance frameworks
Source: https://docs.ankra.ai/api-reference/security/list-the-compliance-frameworks

https://platform.ankra.app/openapi.json get /api/v1/org/security/compliance/frameworks
Lists the compliance frameworks (GDPR, ISO 27001, SOC 2, NIST CSF) with whether each is enabled for the organisation and a live score for every enabled one. Requires `security.read`.

# List the compliance frameworks (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-compliance-frameworks-browser-session

https://platform.ankra.app/openapi.json get /org/security/compliance/frameworks
Lists the compliance frameworks (GDPR, ISO 27001, SOC 2, NIST CSF) with whether each is enabled for the organisation and a live score for every enabled one. Requires `security.read`.

# List the CVEs across one stack's workloads
Source: https://docs.ankra.ai/api-reference/security/list-the-cves-across-one-stacks-workloads

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/findings
Lists the CVEs found in one stack's workloads, paginated, with the same filters, sorting and disposition counts as the organisation findings list; the facets are the stack's own. Requires `security.read`.

# List the CVEs across one stack's workloads (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-cves-across-one-stacks-workloads-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/findings
Lists the CVEs found in one stack's workloads, paginated, with the same filters, sorting and disposition counts as the organisation findings list; the facets are the stack's own. Requires `security.read`.

# List the resources failing one compliance control
Source: https://docs.ankra.ai/api-reference/security/list-the-resources-failing-one-compliance-control

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/compliance/checks/{check_id}/resources
Lists the Kubernetes objects failing one compliance control, each annotated with the add-on or manifest that deploys it and that resource's stack. Pass `source` (`benchmark` or `config_audit`) and, for benchmark checks, `benchmark_id`; requires `security.read`.

# List the resources failing one compliance control (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-resources-failing-one-compliance-control-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/compliance/checks/{check_id}/resources
Lists the Kubernetes objects failing one compliance control, each annotated with the add-on or manifest that deploys it and that resource's stack. Pass `source` (`benchmark` or `config_audit`) and, for benchmark checks, `benchmark_id`; requires `security.read`.

# List the running pods of a stack with their containers' security posture
Source: https://docs.ankra.ai/api-reference/security/list-the-running-pods-of-a-stack-with-their-containers-security-posture

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/pods
Lists the running pods of one stack, riskiest first, with each container's CVE posture and bill of materials. Paginated, filterable by `search` and by stack member (`member_resource_id`); requires `security.read`.

# List the running pods of a stack with their containers' security posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-running-pods-of-a-stack-with-their-containers-security-posture-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/pods
Lists the running pods of one stack, riskiest first, with each container's CVE posture and bill of materials. Paginated, filterable by `search` and by stack member (`member_resource_id`); requires `security.read`.

# List the security posture of every stack of an imported cluster
Source: https://docs.ankra.ai/api-reference/security/list-the-security-posture-of-every-stack-of-an-imported-cluster

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/stacks
Every live stack of the cluster with its security posture - what the read could attribute, the CVE posture over the workloads the stack owns, the running containers with and without a bill of materials - plus the outside bucket: everything on the cluster no stack owns, so the rows add up to the cluster. Each stack is attributed exactly as its own security read attributes it.

# List the security posture of every stack of an imported cluster (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-security-posture-of-every-stack-of-an-imported-cluster-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/stacks
Every live stack of the cluster with its security posture - what the read could attribute, the CVE posture over the workloads the stack owns, the running containers with and without a bill of materials - plus the outside bucket: everything on the cluster no stack owns, so the rows add up to the cluster. Each stack is attributed exactly as its own security read attributes it.

# List the vulnerabilities on one image
Source: https://docs.ankra.ai/api-reference/security/list-the-vulnerabilities-on-one-image

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom/image/findings
List the vulnerabilities (CVEs) named on one image: one row per CVE and installed package version, aggregated across every workload container running the image, with the fixed version when one exists, the CISA KEV / EPSS intelligence, how the occurrences are dispositioned and where it runs. The summary totals the image's active occurrences before search and severity narrow the rows. Answers for an image with or without a bill of materials (image.sbom_status); an image the platform has never seen is not found.

# List the vulnerabilities on one image (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-vulnerabilities-on-one-image-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom/image/findings
List the vulnerabilities (CVEs) named on one image: one row per CVE and installed package version, aggregated across every workload container running the image, with the fixed version when one exists, the CISA KEV / EPSS intelligence, how the occurrences are dispositioned and where it runs. The summary totals the image's active occurrences before search and severity narrow the rows. Answers for an image with or without a bill of materials (image.sbom_status); an image the platform has never seen is not found.

# List the workloads of an imported cluster stack with their security posture
Source: https://docs.ankra.ai/api-reference/security/list-the-workloads-of-an-imported-cluster-stack-with-their-security-posture

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/workloads
The workloads each member of the stack resolved to directly, with the pods each runs, the CVE occurrences the scanner attributed to it and its running containers with and without a bill of materials. A workload no report names has scanned=false; its counts are then absent, not clean.

# List the workloads of an imported cluster stack with their security posture (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-the-workloads-of-an-imported-cluster-stack-with-their-security-posture-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/workloads
The workloads each member of the stack resolved to directly, with the pods each runs, the CVE occurrences the scanner attributed to it and its running containers with and without a bill of materials. A workload no report names has scanned=false; its counts are then absent, not clean.

# List vulnerability disposition policies
Source: https://docs.ankra.ai/api-reference/security/list-vulnerability-disposition-policies

https://platform.ankra.app/openapi.json get /api/v1/org/security/vulnerability-dispositions
Lists the organisation's vulnerability disposition policies, paginated (`page_size` default 50), each with its selector, disposition, reason, expiry, status and match counts. Filter by `search`, `status` or `disposition` and order with `sort` and `order`; requires `security.read`.

# List vulnerability disposition policies (browser session)
Source: https://docs.ankra.ai/api-reference/security/list-vulnerability-disposition-policies-browser-session

https://platform.ankra.app/openapi.json get /org/security/vulnerability-dispositions
Lists the organisation's vulnerability disposition policies, paginated (`page_size` default 50), each with its selector, disposition, reason, expiry, status and match counts. Filter by `search`, `status` or `disposition` and order with `sort` and `order`; requires `security.read`.

# One image's bill of materials
Source: https://docs.ankra.ai/api-reference/security/one-images-bill-of-materials

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom/image
One image by identity (its digest, or repository:tag when the scanner knew no digest): the image, a page of its components with the findings that name them, and every workload container currently running it.

# One image's bill of materials (browser session)
Source: https://docs.ankra.ai/api-reference/security/one-images-bill-of-materials-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom/image
One image by identity (its digest, or repository:tag when the scanner knew no digest): the image, a page of its components with the findings that name them, and every workload container currently running it.

# Open base-image bump pull requests for a security finding
Source: https://docs.ankra.ai/api-reference/security/open-base-image-bump-pull-requests-for-a-security-finding

https://platform.ankra.app/openapi.json post /api/v1/org/security/findings/{finding_id}/rebuild
Opens one pull request per affected application repository bumping the Dockerfile base image to the advisory's fixed version, through the application's own GitHub credential, and records each on the finding (served as image_rebuild_pull_requests on the finding detail). Every write goes to a new branch (ankra/security/<finding short id>/<base image>) plus a pull request, never to the default branch; only base-image FROM lines change; an open Ankra pull request for the same finding and repository is reused, never duplicated. Repositories the plan refuses are answered as refusals with their reason; when no repository could be acted on the call is refused with 409 naming the reasons, as is a finding with no application image occurrence carrying a fixed version.

# Open base-image bump pull requests for a security finding (browser session)
Source: https://docs.ankra.ai/api-reference/security/open-base-image-bump-pull-requests-for-a-security-finding-browser-session

https://platform.ankra.app/openapi.json post /org/security/findings/{finding_id}/rebuild
Opens one pull request per affected application repository bumping the Dockerfile base image to the advisory's fixed version, through the application's own GitHub credential, and records each on the finding (served as image_rebuild_pull_requests on the finding detail). Every write goes to a new branch (ankra/security/<finding short id>/<base image>) plus a pull request, never to the default branch; only base-image FROM lines change; an open Ankra pull request for the same finding and repository is reused, never duplicated. Repositories the plan refuses are answered as refusals with their reason; when no repository could be acted on the call is refused with 409 naming the reasons, as is a finding with no application image occurrence carrying a fixed version.

# Plan base-image bump pull requests for a security finding
Source: https://docs.ankra.ai/api-reference/security/plan-base-image-bump-pull-requests-for-a-security-finding

https://platform.ankra.app/openapi.json get /api/v1/org/security/findings/{finding_id}/rebuild-plan
Plans the base-image bump pull requests for a finding whose occurrences are application container images (the image_rebuild fix route): per affected application repository, the Dockerfile FROM lines that would move from the installed version to the advisory's fixed version, the branch and credential the pull request would use, and the open Ankra pull request already there, if any; per image the lane cannot act on, the refusal and its reason (no application builds it, the application has no repository or GitHub credential, the credential cannot read the repository, no Dockerfile, no FROM line pins the installed version). A read: nothing is opened.

# Plan base-image bump pull requests for a security finding (browser session)
Source: https://docs.ankra.ai/api-reference/security/plan-base-image-bump-pull-requests-for-a-security-finding-browser-session

https://platform.ankra.app/openapi.json get /org/security/findings/{finding_id}/rebuild-plan
Plans the base-image bump pull requests for a finding whose occurrences are application container images (the image_rebuild fix route): per affected application repository, the Dockerfile FROM lines that would move from the installed version to the advisory's fixed version, the branch and credential the pull request would use, and the open Ankra pull request already there, if any; per image the lane cannot act on, the refusal and its reason (no application builds it, the application has no repository or GitHub credential, the credential cannot read the repository, no Dockerfile, no FROM line pins the installed version). A read: nothing is opened.

# Preview code finding disposition
Source: https://docs.ankra.ai/api-reference/security/preview-code-finding-disposition

https://platform.ankra.app/openapi.json post /api/v1/org/security/code-dispositions/preview
Reports the recorded finding a code finding disposition would cover and whether it can be created, writing nothing. Requires `security.manage`.

# Preview code finding disposition (browser session)
Source: https://docs.ankra.ai/api-reference/security/preview-code-finding-disposition-browser-session

https://platform.ankra.app/openapi.json post /org/security/code-dispositions/preview
Reports the recorded finding a code finding disposition would cover and whether it can be created, writing nothing. Requires `security.manage`.

# Preview vulnerability disposition policy
Source: https://docs.ankra.ai/api-reference/security/preview-vulnerability-disposition-policy

https://platform.ankra.app/openapi.json post /api/v1/org/security/vulnerability-dispositions/preview
Session authentication with CSRF; RBAC permission `security.triage`. Accepted-risk dispositions and previews carrying `policy_id` require `security.manage` instead.

# Preview vulnerability disposition policy (browser session)
Source: https://docs.ankra.ai/api-reference/security/preview-vulnerability-disposition-policy-browser-session

https://platform.ankra.app/openapi.json post /org/security/vulnerability-dispositions/preview
Session authentication with CSRF; RBAC permission `security.triage`. Accepted-risk dispositions and previews carrying `policy_id` require `security.manage` instead.

# Read a security remediation run
Source: https://docs.ankra.ai/api-reference/security/read-a-security-remediation-run

https://platform.ankra.app/openapi.json get /api/v1/org/security/remediations/{run_id}
One remediation run with its receipt trail.

# Read a security remediation run (browser session)
Source: https://docs.ankra.ai/api-reference/security/read-a-security-remediation-run-browser-session

https://platform.ankra.app/openapi.json get /org/security/remediations/{run_id}
One remediation run with its receipt trail.

# Revoke a security evidence destination
Source: https://docs.ankra.ai/api-reference/security/revoke-a-security-evidence-destination

https://platform.ankra.app/openapi.json post /api/v1/org/security/evidence/destinations/{destination_id}/revoke
Disables the destination, deletes its credential and cancels its undelivered deliveries; the row stays for the history.

# Revoke a security evidence destination (browser session)
Source: https://docs.ankra.ai/api-reference/security/revoke-a-security-evidence-destination-browser-session

https://platform.ankra.app/openapi.json post /org/security/evidence/destinations/{destination_id}/revoke
Disables the destination, deletes its credential and cancels its undelivered deliveries; the row stays for the history.

# Revoke code finding disposition
Source: https://docs.ankra.ai/api-reference/security/revoke-code-finding-disposition

https://platform.ankra.app/openapi.json post /api/v1/org/security/code-dispositions/{disposition_id}/revoke
Revokes a code finding disposition with a required `reason`; the image gate blocks on the finding again from its next run and the record is kept for audit. Requires `security.manage`; returns 409 when it is already revoked.

# Revoke code finding disposition (browser session)
Source: https://docs.ankra.ai/api-reference/security/revoke-code-finding-disposition-browser-session

https://platform.ankra.app/openapi.json post /org/security/code-dispositions/{disposition_id}/revoke
Revokes a code finding disposition with a required `reason`; the image gate blocks on the finding again from its next run and the record is kept for audit. Requires `security.manage`; returns 409 when it is already revoked.

# Running containers and their bills of materials
Source: https://docs.ankra.ai/api-reference/security/running-containers-and-their-bills-of-materials

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom/containers
Every container the resource cache says is running on the scoped clusters, init containers included, joined to the bill of materials of its image - or marked absent when the scanner has none for it. Absent is a state to act on (SBOM generation off, a registry the scanner cannot pull from, a tag rolled since the last scan), not an empty image. Sorted absent-first by default.

# Running containers and their bills of materials (browser session)
Source: https://docs.ankra.ai/api-reference/security/running-containers-and-their-bills-of-materials-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom/containers
Every container the resource cache says is running on the scoped clusters, init containers included, joined to the bill of materials of its image - or marked absent when the scanner has none for it. Absent is a state to act on (SBOM generation off, a registry the scanner cannot pull from, a tag rolled since the last scan), not an empty image. Sorted absent-first by default.

# Security filter options
Source: https://docs.ankra.ai/api-reference/security/security-filter-options

https://platform.ankra.app/openapi.json get /api/v1/org/security/filter-options
The values the namespace and add-on filters can match: the distinct namespaces and high-confidence add-on slugs on the organisation’s active occurrences, narrowed to one cluster when cluster_id is given. Feeds the console’s filter pickers, so every value returned filters the findings and workloads lists to a non-empty result.

# Security filter options (browser session)
Source: https://docs.ankra.ai/api-reference/security/security-filter-options-browser-session

https://platform.ankra.app/openapi.json get /org/security/filter-options
The values the namespace and add-on filters can match: the distinct namespaces and high-confidence add-on slugs on the organisation’s active occurrences, narrowed to one cluster when cluster_id is given. Feeds the console’s filter pickers, so every value returned filters the findings and workloads lists to a non-empty result.

# Security posture by cluster and namespace
Source: https://docs.ankra.ai/api-reference/security/security-posture-by-cluster-and-namespace

https://platform.ankra.app/openapi.json get /api/v1/org/security/namespaces
Active finding occurrences grouped by cluster and namespace, with the scanned workloads and images, the pods the cluster runs there, and the actionable findings by severity. Cluster-scoped reports carry a row with an empty namespace and report_scope 'cluster'.

# Security posture by cluster and namespace (browser session)
Source: https://docs.ankra.ai/api-reference/security/security-posture-by-cluster-and-namespace-browser-session

https://platform.ankra.app/openapi.json get /org/security/namespaces
Active finding occurrences grouped by cluster and namespace, with the scanned workloads and images, the pods the cluster runs there, and the actionable findings by severity. Cluster-scoped reports carry a row with an empty namespace and report_scope 'cluster'.

# Send security evidence to a destination
Source: https://docs.ankra.ai/api-reference/security/send-security-evidence-to-a-destination

https://platform.ankra.app/openapi.json post /api/v1/org/security/evidence/deliveries
Captures one bounded snapshot (the framework report if requested, and the SBOM image inventory KEV first, at most 2,000 images) and records it in the outbox, due now. A disabled framework or unrecorded month is refused.

# Send security evidence to a destination (browser session)
Source: https://docs.ankra.ai/api-reference/security/send-security-evidence-to-a-destination-browser-session

https://platform.ankra.app/openapi.json post /org/security/evidence/deliveries
Captures one bounded snapshot (the framework report if requested, and the SBOM image inventory KEV first, at most 2,000 images) and records it in the outbox, due now. A disabled framework or unrecorded month is refused.

# Set the security baseline policy mode (audit or enforce)
Source: https://docs.ankra.ai/api-reference/security/set-the-security-baseline-policy-mode-audit-or-enforce

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/security/policy-mode
Switches the security baseline's Kyverno policies between `audit` and `enforce` on one cluster by updating the policy add-on's configuration through GitOps, and returns the resulting commit. Requires `security.triage` or `security.manage`; returns 404 when the baseline policy add-on is not installed.

# Set the security baseline policy mode (audit or enforce) (browser session)
Source: https://docs.ankra.ai/api-reference/security/set-the-security-baseline-policy-mode-audit-or-enforce-browser-session

https://platform.ankra.app/openapi.json post /org/clusters/imported/{cluster_id}/security/policy-mode
Switches the security baseline's Kyverno policies between `audit` and `enforce` on one cluster by updating the policy add-on's configuration through GitOps, and returns the resulting commit. Requires `security.triage` or `security.manage`; returns 404 when the baseline policy add-on is not installed.

# Soft-revoke vulnerability disposition policy
Source: https://docs.ankra.ai/api-reference/security/soft-revoke-vulnerability-disposition-policy

https://platform.ankra.app/openapi.json post /api/v1/org/security/vulnerability-dispositions/{policy_id}/revoke
Revokes a disposition policy with a required `reason`, so it no longer applies to matching vulnerabilities; the policy record is kept for audit. Requires `security.manage`; returns 409 when it is already revoked.

# Soft-revoke vulnerability disposition policy (browser session)
Source: https://docs.ankra.ai/api-reference/security/soft-revoke-vulnerability-disposition-policy-browser-session

https://platform.ankra.app/openapi.json post /org/security/vulnerability-dispositions/{policy_id}/revoke
Revokes a disposition policy with a required `reason`, so it no longer applies to matching vulnerabilities; the policy record is kept for audit. Requires `security.manage`; returns 409 when it is already revoked.

# Start or reuse remediation runs for a security finding
Source: https://docs.ankra.ai/api-reference/security/start-or-reuse-remediation-runs-for-a-security-finding

https://platform.ankra.app/openapi.json post /api/v1/org/security/findings/{finding_id}/remediations
Opens or reuses the fix pull request per affected application repository (the image rebuild lane), starts or answers the live remediation run for each, and dispatches the pull request branch's head through Ankra Pipelines under the default branch's approved authority. Repeating the call reuses the live runs; nothing is approved, waived or accepted. The caller, a person through their session or their API token, is the one asking, so the organisation's AI autonomy pause and the application's keep_it_safe choice do not hold this start; they hold every step Ankra later takes on its own for the run, such as re-running its pipeline after an Ankra infrastructure error, which then stops the run at needs_human with the reason.

# Start or reuse remediation runs for a security finding (browser session)
Source: https://docs.ankra.ai/api-reference/security/start-or-reuse-remediation-runs-for-a-security-finding-browser-session

https://platform.ankra.app/openapi.json post /org/security/findings/{finding_id}/remediations
Opens or reuses the fix pull request per affected application repository (the image rebuild lane), starts or answers the live remediation run for each, and dispatches the pull request branch's head through Ankra Pipelines under the default branch's approved authority. Repeating the call reuses the live runs; nothing is approved, waived or accepted. The caller, a person through their session or their API token, is the one asking, so the organisation's AI autonomy pause and the application's keep_it_safe choice do not hold this start; they hold every step Ankra later takes on its own for the run, such as re-running its pipeline after an Ankra infrastructure error, which then stops the run at needs_human with the reason.

# Store the cluster's scheduled security report
Source: https://docs.ankra.ai/api-reference/security/store-the-clusters-scheduled-security-report

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/imported/{cluster_id}/security/report-schedule
Creates or replaces the cluster's scheduled security report: `frequency` (`weekly` or `monthly`), up to 20 email `recipients`, and `enabled` (default true, which needs at least one recipient). Requires `clusters.write` and returns the stored schedule.

# Store the cluster's scheduled security report (browser session)
Source: https://docs.ankra.ai/api-reference/security/store-the-clusters-scheduled-security-report-browser-session

https://platform.ankra.app/openapi.json put /org/clusters/imported/{cluster_id}/security/report-schedule
Creates or replaces the cluster's scheduled security report: `frequency` (`weekly` or `monthly`), up to 20 email `recipients`, and `enabled` (default true, which needs at least one recipient). Requires `clusters.write` and returns the stored schedule.

# Submit an uploaded Vanta evidence document
Source: https://docs.ankra.ai/api-reference/security/submit-an-uploaded-vanta-evidence-document

https://platform.ankra.app/openapi.json post /api/v1/org/security/evidence/deliveries/{delivery_id}/submit
Submits the Vanta document an uploaded delivery put there; upload and submission are separate. A refused or uncertain submission leaves the delivery uploaded with the reason.

# Submit an uploaded Vanta evidence document (browser session)
Source: https://docs.ankra.ai/api-reference/security/submit-an-uploaded-vanta-evidence-document-browser-session

https://platform.ankra.app/openapi.json post /org/security/evidence/deliveries/{delivery_id}/submit
Submits the Vanta document an uploaded delivery put there; upload and submission are separate. A refused or uncertain submission leaves the delivery uploaded with the reason.

# The cluster's scheduled security report
Source: https://docs.ankra.ai/api-reference/security/the-clusters-scheduled-security-report

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/security/report-schedule
Returns the cluster's scheduled security report configuration: frequency, email recipients and whether it is enabled.

# The cluster's scheduled security report (browser session)
Source: https://docs.ankra.ai/api-reference/security/the-clusters-scheduled-security-report-browser-session

https://platform.ankra.app/openapi.json get /org/clusters/imported/{cluster_id}/security/report-schedule
Returns the cluster's scheduled security report configuration: frequency, email recipients and whether it is enabled.

# The fleet's software bill of materials
Source: https://docs.ankra.ai/api-reference/security/the-fleets-software-bill-of-materials

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom
Every package the scanner found in the fleet's container images, grouped by name, version and ecosystem, with how many images, workloads and clusters carry it and the findings that name that exact package and version on those images. The coverage block says how many scanned clusters publish a bill of materials; the rest have SBOM generation switched off.

# The fleet's software bill of materials (browser session)
Source: https://docs.ankra.ai/api-reference/security/the-fleets-software-bill-of-materials-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom
Every package the scanner found in the fleet's container images, grouped by name, version and ecosystem, with how many images, workloads and clusters carry it and the findings that name that exact package and version on those images. The coverage block says how many scanned clusters publish a bill of materials; the rest have SBOM generation switched off.

# The pods of one namespace joined to their scanned workload's findings
Source: https://docs.ankra.ai/api-reference/security/the-pods-of-one-namespace-joined-to-their-scanned-workloads-findings

https://platform.ankra.app/openapi.json get /api/v1/org/security/pods
The running pods of one namespace on one cluster, each container joined to the findings of the scanned workload container behind it through the pod's owner chain. A container without a vulnerability report is marked scanned=false; a pod is scanned only when every container is, and scan_coverage and unscanned_containers name the containers a partially scanned pod is missing. Narrow to one workload with workload_uid, or workload_kind and workload_name.

# The pods of one namespace joined to their scanned workload's findings (browser session)
Source: https://docs.ankra.ai/api-reference/security/the-pods-of-one-namespace-joined-to-their-scanned-workloads-findings-browser-session

https://platform.ankra.app/openapi.json get /org/security/pods
The running pods of one namespace on one cluster, each container joined to the findings of the scanned workload container behind it through the pod's owner chain. A container without a vulnerability report is marked scanned=false; a pod is scanned only when every container is, and scan_coverage and unscanned_containers name the containers a partially scanned pod is missing. Narrow to one workload with workload_uid, or workload_kind and workload_name.

# Update vulnerability disposition policy
Source: https://docs.ankra.ai/api-reference/security/update-vulnerability-disposition-policy

https://platform.ankra.app/openapi.json patch /api/v1/org/security/vulnerability-dispositions/{policy_id}
Updates a disposition policy's `reason`, `expires_at` or `expire_when_fix_available`; at least one field is required. Requires `security.manage`; returns 409 when the policy has been revoked.

# Update vulnerability disposition policy (browser session)
Source: https://docs.ankra.ai/api-reference/security/update-vulnerability-disposition-policy-browser-session

https://platform.ankra.app/openapi.json patch /org/security/vulnerability-dispositions/{policy_id}
Updates a disposition policy's `reason`, `expires_at` or `expire_when_fix_available`; at least one field is required. Requires `security.manage`; returns 409 when the policy has been revoked.

# Where one package runs: the images carrying it, the workload containers running them, and their clusters
Source: https://docs.ankra.ai/api-reference/security/where-one-package-runs:-the-images-carrying-it-the-workload-containers-running-them-and-their-clusters

https://platform.ankra.app/openapi.json get /api/v1/org/security/sbom/component
Shows where one exact package (`name`, `version`, `package_type`) runs: the images carrying it, the workload containers running those images, and their clusters. Optionally narrowed with `cluster_id`; requires `security.read`.

# Where one package runs: the images carrying it, the workload containers running them, and their clusters (browser session)
Source: https://docs.ankra.ai/api-reference/security/where-one-package-runs:-the-images-carrying-it-the-workload-containers-running-them-and-their-clusters-browser-session

https://platform.ankra.app/openapi.json get /org/security/sbom/component
Shows where one exact package (`name`, `version`, `package_type`) runs: the images carrying it, the workload containers running those images, and their clusters. Optionally narrowed with `cluster_id`; requires `security.read`.

# Bind an explicit application namespace
Source: https://docs.ankra.ai/api-reference/services/bind-an-explicit-application-namespace

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/consumers
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Bind an explicit application namespace (browser session)
Source: https://docs.ankra.ai/api-reference/services/bind-an-explicit-application-namespace-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/consumers
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Choose the service behind an application's conventional connection names
Source: https://docs.ankra.ai/api-reference/services/choose-the-service-behind-an-applications-conventional-connection-names

https://platform.ankra.app/openapi.json put /api/v1/org/service-admission/connection-defaults
Requires the applications rollout flag, applications.deploy, and clusters.operate on the environment's cluster, all intersected with live token scopes. Chooses which managed service gives one application environment a protocol's conventional connection names (DATABASE_URL and the PG* names for postgres, REDIS_URL for redis, NATS_URL, OPENSEARCH_URL, S3_ENDPOINT and AWS_* for s3, ...), or, with instance_id null, that none does. Every service connected to the environment is always delivered under its own prefix (ORDERS_DB_DATABASE_URL); the conventional names belong to one service per protocol, recorded the first time a deploy delivers them, and never move by themselves. When that service stops serving the environment while another service of the protocol still does, the application's deploys are refused until a person chooses here; the instance read shows it as connection_delivery.holder_gone on the consumer. Nothing is deployed: the next deploy delivers the choice. A chosen service must be connected to the environment and speak the protocol.

# Choose the service behind an application's conventional connection names (browser session)
Source: https://docs.ankra.ai/api-reference/services/choose-the-service-behind-an-applications-conventional-connection-names-browser-session

https://platform.ankra.app/openapi.json put /org/service-admission/connection-defaults
Requires the applications rollout flag, applications.deploy, and clusters.operate on the environment's cluster, all intersected with live token scopes. Chooses which managed service gives one application environment a protocol's conventional connection names (DATABASE_URL and the PG* names for postgres, REDIS_URL for redis, NATS_URL, OPENSEARCH_URL, S3_ENDPOINT and AWS_* for s3, ...), or, with instance_id null, that none does. Every service connected to the environment is always delivered under its own prefix (ORDERS_DB_DATABASE_URL); the conventional names belong to one service per protocol, recorded the first time a deploy delivers them, and never move by themselves. When that service stops serving the environment while another service of the protocol still does, the application's deploys are refused until a person chooses here; the instance read shows it as connection_delivery.holder_gone on the consumer. Nothing is deployed: the next deploy delivers the choice. A chosen service must be connected to the environment and speak the protocol.

# Confirm a managed-service disconnection by its digest
Source: https://docs.ankra.ai/api-reference/services/confirm-a-managed-service-disconnection-by-its-digest

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/instances/{instance_id}/disconnections/{disconnection_id}/confirm
Requires the applications rollout flag, applications.deploy, clusters.operate on the service's cluster, and clusters.operate and clusters.read on the application environment's cluster, all intersected with live token scopes: the authority connecting it needed. Accepts only the stored disconnection and the digest its actor reviewed, resolves the plan again under the same locks and refuses when anything it covers moved, or when the plan asks for a choice of who gives the conventional names and none was made. In one transaction it takes the consumer off the instance's plan, records the connection release entry the environment's stored release renders for it so every deploy keeps that Secret byte for byte while pods still read it, records the choice for the conventional names, and audits it. The platform's disconnect lane then removes the Secret once no pod and no deployed workload reads it, takes the namespace off the client port when the plan said so, and settles. A retry returns the same record.

# Confirm a managed-service disconnection by its digest (browser session)
Source: https://docs.ankra.ai/api-reference/services/confirm-a-managed-service-disconnection-by-its-digest-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/instances/{instance_id}/disconnections/{disconnection_id}/confirm
Requires the applications rollout flag, applications.deploy, clusters.operate on the service's cluster, and clusters.operate and clusters.read on the application environment's cluster, all intersected with live token scopes: the authority connecting it needed. Accepts only the stored disconnection and the digest its actor reviewed, resolves the plan again under the same locks and refuses when anything it covers moved, or when the plan asks for a choice of who gives the conventional names and none was made. In one transaction it takes the consumer off the instance's plan, records the connection release entry the environment's stored release renders for it so every deploy keeps that Secret byte for byte while pods still read it, records the choice for the conventional names, and audits it. The platform's disconnect lane then removes the Secret once no pod and no deployed workload reads it, takes the namespace off the client port when the plan said so, and settles. A retry returns the same record.

# Confirm a managed-service retirement by its digest
Source: https://docs.ankra.ai/api-reference/services/confirm-a-managed-service-retirement-by-its-digest

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/instances/{instance_id}/retirements/{retirement_id}/confirm
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes. Accepts only the stored retirement and the digest its actor reviewed, resolves the plan again under the instance lock and enqueues one execution that removes the stack, waits for its members to be removed from the cluster, deletes the service's namespace once nothing else deploys into it, and releases the name only after the namespace is observed gone. Concurrent confirmations yield one execution; a retry returns the same receipt. The receipt is not proof of removal: follow the retirement's outcome.

# Confirm a managed-service retirement by its digest (browser session)
Source: https://docs.ankra.ai/api-reference/services/confirm-a-managed-service-retirement-by-its-digest-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/instances/{instance_id}/retirements/{retirement_id}/confirm
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes. Accepts only the stored retirement and the digest its actor reviewed, resolves the plan again under the instance lock and enqueues one execution that removes the stack, waits for its members to be removed from the cluster, deletes the service's namespace once nothing else deploys into it, and releases the name only after the namespace is observed gone. Concurrent confirmations yield one execution; a retry returns the same receipt. The receipt is not proof of removal: follow the retirement's outcome.

# Confirm a reviewed managed-service plan by its digest
Source: https://docs.ankra.ai/api-reference/services/confirm-a-reviewed-managed-service-plan-by-its-digest

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/reviews/{review_id}/confirm
Requires the applications rollout flag and live membership intersected with token scopes; reviews require applications.deploy, profiles.read and clusters.read. Preparing a review resolves the immutable package, the declared cluster policy, every explicitly bound consumer and every secret grant on the primary database, and stores an actor-bound plan with a digest and a ten-minute expiry. Confirming accepts only the stored review id and the reviewed digest, revalidates the same authority under row locks, and enqueues one cluster-scoped execution for a customer or existing-service plan; a retry returns the same receipt after current access checks. Hosted plans are refused at preparation: hosted operator-to-customer binding and cell dispatch are not wired, so nothing hosted can be reviewed or confirmed. A name an unreleased service instance already holds on the service cluster is refused with 409 Service name is already in use when the review is prepared, and again when it is confirmed: the reservation made at confirmation decides between concurrent reviews of one name. Service review has changed means only that the digest or the stored review changed. Plans never carry credential values. The execution receipt is not proof of service readiness. On a playground, prepare and confirm also check the plan's quota against what the tenant commits now: a shortfall is refused with 409 naming it, and a capacity the platform cannot establish is returned as capacity.state unknown without blocking.

# Confirm a reviewed managed-service plan by its digest (browser session)
Source: https://docs.ankra.ai/api-reference/services/confirm-a-reviewed-managed-service-plan-by-its-digest-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/reviews/{review_id}/confirm
Requires the applications rollout flag and live membership intersected with token scopes; reviews require applications.deploy, profiles.read and clusters.read. Preparing a review resolves the immutable package, the declared cluster policy, every explicitly bound consumer and every secret grant on the primary database, and stores an actor-bound plan with a digest and a ten-minute expiry. Confirming accepts only the stored review id and the reviewed digest, revalidates the same authority under row locks, and enqueues one cluster-scoped execution for a customer or existing-service plan; a retry returns the same receipt after current access checks. Hosted plans are refused at preparation: hosted operator-to-customer binding and cell dispatch are not wired, so nothing hosted can be reviewed or confirmed. A name an unreleased service instance already holds on the service cluster is refused with 409 Service name is already in use when the review is prepared, and again when it is confirmed: the reservation made at confirmation decides between concurrent reviews of one name. Service review has changed means only that the digest or the stored review changed. Plans never carry credential values. The execution receipt is not proof of service readiness. On a playground, prepare and confirm also check the plan's quota against what the tenant commits now: a shortfall is refused with 409 naming it, and a capacity the platform cannot establish is returned as capacity.state unknown without blocking.

# Connect an application to a managed service
Source: https://docs.ankra.ai/api-reference/services/connect-an-application-to-a-managed-service

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/instances/{instance_id}/consumers
Requires the applications rollout flag, applications.deploy, and clusters.operate and clusters.read on the service's cluster, which is also the environment's, all intersected with live token scopes. Adds one bound application environment (POST .../consumers) to the consumers of a service Ankra runs in your cluster, so a second application uses the same service instead of getting one of its own. The service is not redeployed and the generation does not move; only its client network policy is re-rendered to admit the environment's namespace (alongside the service's own and the cluster agent's), on a service whose profile version renders that policy from its consumers (an older one admits every namespace until it is updated). The environment joins the service's record of who uses it, receives the service's connection the next time the application deploys, cannot be unbound while the service uses it, and is disconnected by a retirement like every other consumer. A retirement reviewed before the change is refused when confirmed. The environment must be on the service's own cluster and in its data boundary. Connecting an environment that already uses the service again re-applies its network access and answers the service. Refused for another generation than the one read, and a service that is still installing, being retired, retired, or not one Ankra runs in your cluster. One service serves at most 100 environments. A 409 that says the application is connected but the network policy could not be opened yet means the environment was recorded; Ankra retries the network policy automatically within a few minutes, and connecting it again retries at once. A 409 that says the service's client access was changed by hand means the environment was recorded but Ankra did not edit a policy a person rewrote; add the namespace the instance's client_access lists.

# Connect an application to a managed service (browser session)
Source: https://docs.ankra.ai/api-reference/services/connect-an-application-to-a-managed-service-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/instances/{instance_id}/consumers
Requires the applications rollout flag, applications.deploy, and clusters.operate and clusters.read on the service's cluster, which is also the environment's, all intersected with live token scopes. Adds one bound application environment (POST .../consumers) to the consumers of a service Ankra runs in your cluster, so a second application uses the same service instead of getting one of its own. The service is not redeployed and the generation does not move; only its client network policy is re-rendered to admit the environment's namespace (alongside the service's own and the cluster agent's), on a service whose profile version renders that policy from its consumers (an older one admits every namespace until it is updated). The environment joins the service's record of who uses it, receives the service's connection the next time the application deploys, cannot be unbound while the service uses it, and is disconnected by a retirement like every other consumer. A retirement reviewed before the change is refused when confirmed. The environment must be on the service's own cluster and in its data boundary. Connecting an environment that already uses the service again re-applies its network access and answers the service. Refused for another generation than the one read, and a service that is still installing, being retired, retired, or not one Ankra runs in your cluster. One service serves at most 100 environments. A 409 that says the application is connected but the network policy could not be opened yet means the environment was recorded; Ankra retries the network policy automatically within a few minutes, and connecting it again retries at once. A 409 that says the service's client access was changed by hand means the environment was recorded but Ankra did not edit a policy a person rewrote; add the namespace the instance's client_access lists.

# Create a managed-service credential family
Source: https://docs.ankra.ai/api-reference/services/create-a-managed-service-credential-family

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/credentials
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# Create a managed-service credential family (browser session)
Source: https://docs.ankra.ai/api-reference/services/create-a-managed-service-credential-family-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/credentials
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# Create or rotate a reviewed credential value
Source: https://docs.ankra.ai/api-reference/services/create-or-rotate-a-reviewed-credential-value

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/credentials/{family_id}/values
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload. expected_value_id is required: null requires no active value; otherwise it must match the current active value. A repeated or concurrent stale request cannot replace a newer value. Successful rotation retires the previous value, revokes its grants and returns replacement grant metadata. Store acknowledgement must identify immutable version one. After an uncertain response reload family metadata and review the current value before another write.

# Create or rotate a reviewed credential value (browser session)
Source: https://docs.ankra.ai/api-reference/services/create-or-rotate-a-reviewed-credential-value-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/credentials/{family_id}/values
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload. expected_value_id is required: null requires no active value; otherwise it must match the current active value. A repeated or concurrent stale request cannot replace a newer value. Successful rotation retires the previous value, revokes its grants and returns replacement grant metadata. Store acknowledgement must identify immutable version one. After an uncertain response reload family metadata and review the current value before another write.

# Declare cluster service placement policy
Source: https://docs.ankra.ai/api-reference/services/declare-cluster-service-placement-policy

https://platform.ankra.app/openapi.json put /api/v1/org/service-admission/cluster-policies/{cluster_id}
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Declare cluster service placement policy (browser session)
Source: https://docs.ankra.ai/api-reference/services/declare-cluster-service-placement-policy-browser-session

https://platform.ankra.app/openapi.json put /org/service-admission/cluster-policies/{cluster_id}
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Fingerprint an accessible profile version
Source: https://docs.ankra.ai/api-reference/services/fingerprint-an-accessible-profile-version

https://platform.ankra.app/openapi.json get /api/v1/org/service-packages/profile-pins/{profile_id}/{profile_version_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Fingerprint an accessible profile version (browser session)
Source: https://docs.ankra.ai/api-reference/services/fingerprint-an-accessible-profile-version-browser-session

https://platform.ankra.app/openapi.json get /org/service-packages/profile-pins/{profile_id}/{profile_version_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Get a managed service instance
Source: https://docs.ankra.ai/api-reference/services/get-a-managed-service-instance

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/instances/{instance_id}
Durable organisation inventory, independent of the confirming actor and review retention. Requires live applications.read and clusters.read on all requested destinations and the service cluster, intersected with live token scopes. Uses primary authority reads so replica lag cannot extend revoked access. Deleted or inaccessible resources are hidden. No credentials, grant IDs, private plans, operation payloads or raw failures are returned. Deployment state reports recorded operation progress only; evidence_updated_at makes its age explicit. Missing, malformed, foreign or later-generation evidence is unknown. Successful deployment remains verification_pending with readiness unverified; this endpoint does not observe a service-specific consumer canary.

# Get a managed service instance (browser session)
Source: https://docs.ankra.ai/api-reference/services/get-a-managed-service-instance-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/instances/{instance_id}
Durable organisation inventory, independent of the confirming actor and review retention. Requires live applications.read and clusters.read on all requested destinations and the service cluster, intersected with live token scopes. Uses primary authority reads so replica lag cannot extend revoked access. Deleted or inaccessible resources are hidden. No credentials, grant IDs, private plans, operation payloads or raw failures are returned. Deployment state reports recorded operation progress only; evidence_updated_at makes its age explicit. Missing, malformed, foreign or later-generation evidence is unknown. Successful deployment remains verification_pending with readiness unverified; this endpoint does not observe a service-specific consumer canary.

# Get a managed-service retirement
Source: https://docs.ankra.ai/api-reference/services/get-a-managed-service-retirement

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/instances/{instance_id}/retirements/{retirement_id}
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes. Returns a retirement its actor prepared, with its state, phase and outcome. Another actor's retirement is not found.

# Get a managed-service retirement (browser session)
Source: https://docs.ankra.ai/api-reference/services/get-a-managed-service-retirement-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/instances/{instance_id}/retirements/{retirement_id}
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes. Returns a retirement its actor prepared, with its state, phase and outcome. Another actor's retirement is not found.

# Issue a purpose-bound credential reference
Source: https://docs.ankra.ai/api-reference/services/issue-a-purpose-bound-credential-reference

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/credential-grants
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload. Each issue creates an independently revocable reference. At most 128 active grants per family bounds rotation work.

# Issue a purpose-bound credential reference (browser session)
Source: https://docs.ankra.ai/api-reference/services/issue-a-purpose-bound-credential-reference-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/credential-grants
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload. Each issue creates an independently revocable reference. At most 128 active grants per family bounds rotation work.

# List an application's service consumer bindings
Source: https://docs.ankra.ai/api-reference/services/list-an-applications-service-consumer-bindings

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/consumers
Requires the applications rollout flag and live membership intersected with token scopes. Lists one application's stored namespace bindings, oldest identifier first, gated on applications.read; a binding is included only when the caller also holds clusters.read on its cluster, so a page can hold fewer rows than the limit, or none, while next_cursor is set. Rows are the bindings as last saved, not live-resolved consumers: a binding whose deployment or cluster policy is missing is still listed. No service deployment is executed.

# List an application's service consumer bindings (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-an-applications-service-consumer-bindings-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/consumers
Requires the applications rollout flag and live membership intersected with token scopes. Lists one application's stored namespace bindings, oldest identifier first, gated on applications.read; a binding is included only when the caller also holds clusters.read on its cluster, so a page can hold fewer rows than the limit, or none, while next_cursor is set. Rows are the bindings as last saved, not live-resolved consumers: a binding whose deployment or cluster policy is missing is still listed. No service deployment is executed.

# List immutable credential version metadata
Source: https://docs.ankra.ai/api-reference/services/list-immutable-credential-version-metadata

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/credentials/{family_id}/values
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# List immutable credential version metadata (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-immutable-credential-version-metadata-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/credentials/{family_id}/values
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# List managed-service credential metadata
Source: https://docs.ankra.ai/api-reference/services/list-managed-service-credential-metadata

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/credentials
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# List managed-service credential metadata (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-managed-service-credential-metadata-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/credentials
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# List managed service instances
Source: https://docs.ankra.ai/api-reference/services/list-managed-service-instances

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/instances
Durable organisation inventory, independent of the confirming actor and review retention. Requires live applications.read and clusters.read on all requested destinations and the service cluster, intersected with live token scopes. Uses primary authority reads so replica lag cannot extend revoked access. Deleted or inaccessible resources are hidden. No credentials, grant IDs, private plans, operation payloads or raw failures are returned. Deployment state reports recorded operation progress only; evidence_updated_at makes its age explicit. Missing, malformed, foreign or later-generation evidence is unknown. Successful deployment remains verification_pending with readiness unverified; this endpoint does not observe a service-specific consumer canary. Optional filters: application_id keeps the instances whose reviewed plan names a consumer of that application, so an application's services are one call; cluster_id keeps the instances running on that cluster; state keeps the instances in one state. Each instance carries cluster_name and each consumer its application_name, cluster_name and environment for display; the ids stay authoritative. Ascending UUID cursor order; one request examines at most 500 rows and returns at most 50 matching instances. next_cursor is set exactly when rows remain past it. A page shorter than limit that has a next_cursor always carries scan_capped true: the request stopped at its row bound before the page filled, which is never a statement that nothing more matches. Follow next_cursor until null.

# List managed service instances (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-managed-service-instances-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/instances
Durable organisation inventory, independent of the confirming actor and review retention. Requires live applications.read and clusters.read on all requested destinations and the service cluster, intersected with live token scopes. Uses primary authority reads so replica lag cannot extend revoked access. Deleted or inaccessible resources are hidden. No credentials, grant IDs, private plans, operation payloads or raw failures are returned. Deployment state reports recorded operation progress only; evidence_updated_at makes its age explicit. Missing, malformed, foreign or later-generation evidence is unknown. Successful deployment remains verification_pending with readiness unverified; this endpoint does not observe a service-specific consumer canary. Optional filters: application_id keeps the instances whose reviewed plan names a consumer of that application, so an application's services are one call; cluster_id keeps the instances running on that cluster; state keeps the instances in one state. Each instance carries cluster_name and each consumer its application_name, cluster_name and environment for display; the ids stay authoritative. Ascending UUID cursor order; one request examines at most 500 rows and returns at most 50 matching instances. next_cursor is set exactly when rows remain past it. A page shorter than limit that has a next_cursor always carries scan_capped true: the request stopped at its row bound before the page filled, which is never a statement that nothing more matches. Follow next_cursor until null.

# List package recipients as its owner
Source: https://docs.ankra.ai/api-reference/services/list-package-recipients-as-its-owner

https://platform.ankra.app/openapi.json get /api/v1/org/service-packages/{version_id}/shares
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# List package recipients as its owner (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-package-recipients-as-its-owner-browser-session

https://platform.ankra.app/openapi.json get /org/service-packages/{version_id}/shares
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# List purpose-bound credential grants
Source: https://docs.ankra.ai/api-reference/services/list-purpose-bound-credential-grants

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/credentials/{family_id}/grants
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# List purpose-bound credential grants (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-purpose-bound-credential-grants-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/credentials/{family_id}/grants
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# List visible package versions
Source: https://docs.ankra.ai/api-reference/services/list-visible-package-versions

https://platform.ankra.app/openapi.json get /api/v1/org/service-packages
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# List visible package versions (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-visible-package-versions-browser-session

https://platform.ankra.app/openapi.json get /org/service-packages
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# List your retirements of a managed service
Source: https://docs.ankra.ai/api-reference/services/list-your-retirements-of-a-managed-service

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/instances/{instance_id}/retirements
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes - checked before any retirement is read, and again against every listed plan. Lists only your own retirements of the instance, never another actor's, read on the primary database so a review prepared a moment ago is already listed: a client whose prepare answer was lost finds the review here instead of preparing again, which would spend another of its 10 open retirements. Each item is the single read's projection, its state folded against the database clock, so a review past its ten-minute window lists as expired, never pending. state keeps only the retirements in that state. Newest first: ordered by creation time, latest first, with the retirement id breaking ties. next_cursor is the id of the page's last retirement when more match; pass it as after to continue with older ones. after must name one of your own retirements of this instance: an unknown id, another actor's or another instance's retirement, or one deleted by retention since the cursor was issued is refused with 422 (Invalid service review page), and the listing starts again from the first page. A cursor whose retirement has since changed state still continues the listing. Nothing is skipped, so a page shorter than limit is the last one. An instance the organisation does not hold is not found, exactly as for prepare.

# List your retirements of a managed service (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-your-retirements-of-a-managed-service-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/instances/{instance_id}/retirements
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes - checked before any retirement is read, and again against every listed plan. Lists only your own retirements of the instance, never another actor's, read on the primary database so a review prepared a moment ago is already listed: a client whose prepare answer was lost finds the review here instead of preparing again, which would spend another of its 10 open retirements. Each item is the single read's projection, its state folded against the database clock, so a review past its ten-minute window lists as expired, never pending. state keeps only the retirements in that state. Newest first: ordered by creation time, latest first, with the retirement id breaking ties. next_cursor is the id of the page's last retirement when more match; pass it as after to continue with older ones. after must name one of your own retirements of this instance: an unknown id, another actor's or another instance's retirement, or one deleted by retention since the cursor was issued is refused with 422 (Invalid service review page), and the listing starts again from the first page. A cursor whose retirement has since changed state still continues the listing. Nothing is skipped, so a page shorter than limit is the last one. An instance the organisation does not hold is not found, exactly as for prepare.

# List your service reviews
Source: https://docs.ankra.ai/api-reference/services/list-your-service-reviews

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/reviews
Actor-scoped history on the primary database. Requires current applications rollout and applications.deploy; each row requires clusters.read for every destination and clusters.operate for the service cluster, intersected with live token scopes. Foreign actors, deleted resources and inaccessible reviews are hidden. Secret values, secret reference IDs and internal consumer binding IDs are never returned. Pending means only that the original review window has not expired; confirmation revalidates authority and configuration. Expired reviews require a new review; confirmed receipts remain confirmed after execution retention and are not readiness evidence. Newest first: ordered by creation time, latest first, with the review id breaking ties. next_cursor is the id of the last review the page inspected; pass it as after to continue with older reviews. after must name one of your own reviews: an unknown id, another actor's review, or a review deleted by retention since the cursor was issued is refused with 422 (Invalid service review page), and the listing starts again from the first page. A review prepared while you page is newer than your cursor, so it appears on a fresh first page rather than in the continuation. Scans at most 100 owned rows per request, skipping denied rows; a short or empty page may have next_cursor. A continuation means more owned rows remain to inspect, not necessarily more readable reviews. Follow until next_cursor is null.

# List your service reviews (browser session)
Source: https://docs.ankra.ai/api-reference/services/list-your-service-reviews-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/reviews
Actor-scoped history on the primary database. Requires current applications rollout and applications.deploy; each row requires clusters.read for every destination and clusters.operate for the service cluster, intersected with live token scopes. Foreign actors, deleted resources and inaccessible reviews are hidden. Secret values, secret reference IDs and internal consumer binding IDs are never returned. Pending means only that the original review window has not expired; confirmation revalidates authority and configuration. Expired reviews require a new review; confirmed receipts remain confirmed after execution retention and are not readiness evidence. Newest first: ordered by creation time, latest first, with the review id breaking ties. next_cursor is the id of the last review the page inspected; pass it as after to continue with older reviews. after must name one of your own reviews: an unknown id, another actor's review, or a review deleted by retention since the cursor was issued is refused with 422 (Invalid service review page), and the listing starts again from the first page. A review prepared while you page is newer than your cursor, so it appears on a fresh first page rather than in the continuation. Scans at most 100 owned rows per request, skipping denied rows; a short or empty page may have next_cursor. A continuation means more owned rows remain to inspect, not necessarily more readable reviews. Follow until next_cursor is null.

# Prepare a managed-service disconnection review
Source: https://docs.ankra.ai/api-reference/services/prepare-a-managed-service-disconnection-review

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/instances/{instance_id}/disconnections
Requires the applications rollout flag, applications.deploy, clusters.operate on the service's cluster, and clusters.operate and clusters.read on the application environment's cluster, all intersected with live token scopes: the authority connecting it needed. Resolves, on the primary database, what disconnecting one application environment from a running managed service does: the variables it stops receiving and, when this service gives the protocol's conventional names (DATABASE_URL, ...) while another service of the protocol is connected, the choices for who gives them next; that the shared credential is not revoked and how to make sure the application can no longer authenticate; whether the environment's release delivered the connection Secret; which deployed workloads read it, separating references Ankra attached (the next deploy removes them and rolls the workloads) from references written by hand; whether the namespace leaves the service's client port; when it takes effect; and what stays. It stores an actor-bound plan with a digest and a ten-minute expiry. Nothing changes. timing now is refused while every application of the service shares one credential. Refused while the service installs or retires, while a deploy of the environment is in flight, while the environment is already being disconnected, and for another generation. An actor may hold at most 10 open disconnection reviews and an organisation 50.

# Prepare a managed-service disconnection review (browser session)
Source: https://docs.ankra.ai/api-reference/services/prepare-a-managed-service-disconnection-review-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/instances/{instance_id}/disconnections
Requires the applications rollout flag, applications.deploy, clusters.operate on the service's cluster, and clusters.operate and clusters.read on the application environment's cluster, all intersected with live token scopes: the authority connecting it needed. Resolves, on the primary database, what disconnecting one application environment from a running managed service does: the variables it stops receiving and, when this service gives the protocol's conventional names (DATABASE_URL, ...) while another service of the protocol is connected, the choices for who gives them next; that the shared credential is not revoked and how to make sure the application can no longer authenticate; whether the environment's release delivered the connection Secret; which deployed workloads read it, separating references Ankra attached (the next deploy removes them and rolls the workloads) from references written by hand; whether the namespace leaves the service's client port; when it takes effect; and what stays. It stores an actor-bound plan with a digest and a ten-minute expiry. Nothing changes. timing now is refused while every application of the service shares one credential. Refused while the service installs or retires, while a deploy of the environment is in flight, while the environment is already being disconnected, and for another generation. An actor may hold at most 10 open disconnection reviews and an organisation 50.

# Prepare a managed-service retirement review
Source: https://docs.ankra.ai/api-reference/services/prepare-a-managed-service-retirement-review

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/instances/{instance_id}/retirements
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes. Resolves, on the primary database, what retiring the instance removes and keeps - its stack found by resource id with every member and the namespace it deploys into, the consumers it is disconnected from, the shared operators it keeps and what happens to its data - and stores an actor-bound plan with a digest and a ten-minute expiry. Nothing on the cluster changes. Refused while the installation runs, while another retirement runs, for another generation, for a disconnect set that is not exactly the service's consumers, for a stack changed outside Services, and without the data-loss acknowledgement. An actor may hold at most 10 open retirements and an organisation 50.

# Prepare a managed-service retirement review (browser session)
Source: https://docs.ankra.ai/api-reference/services/prepare-a-managed-service-retirement-review-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/instances/{instance_id}/retirements
Requires the applications rollout flag, applications.deploy, and on the service cluster clusters.operate, stacks.delete and clusters.read, plus clusters.read on every consumer cluster, all intersected with live token scopes. Resolves, on the primary database, what retiring the instance removes and keeps - its stack found by resource id with every member and the namespace it deploys into, the consumers it is disconnected from, the shared operators it keeps and what happens to its data - and stores an actor-bound plan with a digest and a ten-minute expiry. Nothing on the cluster changes. Refused while the installation runs, while another retirement runs, for another generation, for a disconnect set that is not exactly the service's consumers, for a stack changed outside Services, and without the data-loss acknowledgement. An actor may hold at most 10 open retirements and an organisation 50.

# Prepare an actor-bound managed-service plan review
Source: https://docs.ankra.ai/api-reference/services/prepare-an-actor-bound-managed-service-plan-review

https://platform.ankra.app/openapi.json post /api/v1/org/service-admission/reviews
Requires the applications rollout flag and live membership intersected with token scopes; reviews require applications.deploy, profiles.read and clusters.read. Preparing a review resolves the immutable package, the declared cluster policy, every explicitly bound consumer and every secret grant on the primary database, and stores an actor-bound plan with a digest and a ten-minute expiry. Confirming accepts only the stored review id and the reviewed digest, revalidates the same authority under row locks, and enqueues one cluster-scoped execution for a customer or existing-service plan; a retry returns the same receipt after current access checks. Hosted plans are refused at preparation: hosted operator-to-customer binding and cell dispatch are not wired, so nothing hosted can be reviewed or confirmed. A name an unreleased service instance already holds on the service cluster is refused with 409 Service name is already in use when the review is prepared, and again when it is confirmed: the reservation made at confirmation decides between concurrent reviews of one name. Service review has changed means only that the digest or the stored review changed. The request body is bounded at 16 KiB, which fits the maximum of 100 consumer_ids, 32 parameters and 16 secret_references. An actor may hold at most 20 open reviews and an organisation 100; a review that was never confirmed is deleted seven days after it expires. Plans never carry credential values. The execution receipt is not proof of service readiness. On a playground, prepare and confirm also check the plan's quota against what the tenant commits now: a shortfall is refused with 409 naming it, and a capacity the platform cannot establish is returned as capacity.state unknown without blocking.

# Prepare an actor-bound managed-service plan review (browser session)
Source: https://docs.ankra.ai/api-reference/services/prepare-an-actor-bound-managed-service-plan-review-browser-session

https://platform.ankra.app/openapi.json post /org/service-admission/reviews
Requires the applications rollout flag and live membership intersected with token scopes; reviews require applications.deploy, profiles.read and clusters.read. Preparing a review resolves the immutable package, the declared cluster policy, every explicitly bound consumer and every secret grant on the primary database, and stores an actor-bound plan with a digest and a ten-minute expiry. Confirming accepts only the stored review id and the reviewed digest, revalidates the same authority under row locks, and enqueues one cluster-scoped execution for a customer or existing-service plan; a retry returns the same receipt after current access checks. Hosted plans are refused at preparation: hosted operator-to-customer binding and cell dispatch are not wired, so nothing hosted can be reviewed or confirmed. A name an unreleased service instance already holds on the service cluster is refused with 409 Service name is already in use when the review is prepared, and again when it is confirmed: the reservation made at confirmation decides between concurrent reviews of one name. Service review has changed means only that the digest or the stored review changed. The request body is bounded at 16 KiB, which fits the maximum of 100 consumer_ids, 32 parameters and 16 secret_references. An actor may hold at most 20 open reviews and an organisation 100; a review that was never confirmed is deleted seven days after it expires. Plans never carry credential values. The execution receipt is not proof of service readiness. On a playground, prepare and confirm also check the plan's quota against what the tenant commits now: a shortfall is refused with 409 naming it, and a capacity the platform cannot establish is returned as capacity.state unknown without blocking.

# Preview managed service eligibility
Source: https://docs.ankra.ai/api-reference/services/preview-managed-service-eligibility

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/eligibility
Answers which catalogue package versions and modes one application environment - the namespace an application is, or is about to be, deployed to on a cluster - could set up right now, and for each that it cannot, the reason and what to do: a cluster that does not deploy through the Ankra native engine, a playground short of capacity, a mode that is not available (Ankra-hosted), a missing permission, and the rest a prepare refuses with. It runs the checks a prepare runs, through the same code, in a transaction it rolls back: no review is recorded, no name reserved and no review quota spent; the name is the one check it cannot make, since the name is chosen at setup. The service is previewed on the environment's own cluster with the package's default settings. An environment that is not bound yet is checked the way setup would bind it, which needs the application deployed in that namespace. Capacity the platform cannot establish reads unknown, never fits. It is a preview, not a reservation: it takes no lock, so a review quota, capacity or policy that changes before the setup is prepared can still refuse it, and the prepare answers authoritatively. Requires the applications rollout, applications.read and clusters.read on the cluster to ask, and profiles.read to read the catalogue; a member who may read but not deploy gets every mode blocked with permission_required. package_version_id checks one version; otherwise limit (default 10, at most 25) and after page the catalogue in its own order.

# Preview managed service eligibility (browser session)
Source: https://docs.ankra.ai/api-reference/services/preview-managed-service-eligibility-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/eligibility
Answers which catalogue package versions and modes one application environment - the namespace an application is, or is about to be, deployed to on a cluster - could set up right now, and for each that it cannot, the reason and what to do: a cluster that does not deploy through the Ankra native engine, a playground short of capacity, a mode that is not available (Ankra-hosted), a missing permission, and the rest a prepare refuses with. It runs the checks a prepare runs, through the same code, in a transaction it rolls back: no review is recorded, no name reserved and no review quota spent; the name is the one check it cannot make, since the name is chosen at setup. The service is previewed on the environment's own cluster with the package's default settings. An environment that is not bound yet is checked the way setup would bind it, which needs the application deployed in that namespace. Capacity the platform cannot establish reads unknown, never fits. It is a preview, not a reservation: it takes no lock, so a review quota, capacity or policy that changes before the setup is prepared can still refuse it, and the prepare answers authoritatively. Requires the applications rollout, applications.read and clusters.read on the cluster to ask, and profiles.read to read the catalogue; a member who may read but not deploy gets every mode blocked with permission_required. package_version_id checks one version; otherwise limit (default 10, at most 25) and after page the catalogue in its own order.

# Publish an immutable private package version
Source: https://docs.ankra.ai/api-reference/services/publish-an-immutable-private-package-version

https://platform.ankra.app/openapi.json post /api/v1/org/service-packages
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Publish an immutable private package version (browser session)
Source: https://docs.ankra.ai/api-reference/services/publish-an-immutable-private-package-version-browser-session

https://platform.ankra.app/openapi.json post /org/service-packages
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Read a cluster's service placement policy
Source: https://docs.ankra.ai/api-reference/services/read-a-clusters-service-placement-policy

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/cluster-policies/{cluster_id}
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Read a cluster's service placement policy (browser session)
Source: https://docs.ankra.ai/api-reference/services/read-a-clusters-service-placement-policy-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/cluster-policies/{cluster_id}
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Read a service consumer binding
Source: https://docs.ankra.ai/api-reference/services/read-a-service-consumer-binding

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/consumers/{consumer_id}
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Read a service consumer binding (browser session)
Source: https://docs.ankra.ai/api-reference/services/read-a-service-consumer-binding-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/consumers/{consumer_id}
Requires the applications rollout flag and live membership intersected with token scopes. Cluster policy reads require clusters.read and writes clusters.write. Consumer reads require applications.read and clusters.read; binding requires applications.deploy, clusters.operate and clusters.read. Locations are organisation declarations, not independently verified. No service deployment is executed. Updates require the current revision; zero creates only. Browser mutations require CSRF.

# Read an accessible package contract
Source: https://docs.ankra.ai/api-reference/services/read-an-accessible-package-contract

https://platform.ankra.app/openapi.json get /api/v1/org/service-packages/{version_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Read an accessible package contract (browser session)
Source: https://docs.ankra.ai/api-reference/services/read-an-accessible-package-contract-browser-session

https://platform.ankra.app/openapi.json get /org/service-packages/{version_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Read current managed-service credential metadata
Source: https://docs.ankra.ai/api-reference/services/read-current-managed-service-credential-metadata

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/credentials/{family_id}
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# Read current managed-service credential metadata (browser session)
Source: https://docs.ankra.ai/api-reference/services/read-current-managed-service-credential-metadata-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/credentials/{family_id}
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# Remove a service consumer binding
Source: https://docs.ankra.ai/api-reference/services/remove-a-service-consumer-binding

https://platform.ankra.app/openapi.json delete /api/v1/org/service-admission/consumers/{consumer_id}
Requires the applications rollout flag and live membership intersected with token scopes. Removing a binding requires applications.deploy, clusters.operate and clusters.read, and the binding's current revision as expected_revision. A binding a service that has not been released was planned with is kept (409); retire the service first. A pending review naming the binding no longer confirms. A binding whose cluster or application has since been removed can still be removed. No deployment changes. Browser mutations require CSRF.

# Remove a service consumer binding (browser session)
Source: https://docs.ankra.ai/api-reference/services/remove-a-service-consumer-binding-browser-session

https://platform.ankra.app/openapi.json delete /org/service-admission/consumers/{consumer_id}
Requires the applications rollout flag and live membership intersected with token scopes. Removing a binding requires applications.deploy, clusters.operate and clusters.read, and the binding's current revision as expected_revision. A binding a service that has not been released was planned with is kept (409); retire the service first. A pending review naming the binding no longer confirms. A binding whose cluster or application has since been removed can still be removed. No deployment changes. Browser mutations require CSRF.

# Resume your service review
Source: https://docs.ankra.ai/api-reference/services/resume-your-service-review

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/reviews/{review_id}
Actor-scoped history on the primary database. Requires current applications rollout and applications.deploy; each row requires clusters.read for every destination and clusters.operate for the service cluster, intersected with live token scopes. Foreign actors, deleted resources and inaccessible reviews are hidden. Secret values, secret reference IDs and internal consumer binding IDs are never returned. Pending means only that the original review window has not expired; confirmation revalidates authority and configuration. Expired reviews require a new review; confirmed receipts remain confirmed after execution retention and are not readiness evidence.

# Resume your service review (browser session)
Source: https://docs.ankra.ai/api-reference/services/resume-your-service-review-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/reviews/{review_id}
Actor-scoped history on the primary database. Requires current applications rollout and applications.deploy; each row requires clusters.read for every destination and clusters.operate for the service cluster, intersected with live token scopes. Foreign actors, deleted resources and inaccessible reviews are hidden. Secret values, secret reference IDs and internal consumer binding IDs are never returned. Pending means only that the original review window has not expired; confirmation revalidates authority and configuration. Expired reviews require a new review; confirmed receipts remain confirmed after execution retention and are not readiness evidence.

# Revoke a managed-service credential reference
Source: https://docs.ankra.ai/api-reference/services/revoke-a-managed-service-credential-reference

https://platform.ankra.app/openapi.json delete /api/v1/org/service-admission/credential-grants/{grant_id}
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# Revoke a managed-service credential reference (browser session)
Source: https://docs.ankra.ai/api-reference/services/revoke-a-managed-service-credential-reference-browser-session

https://platform.ankra.app/openapi.json delete /org/service-admission/credential-grants/{grant_id}
Requires the applications rollout and live organisation membership. Metadata reads require applications.read; writes require applications.write, intersected with live PAT scope. Browser mutations require CSRF. No secret values or store paths are returned; all responses are no-store. This registry operation does not connect or restart a workload.

# Revoke a package recipient
Source: https://docs.ankra.ai/api-reference/services/revoke-a-package-recipient

https://platform.ankra.app/openapi.json delete /api/v1/org/service-packages/{version_id}/shares/{organisation_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Revoke a package recipient (browser session)
Source: https://docs.ankra.ai/api-reference/services/revoke-a-package-recipient-browser-session

https://platform.ankra.app/openapi.json delete /org/service-packages/{version_id}/shares/{organisation_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Share a package version with an organisation
Source: https://docs.ankra.ai/api-reference/services/share-a-package-version-with-an-organisation

https://platform.ankra.app/openapi.json put /api/v1/org/service-packages/{version_id}/shares/{organisation_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Share a package version with an organisation (browser session)
Source: https://docs.ankra.ai/api-reference/services/share-a-package-version-with-an-organisation-browser-session

https://platform.ankra.app/openapi.json put /org/service-packages/{version_id}/shares/{organisation_id}
Requires live profiles.read, profiles.write (publication), or profiles.share (recipient management) permission, intersected with token scopes. Catalogue publication does not grant deployment permission, approve hosted operation, or assert runtime readiness. Shared metadata can remain visible after underlying profile access is revoked; contract reads then return 404. Profile fingerprints are rechecked on contract reads.

# Decrypt content using SOPS
Source: https://docs.ankra.ai/api-reference/sops/decrypt-content-using-sops

https://platform.ankra.app/openapi.json post /api/v1/org/sops/decrypt
Decrypts a SOPS-encrypted YAML document (`encrypted_yaml`) with the organisation's key and returns the plaintext. Requires `sops.use`.

# Encrypt content using SOPS
Source: https://docs.ankra.ai/api-reference/sops/encrypt-content-using-sops

https://platform.ankra.app/openapi.json post /api/v1/org/sops/encrypt
Encrypts the values selected by `encrypted_paths` in a YAML document (`yaml_content`) with the organisation's AGE key and returns the SOPS-encrypted document. Requires `sops.use`; a path that matches nothing is rejected.

# Get SOPS configuration including public key
Source: https://docs.ankra.ai/api-reference/sops/get-sops-configuration-including-public-key

https://platform.ankra.app/openapi.json get /api/v1/org/sops/config
Returns the organisation's SOPS configuration: its AGE public key, whether SOPS is enabled, and whether a key pair has been initialised. The private key is never returned.

# Approve stack profile generation consent
Source: https://docs.ankra.ai/api-reference/stack-profiles/approve-stack-profile-generation-consent

https://platform.ankra.app/openapi.json put /api/v1/org/stack-profiles/summary-generation-policy
A human with organisation-wide ai.manage approves the exact route and data-use notice previously displayed. Both acknowledgements and explicit bounded limits are required. Endpoint, credential and notice identities are server-derived; stale displayed consent conflicts. Approval does not enable deployment admission or publish a summary. Unknown commit outcomes require rereading the policy. Explicit OpenRouter routing is saved atomically with consent; a stale revision or digest rolls back both. Global AI routing and other tenants are unaffected.

# Approve stack profile generation consent (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/approve-stack-profile-generation-consent-browser-session

https://platform.ankra.app/openapi.json put /org/stack-profiles/summary-generation-policy
A human with organisation-wide ai.manage approves the exact route and data-use notice previously displayed. Both acknowledgements and explicit bounded limits are required. Endpoint, credential and notice identities are server-derived; stale displayed consent conflicts. Approval does not enable deployment admission or publish a summary. Unknown commit outcomes require rereading the policy. Explicit OpenRouter routing is saved atomically with consent; a stale revision or digest rolls back both. Global AI routing and other tenants are unaffected.

# Cancel a profile runtime qualification
Source: https://docs.ankra.ai/api-reference/stack-profiles/cancel-a-profile-runtime-qualification

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/summary-runtime-qualifications/{operation_id}/cancel
Requires fresh organisation-wide ai.manage and clusters.read on the recorded target; start and cancel also require clusters.operate. Token scopes and current membership are rechecked. Start derives the target from organisation staging settings, requires one recently checked-in agent, and serializes active runs across API replicas. Only a fixed synthetic nonce reaches the probe: no profile configuration, credentials or model request. Cancellation records a request; external cleanup remains unverified until independently observed. History remains readable when new starts are unconfigured. Browser writes require CSRF.

# Cancel a profile runtime qualification (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/cancel-a-profile-runtime-qualification-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/summary-runtime-qualifications/{operation_id}/cancel
Requires fresh organisation-wide ai.manage and clusters.read on the recorded target; start and cancel also require clusters.operate. Token scopes and current membership are rechecked. Start derives the target from organisation staging settings, requires one recently checked-in agent, and serializes active runs across API replicas. Only a fixed synthetic nonce reaches the probe: no profile configuration, credentials or model request. Cancellation records a request; external cleanup remains unverified until independently observed. History remains readable when new starts are unconfigured. Browser writes require CSRF.

# Cancel a stack profile summary generation
Source: https://docs.ankra.ai/api-reference/stack-profiles/cancel-a-stack-profile-summary-generation

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/summary-generations/{generation_id}/cancel
Requires fresh profiles.write authority and current source ownership, including after a draft edit or AI consent revocation. Accepts only an empty JSON object. Repeated cancellation is idempotent; other terminal jobs return 409. Returns cancelled only after a confirmed transaction commit. Cancellation fences later results but does not confirm physical provider cancellation or data deletion. On outcome_unknown, poll the source status before retrying.

# Cancel a stack profile summary generation (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/cancel-a-stack-profile-summary-generation-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/summary-generations/{generation_id}/cancel
Requires fresh profiles.write authority and current source ownership, including after a draft edit or AI consent revocation. Accepts only an empty JSON object. Repeated cancellation is idempotent; other terminal jobs return 409. Returns cancelled only after a confirmed transaction commit. Cancellation fences later results but does not confirm physical provider cancellation or data deletion. On outcome_unknown, poll the source status before retrying.

# Check a demo for service collisions
Source: https://docs.ankra.ai/api-reference/stack-profiles/check-a-demo-for-service-collisions

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/demos/{workspace_id}/collisions
Reads one running demo of a stack profile on the organisation's staging cluster and answers whether two services set up from a service package built on the profile could run side by side on one cluster. Every service gets a namespace of its own while each chart keeps its release name, so a cluster-scoped object the demo's releases own (ClusterRole, ClusterRoleBinding, CustomResourceDefinition, admission webhook configurations, PriorityClass, StorageClass, IngressClass, Namespace) whose name does not carry the demo's namespace (which its stack is named after) collides with a second service's copy of it. Services and Secrets whose names do carry it are listed as instance-specific, since a package connection naming them would not match another service. Only names, Secret types and Helm's release annotation are kept; the Secret data the listing carries is dropped, never kept or returned, and nothing is installed or written. `verdict` is `no_collision` only when every kind was read and nothing collides, `collisions` when something does, and `unknown` when the demo, or a kind, could not be read; `reason` says why.

# Check a demo for service collisions (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/check-a-demo-for-service-collisions-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/demos/{workspace_id}/collisions
Reads one running demo of a stack profile on the organisation's staging cluster and answers whether two services set up from a service package built on the profile could run side by side on one cluster. Every service gets a namespace of its own while each chart keeps its release name, so a cluster-scoped object the demo's releases own (ClusterRole, ClusterRoleBinding, CustomResourceDefinition, admission webhook configurations, PriorityClass, StorageClass, IngressClass, Namespace) whose name does not carry the demo's namespace (which its stack is named after) collides with a second service's copy of it. Services and Secrets whose names do carry it are listed as instance-specific, since a package connection naming them would not match another service. Only names, Secret types and Helm's release annotation are kept; the Secret data the listing carries is dropped, never kept or returned, and nothing is installed or written. `verdict` is `no_collision` only when every kind was read and nothing collides, `collisions` when something does, and `unknown` when the demo, or a kind, could not be read; `reason` says why.

# Classify the service a stack profile runs
Source: https://docs.ankra.ai/api-reference/stack-profiles/classify-the-service-a-stack-profile-runs

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/service-classification
Asks the organisation's service_classification AI lane (the Quick tier, Claude Haiku, unless the organisation chose another model for the lane) what kind of managed service the profile's latest version runs: an engine applications connect to over a protocol Ankra supports (`protocol` set), an engine Ankra has no protocol for, an application or piece of infrastructure, or unclear. Only the profile's name and description and each add-on's name, chart, chart version, registry and namespace are sent; configuration values and manifests never are. The answer is validated before it is returned and cached per profile version for 24 hours, and every call is metered and gated by the monthly AI allowance. Model trouble is never an error status: `available` false with `unavailable_reason` says why no classification could be made (no_addons, allowance_exhausted, ai_unavailable or model_error). Requires profiles.read on a profile the caller can see.

# Classify the service a stack profile runs (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/classify-the-service-a-stack-profile-runs-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/service-classification
Asks the organisation's service_classification AI lane (the Quick tier, Claude Haiku, unless the organisation chose another model for the lane) what kind of managed service the profile's latest version runs: an engine applications connect to over a protocol Ankra supports (`protocol` set), an engine Ankra has no protocol for, an application or piece of infrastructure, or unclear. Only the profile's name and description and each add-on's name, chart, chart version, registry and namespace are sent; configuration values and manifests never are. The answer is validated before it is returned and cached per profile version for 24 hours, and every call is metered and gated by the monthly AI allowance. Model trouble is never an error status: `available` false with `unavailable_reason` says why no classification could be made (no_addons, allowance_exhausted, ai_unavailable or model_error). Requires profiles.read on a profile the caller can see.

# Create a stack profile from a Helm chart
Source: https://docs.ankra.ai/api-reference/stack-profiles/create-a-stack-profile-from-a-helm-chart

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/from-chart
Makes one Helm chart from a registry your organisation can use into a stack profile and stores its first version, so a managed service can be published over it: one stack holding the chart, installed into the namespace named after each service. With `generated_secret`, the profile also carries a credentials release that generates that Secret's keys in the service's cluster on the first install and keeps them on every upgrade; Ankra never sees the values. Answers 201 with the profile and the version, and 422 naming the field a request cannot be built from.

# Create a stack profile from a Helm chart (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/create-a-stack-profile-from-a-helm-chart-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/from-chart
Makes one Helm chart from a registry your organisation can use into a stack profile and stores its first version, so a managed service can be published over it: one stack holding the chart, installed into the namespace named after each service. With `generated_secret`, the profile also carries a credentials release that generates that Secret's keys in the service's cluster on the first install and keeps them on every upgrade; Ankra never sees the values. Answers 201 with the profile and the version, and 422 naming the field a request cannot be built from.

# Create stack profile
Source: https://docs.ankra.ai/api-reference/stack-profiles/create-stack-profile

https://platform.ankra.app/openapi.json post /org/stack-profiles
Creates a stack profile from a stack deployed on one of your organisation's clusters (`source_cluster_id` and `stack_name`) and stores it as the profile's first version, answering 201 with the profile, the version and any warnings. Secret values captured from the stack are redacted; answers 409 when your organisation already has a profile with that name.

# Delete stack profile logo
Source: https://docs.ankra.ai/api-reference/stack-profiles/delete-stack-profile-logo

https://platform.ankra.app/openapi.json delete /org/stack-profiles/{profile_id}/logo
Removes the uploaded logo from a profile your organisation owns and returns the updated profile. Removing a logo that does not exist succeeds.

# Deprecate stack profile version
Source: https://docs.ankra.ai/api-reference/stack-profiles/deprecate-stack-profile-version

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/{profile_id}/versions/{version}/deprecation
Marks a published version of a profile your organisation owns as deprecated, with a `reason` (`incompatibility`, `critical_bug` or `cve`), an optional note and up to 20 references, and returns the version. The profile's current version cannot be deprecated; make another version current first.

# Deprecate stack profile version (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/deprecate-stack-profile-version-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/{profile_id}/versions/{version}/deprecation
Marks a published version of a profile your organisation owns as deprecated, with a `reason` (`incompatibility`, `critical_bug` or `cve`), an optional note and up to 20 references, and returns the version. The profile's current version cannot be deprecated; make another version current first.

# Edit a stack profile summary candidate
Source: https://docs.ankra.ai/api-reference/stack-profiles/edit-a-stack-profile-summary-candidate

https://platform.ankra.app/openapi.json put /api/v1/org/stack-profiles/summary-generations/{generation_id}/candidate
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Edit a stack profile summary candidate (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/edit-a-stack-profile-summary-candidate-browser-session

https://platform.ankra.app/openapi.json put /org/stack-profiles/summary-generations/{generation_id}/candidate
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Generate a summary for a stack profile draft
Source: https://docs.ankra.ai/api-reference/stack-profiles/generate-a-summary-for-a-stack-profile-draft

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/drafts/{draft_id}/summary-generation
Explicitly requests an unpublished summary for this exact owned source revision. Requires current profiles.write and ai.use, approved current data-use policy, available quota and the default-off admission gate. The server locks and normalizes stored configuration; clients cannot provide facts, source digests, models or consent. Retained exact-key retries return their original job before new-admission gate/policy checks. New stale UUIDv7 keys refuse rather than dispatch again after metadata cleanup. No model call occurs in this HTTP request; approval/publication are separate human actions.

# Generate a summary for a stack profile draft (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/generate-a-summary-for-a-stack-profile-draft-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/drafts/{draft_id}/summary-generation
Explicitly requests an unpublished summary for this exact owned source revision. Requires current profiles.write and ai.use, approved current data-use policy, available quota and the default-off admission gate. The server locks and normalizes stored configuration; clients cannot provide facts, source digests, models or consent. Retained exact-key retries return their original job before new-admission gate/policy checks. New stale UUIDv7 keys refuse rather than dispatch again after metadata cleanup. No model call occurs in this HTTP request; approval/publication are separate human actions.

# Generate a summary for a stack profile version
Source: https://docs.ankra.ai/api-reference/stack-profiles/generate-a-summary-for-a-stack-profile-version

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary-generation
Explicitly requests an unpublished summary for this exact owned source revision. Requires current profiles.write and ai.use, approved current data-use policy, available quota and the default-off admission gate. The server locks and normalizes stored configuration; clients cannot provide facts, source digests, models or consent. Retained exact-key retries return their original job before new-admission gate/policy checks. New stale UUIDv7 keys refuse rather than dispatch again after metadata cleanup. No model call occurs in this HTTP request; approval/publication are separate human actions.

# Generate a summary for a stack profile version (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/generate-a-summary-for-a-stack-profile-version-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/{profile_id}/versions/{version}/summary-generation
Explicitly requests an unpublished summary for this exact owned source revision. Requires current profiles.write and ai.use, approved current data-use policy, available quota and the default-off admission gate. The server locks and normalizes stored configuration; clients cannot provide facts, source digests, models or consent. Retained exact-key retries return their original job before new-admission gate/policy checks. New stale UUIDv7 keys refuse rather than dispatch again after metadata cleanup. No model call occurs in this HTTP request; approval/publication are separate human actions.

# Get a connection probe on a demo
Source: https://docs.ankra.ai/api-reference/stack-profiles/get-a-connection-probe-on-a-demo

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/demos/{workspace_id}/connection-probes/{probe_id}
Reads back a connection probe requested on one demo of a stack profile. `verdict` is passed (a pod in the demo's namespace connected), failed (the canary ran and did not connect; `reason` says how) or unknown (nothing was learned yet or at all; `reason` says why). `status` is queued, probed or expired; a probe not run within ten minutes expires, and an expired probe says nothing about the connection.

# Get a connection probe on a demo (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/get-a-connection-probe-on-a-demo-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/demos/{workspace_id}/connection-probes/{probe_id}
Reads back a connection probe requested on one demo of a stack profile. `verdict` is passed (a pod in the demo's namespace connected), failed (the canary ran and did not connect; `reason` says how) or unknown (nothing was learned yet or at all; `reason` says why). `status` is queued, probed or expired; a probe not run within ten minutes expires, and an expired probe says nothing about the connection.

# Get stack profile logo
Source: https://docs.ankra.ai/api-reference/stack-profiles/get-stack-profile-logo

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/logo
Returns the profile's uploaded logo image to any caller who can see the profile. A URL carrying `?v=` may be cached for a year; otherwise the response revalidates with an ETag.

# Get stack profile metadata suggestions
Source: https://docs.ankra.ai/api-reference/stack-profiles/get-stack-profile-metadata-suggestions

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/metadata-suggestions
Returns the categories and tags already used on stack profiles your organisation owns, for reuse when describing a profile.

# Get stack profile metadata suggestions (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/get-stack-profile-metadata-suggestions-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/metadata-suggestions
Returns the categories and tags already used on stack profiles your organisation owns, for reuse when describing a profile.

# Probe a proposed connection on a demo
Source: https://docs.ankra.ai/api-reference/stack-profiles/probe-a-proposed-connection-on-a-demo

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/{profile_id}/demos/{workspace_id}/connection-probes
Requests a probe of a proposed connection block against one running demo of a stack profile: the connection's own canary (PostgreSQL's SELECT 1, or the protocol's pod canary) runs in the demo's namespace on the organisation's staging cluster, before any package is published. The connection is validated as publishing validates it, and a credential given as a literal is refused, because the request is stored. The probe runs in the background; the answer is the queued probe, to be read back by `probe_id`. Requires stacks.deploy.

# Probe a proposed connection on a demo (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/probe-a-proposed-connection-on-a-demo-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/{profile_id}/demos/{workspace_id}/connection-probes
Requests a probe of a proposed connection block against one running demo of a stack profile: the connection's own canary (PostgreSQL's SELECT 1, or the protocol's pod canary) runs in the demo's namespace on the organisation's staging cluster, before any package is published. The connection is validated as publishing validates it, and a credential given as a literal is refused, because the request is stored. The probe runs in the background; the answer is the queued probe, to be read back by `probe_id`. Requires stacks.deploy.

# Propose a service connection from a demo
Source: https://docs.ankra.ai/api-reference/stack-profiles/propose-a-service-connection-from-a-demo

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/demos/{workspace_id}/connection-proposal
Observes one running demo of a stack profile on the organisation's staging cluster and proposes the connection blocks a service package built from the profile could declare: one per Service port speaking PostgreSQL, Redis, NATS, OpenSearch, S3, VictoriaLogs or VictoriaMetrics, with each field mapped to a key of the Secret that holds the most of its credentials. Only Service ports and Secret key names are read, never Secret values, and nothing is written or tried. `observable` false means the demo's namespace could not be observed yet (the demo is not ready, or the staging cluster could not list its Services and Secrets) and `reason` says why; it is never an empty answer. Publishing the package lets the readiness canary verify the connection.

# Propose a service connection from a demo (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/propose-a-service-connection-from-a-demo-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/demos/{workspace_id}/connection-proposal
Observes one running demo of a stack profile on the organisation's staging cluster and proposes the connection blocks a service package built from the profile could declare: one per Service port speaking PostgreSQL, Redis, NATS, OpenSearch, S3, VictoriaLogs or VictoriaMetrics, with each field mapped to a key of the Secret that holds the most of its credentials. Only Service ports and Secret key names are read, never Secret values, and nothing is written or tried. `observable` false means the demo's namespace could not be observed yet (the demo is not ready, or the staging cluster could not list its Services and Secrets) and `reason` says why; it is never an empty answer. Publishing the package lets the readiness canary verify the connection.

# Publish a stack profile draft
Source: https://docs.ankra.ai/api-reference/stack-profiles/publish-a-stack-profile-draft

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/drafts/{draft_id}/publish
Publishes the final normalized configuration atomically. Omit approved_summary_revision to publish without a summary. When attaching an approval, version and approved_summary_revision must be explicit positive integers; source identity, current authority and approval are rechecked under the publication locks. A mismatch returns 409 without creating a version or consuming the draft. No request may supply snapshots, source digests or approval identity. A 503 outcome is uncertain: reload the draft and versions before retrying.

# Publish a stack profile draft (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/publish-a-stack-profile-draft-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/drafts/{draft_id}/publish
Publishes the final normalized configuration atomically. Omit approved_summary_revision to publish without a summary. When attaching an approval, version and approved_summary_revision must be explicit positive integers; source identity, current authority and approval are rechecked under the publication locks. A mismatch returns 409 without creating a version or consuming the draft. No request may supply snapshots, source digests or approval identity. A 503 outcome is uncertain: reload the draft and versions before retrying.

# Read a profile runtime qualification
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-a-profile-runtime-qualification

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/summary-runtime-qualifications/{operation_id}
Requires fresh organisation-wide ai.manage and clusters.read on the recorded target; start and cancel also require clusters.operate. Token scopes and current membership are rechecked. Start derives the target from organisation staging settings, requires one recently checked-in agent, and serializes active runs across API replicas. Only a fixed synthetic nonce reaches the probe: no profile configuration, credentials or model request. Cancellation records a request; external cleanup remains unverified until independently observed. History remains readable when new starts are unconfigured. Browser writes require CSRF.

# Read a profile runtime qualification (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-a-profile-runtime-qualification-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/summary-runtime-qualifications/{operation_id}
Requires fresh organisation-wide ai.manage and clusters.read on the recorded target; start and cancel also require clusters.operate. Token scopes and current membership are rechecked. Start derives the target from organisation staging settings, requires one recently checked-in agent, and serializes active runs across API replicas. Only a fixed synthetic nonce reaches the probe: no profile configuration, credentials or model request. Cancellation records a request; external cleanup remains unverified until independently observed. History remains readable when new starts are unconfigured. Browser writes require CSRF.

# Read a stack profile summary generation
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-a-stack-profile-summary-generation

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/summary-generations/{generation_id}
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Read a stack profile summary generation (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-a-stack-profile-summary-generation-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/summary-generations/{generation_id}
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Read an approved stack profile summary
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-an-approved-stack-profile-summary

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Read an approved stack profile summary (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-an-approved-stack-profile-summary-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/versions/{version}/summary
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Read approved summary source labels
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-approved-summary-source-labels

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary/source-labels
Requires fresh profiles.read authority and access to the exact published version. Exposes only resource and admitted boolean parameter names already visible in that version, including authorized public and shared reads. Rechecks the current approval revision and normalizes the locked source against its private snapshot binding. No fingerprint, draft, candidate, configuration values or provider metadata is returned. Independent failures must not erase summary status; stale approval or revoked access requires a summary refresh. No AI call or consent is required.

# Read approved summary source labels (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-approved-summary-source-labels-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/versions/{version}/summary/source-labels
Requires fresh profiles.read authority and access to the exact published version. Exposes only resource and admitted boolean parameter names already visible in that version, including authorized public and shared reads. Rechecks the current approval revision and normalizes the locked source against its private snapshot binding. No fingerprint, draft, candidate, configuration values or provider metadata is returned. Independent failures must not erase summary status; stale approval or revoked access requires a summary refresh. No AI call or consent is required.

# Read draft summary source labels
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-draft-summary-source-labels

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/drafts/{draft_id}/summary-source-labels
Requires fresh profiles.write authority and ownership of the exact source. Reads bounded normalized configuration without AI calls or consent. Returns names only if the exact snapshot fingerprint matches. This independent read cannot alter approval, generate work or withdraw a summary. Names are private and excluded from model input and public/shared summary projections. Failure is unavailable or stale, never an empty label map.

# Read draft summary source labels (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-draft-summary-source-labels-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/drafts/{draft_id}/summary-source-labels
Requires fresh profiles.write authority and ownership of the exact source. Reads bounded normalized configuration without AI calls or consent. Returns names only if the exact snapshot fingerprint matches. This independent read cannot alter approval, generate work or withdraw a summary. Names are private and excluded from model input and public/shared summary projections. Failure is unavailable or stale, never an empty label map.

# Read stack profile generation consent
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-stack-profile-generation-consent

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/summary-generation-policy
Requires current organisation-wide ai.manage permission. Returns the server-derived data-use notice and current selected route without credential details. Null policy means no saved consent; unavailable route resolution keeps saved consent visible and consent_current null. No provider request is made. Admission is a separate default-off deployment gate. Optional routing preview changes only the displayed consent digest, never stored settings. Both routing query fields must occur exactly once.

# Read stack profile generation consent (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-stack-profile-generation-consent-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/summary-generation-policy
Requires current organisation-wide ai.manage permission. Returns the server-derived data-use notice and current selected route without credential details. Null policy means no saved consent; unavailable route resolution keeps saved consent visible and consent_current null. No provider request is made. Admission is a separate default-off deployment gate. Optional routing preview changes only the displayed consent digest, never stored settings. Both routing query fields must occur exactly once.

# Read stack profile summary evidence
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-stack-profile-summary-evidence

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary/evidence/{fact_id}
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Read stack profile summary evidence (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-stack-profile-summary-evidence-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/versions/{version}/summary/evidence/{fact_id}
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Read summary progress for a stack profile draft
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-summary-progress-for-a-stack-profile-draft

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/drafts/{draft_id}/summary-generation
Requires current profiles.write authority and source ownership. Returns private progress metadata only, with null generation when no job exists. Active jobs take priority, followed by the latest recorded job. Draft reads require the currently loaded source revision and return 409 if it changed; an older draft job is explicitly stale. Version reads never return jobs from a different immutable version. Candidate content requires the separate exact-source generation read. Database failures are not absence.

# Read summary progress for a stack profile draft (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-summary-progress-for-a-stack-profile-draft-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/drafts/{draft_id}/summary-generation
Requires current profiles.write authority and source ownership. Returns private progress metadata only, with null generation when no job exists. Active jobs take priority, followed by the latest recorded job. Draft reads require the currently loaded source revision and return 409 if it changed; an older draft job is explicitly stale. Version reads never return jobs from a different immutable version. Candidate content requires the separate exact-source generation read. Database failures are not absence.

# Read summary progress for a stack profile version
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-summary-progress-for-a-stack-profile-version

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary-generation
Requires current profiles.write authority and source ownership. Returns private progress metadata only, with null generation when no job exists. Active jobs take priority, followed by the latest recorded job. Draft reads require the currently loaded source revision and return 409 if it changed; an older draft job is explicitly stale. Version reads never return jobs from a different immutable version. Candidate content requires the separate exact-source generation read. Database failures are not absence.

# Read summary progress for a stack profile version (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-summary-progress-for-a-stack-profile-version-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/versions/{version}/summary-generation
Requires current profiles.write authority and source ownership. Returns private progress metadata only, with null generation when no job exists. Active jobs take priority, followed by the latest recorded job. Draft reads require the currently loaded source revision and return 409 if it changed; an older draft job is explicitly stale. Version reads never return jobs from a different immutable version. Candidate content requires the separate exact-source generation read. Database failures are not absence.

# Read version summary source labels
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-version-summary-source-labels

https://platform.ankra.app/openapi.json get /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary-source-labels
Requires fresh profiles.write authority and ownership of the exact source. Reads bounded normalized configuration without AI calls or consent. Returns names only if the exact snapshot fingerprint matches. This independent read cannot alter approval, generate work or withdraw a summary. Names are private and excluded from model input and public/shared summary projections. Failure is unavailable or stale, never an empty label map.

# Read version summary source labels (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/read-version-summary-source-labels-browser-session

https://platform.ankra.app/openapi.json get /org/stack-profiles/{profile_id}/versions/{version}/summary-source-labels
Requires fresh profiles.write authority and ownership of the exact source. Reads bounded normalized configuration without AI calls or consent. Returns names only if the exact snapshot fingerprint matches. This independent read cannot alter approval, generate work or withdraw a summary. Names are private and excluded from model input and public/shared summary projections. Failure is unavailable or stale, never an empty label map.

# Remove stack profile version deprecation
Source: https://docs.ankra.ai/api-reference/stack-profiles/remove-stack-profile-version-deprecation

https://platform.ankra.app/openapi.json delete /api/v1/org/stack-profiles/{profile_id}/versions/{version}/deprecation
Clears the deprecation notice from a version of a profile your organisation owns and returns the version. Clearing a version that is not deprecated changes nothing.

# Remove stack profile version deprecation (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/remove-stack-profile-version-deprecation-browser-session

https://platform.ankra.app/openapi.json delete /org/stack-profiles/{profile_id}/versions/{version}/deprecation
Clears the deprecation notice from a version of a profile your organisation owns and returns the version. Clearing a version that is not deprecated changes nothing.

# Review a stack profile summary candidate
Source: https://docs.ankra.ai/api-reference/stack-profiles/review-a-stack-profile-summary-candidate

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/summary-generations/{generation_id}/review
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Review a stack profile summary candidate (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/review-a-stack-profile-summary-candidate-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/summary-generations/{generation_id}/review
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Revoke stack profile generation consent
Source: https://docs.ankra.ai/api-reference/stack-profiles/revoke-stack-profile-generation-consent

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/summary-generation-policy/revoke
Revokes the expected organisation policy revision atomically with its audit. Remains usable when the selected provider or credentials are unavailable. Existing workers must recheck the changed consent; revocation does not promise provider-side physical deletion.

# Revoke stack profile generation consent (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/revoke-stack-profile-generation-consent-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/summary-generation-policy/revoke
Revokes the expected organisation policy revision atomically with its audit. Remains usable when the selected provider or credentials are unavailable. Existing workers must recheck the changed consent; revocation does not promise provider-side physical deletion.

# Share stack profile
Source: https://docs.ankra.ai/api-reference/stack-profiles/share-stack-profile

https://platform.ankra.app/openapi.json post /org/stack-profiles/{profile_id}/shares
Gives another organisation, identified by `organisation_slug`, read and instantiate access to a profile your organisation owns, answering 201 with the share. A profile can be shared with up to 50 organisations, and sharing is refused while any stored version contains secret values.

# Start a profile runtime qualification
Source: https://docs.ankra.ai/api-reference/stack-profiles/start-a-profile-runtime-qualification

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/summary-runtime-qualifications
Requires fresh organisation-wide ai.manage and clusters.read on the recorded target; start and cancel also require clusters.operate. Token scopes and current membership are rechecked. Start derives the target from organisation staging settings, requires one recently checked-in agent, and serializes active runs across API replicas. Only a fixed synthetic nonce reaches the probe: no profile configuration, credentials or model request. Cancellation records a request; external cleanup remains unverified until independently observed. History remains readable when new starts are unconfigured. Browser writes require CSRF.

# Start a profile runtime qualification (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/start-a-profile-runtime-qualification-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/summary-runtime-qualifications
Requires fresh organisation-wide ai.manage and clusters.read on the recorded target; start and cancel also require clusters.operate. Token scopes and current membership are rechecked. Start derives the target from organisation staging settings, requires one recently checked-in agent, and serializes active runs across API replicas. Only a fixed synthetic nonce reaches the probe: no profile configuration, credentials or model request. Cancellation records a request; external cleanup remains unverified until independently observed. History remains readable when new starts are unconfigured. Browser writes require CSRF.

# Store stack profile logo
Source: https://docs.ankra.ai/api-reference/stack-profiles/store-stack-profile-logo

https://platform.ankra.app/openapi.json put /org/stack-profiles/{profile_id}/logo
Uploads a PNG, JPEG or WebP logo of up to 512 KB, sent as the multipart field `file`, for a profile your organisation owns, and returns the updated profile. The upload replaces any external `logo_url`.

# Withdraw an approved stack profile summary
Source: https://docs.ankra.ai/api-reference/stack-profiles/withdraw-an-approved-stack-profile-summary

https://platform.ankra.app/openapi.json post /api/v1/org/stack-profiles/{profile_id}/versions/{version}/summary/withdraw
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Withdraw an approved stack profile summary (browser session)
Source: https://docs.ankra.ai/api-reference/stack-profiles/withdraw-an-approved-stack-profile-summary-browser-session

https://platform.ankra.app/openapi.json post /org/stack-profiles/{profile_id}/versions/{version}/summary/withdraw
Reads and decisions use the primary database with fresh permission, credential and source checks. Responses are private/no-store. Summary revisions never create or advance a workload profile version. No request accepts snapshots, approval identities or provider configuration.

# Add an attachment to a support ticket
Source: https://docs.ankra.ai/api-reference/support/add-an-attachment-to-a-support-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/support/tickets/{ticket_id}/attachments
Uploads a file, sent as the multipart field `file`, to the ticket and returns the updated ticket. Answers 415 for an unsupported file type, 413 for a file that is too large, and 409 when the ticket already has the maximum number of attachments.

# Close a support ticket
Source: https://docs.ankra.ai/api-reference/support/close-a-support-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/support/tickets/{ticket_id}/close
Closes the ticket and returns it. Closing a ticket that is already closed changes nothing.

# Comment on a support ticket
Source: https://docs.ankra.ai/api-reference/support/comment-on-a-support-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/support/tickets/{ticket_id}/comments
Adds a comment of up to 10,000 characters to the ticket and returns the updated ticket. A ticket waiting on the customer moves back to in progress.

# Create a support ticket
Source: https://docs.ankra.ai/api-reference/support/create-a-support-ticket

https://platform.ankra.app/openapi.json post /api/v1/org/support/tickets
Opens a support ticket and returns it, either from an earlier review (`review_id`) or directly from a subject and description. Answers 409 when the review has expired or when a flagged draft is sent without `acknowledged: true`, and 404 for a cluster outside the organisation.

# Download a support ticket attachment
Source: https://docs.ankra.ai/api-reference/support/download-a-support-ticket-attachment

https://platform.ankra.app/openapi.json get /api/v1/org/support/tickets/{ticket_id}/attachments/{attachment_id}
Returns the attachment's file content with its original filename and content type.

# Get a support ticket
Source: https://docs.ankra.ai/api-reference/support/get-a-support-ticket

https://platform.ankra.app/openapi.json get /api/v1/org/support/tickets/{ticket_id}
Returns the ticket with its comments and attachments. Answers 404 for a ticket that does not belong to the organisation.

# List support tickets
Source: https://docs.ankra.ai/api-reference/support/list-support-tickets

https://platform.ankra.app/openapi.json get /api/v1/org/support/tickets
Lists the organisation's support tickets, paginated, with filters for status, severity, category and cluster, a free-text search `q`, and sorting.

# Review a support ticket draft
Source: https://docs.ankra.ai/api-reference/support/review-a-support-ticket-draft

https://platform.ankra.app/openapi.json post /api/v1/org/support/tickets/review
Checks a ticket draft before it is opened and returns a `review_id`, valid for one hour, together with a quality verdict, clarifying questions and possible duplicate tickets. Pass the `review_id` when creating the ticket.

# Add a standalone VM
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/add-a-standalone-vm

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/vms
Adds a standalone VM with the given `name` and `instance_type` on the cluster network; its location defaults to the bastion's. On a running cluster its creation starts at once and the result carries the `operation_id`; on a stopped cluster it is created at the next start. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Add node group
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/add-node-group

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/node-groups
Adds a worker node group with the given `name`, `instance_type` and `count` (default 1), plus optional labels, taints and autoscaling settings. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Change ingress load balancer plan
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/change-ingress-load-balancer-plan

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/load-balancer-plan
Record a new UpCloud plan for the cluster's ingress load balancer. Ankra re-renders the Traefik Service's load balancer annotation and the UpCloud cloud controller manager moves the existing balancer onto the plan in place. The plan is checked against UpCloud's catalogue; refusals (unknown plan, non-UpCloud cluster, no Ankra-managed cloud controller or ingress, cloud provider stack not settled) answer 409.

# Change UpCloud NAT gateway plan
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/change-upcloud-nat-gateway-plan

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/gateway-plan
Changes the plan of the cluster's UpCloud NAT gateways in place. This interrupts the cluster's outbound internet access while UpCloud rebuilds the gateway: expect several minutes without outbound access, much longer than the roughly 20 seconds UpCloud documents, so choose a quiet time and confirm with the user first. Answers 202 once the change is recorded: the gateway update job carries it out and reports it complete only after the gateway runs on the new plan and the cluster's agent has checked in again over the restored egress. A stopped cluster's gateways take the plan at the next start. Invalid states (empty or unlisted plan, non-UpCloud cluster, no gateway, a gateway being created or deleted) answer 409 with a detail message.

# Check Kubernetes upgrade readiness
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/check-kubernetes-upgrade-readiness

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/upgrade-preflight
Runs the read-only upgrade preflight for a hop to target_version: the hop plan per node, running operations and the operations block, PodDisruptionBudgets that would park a drain, CloudNativePG stopDelay and single-instance clusters, control-plane memory headroom from the cluster's metrics source, restore points, control-plane SSH reachability and, on k3s, the address pin. Nothing is changed. The Kubernetes version upgrade runs the same preflight first and refuses on a block. Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Create an UpCloud cluster
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/create-an-upcloud-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud
Creates an UpCloud cluster from the request and starts provisioning it in the background, answering 201 with the new cluster's `cluster_id` and `name`. A configuration that fails validation answers 400 with the reason, and an organisation whose billing is restricted is refused with 402.

# Delete a standalone VM
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/delete-a-standalone-vm

https://platform.ankra.app/openapi.json delete /api/v1/clusters/upcloud/{cluster_id}/vms/{vm_id}
Deletes a standalone VM: it is handed to teardown and its server is removed at the provider. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Delete node group
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/delete-node-group

https://platform.ankra.app/openapi.json delete /api/v1/clusters/upcloud/{cluster_id}/node-groups/{group_name}
Removes a node group by draining and deleting its workers one at a time through their PodDisruptionBudgets; a worker whose drain is refused stays in service and the operation fails with the reason. Pass `force_drain=true` to take the whole group down regardless. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result. Requires `clusters.delete`.

# Deprovision an UpCloud cluster
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/deprovision-an-upcloud-cluster

https://platform.ankra.app/openapi.json delete /api/v1/clusters/upcloud/{cluster_id}
Deletes the cluster and its cloud resources. A delete that would remove persistent volumes, or cannot tell whether it does, is refused with 409 unless `accept_volume_data_loss=true` is passed (see the deprovision-volumes read); `force=true` tolerates infrastructure that can no longer be reached. Active operations on the cluster are cancelled and the response carries the teardown's `operation_id`.

# Diagnose bastion
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/diagnose-bastion

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/bastion/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `<provider>_bastion_diagnose` job over SSH and waits for its report within a bounded budget; a slower job answers the operation ids to poll. Browser mutations require CSRF.

# Diagnose node
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/diagnose-node

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/nodes/{node_id}/diagnose
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `upcloud_node_diagnose` job, the REST twin of the assistant's ssh_diagnose_node: over the platform's bastion SSH lane it snapshots the node's OS-level state (the Kubernetes service unit and its journal, disk, memory, uptime, the kernel log, the firewall path to the API server) and classifies the symptoms without changing anything on the host, and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Get bastion health
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/get-bastion-health

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/bastion/health
Bearer PAT authentication; RBAC permission `clusters.read`. Reports the verdict the bastion_health maintenance loop last recorded for the cluster's bastion or gateway host; it never probes the host itself.

# Get bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/get-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.read`. Returns the cluster's stored bastion SSH source allowlist, as the update on the same path stored it. `configured` tells a cleared list (true, empty) from one that was never set (false, empty); both leave SSH open from anywhere.

# Get current Kubernetes version
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/get-current-kubernetes-version

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/k8s-version
Returns the cluster's Kubernetes distribution with its current, desired and observed versions, whether any node still has to converge to the desired version, whether automatic patch upgrades are on, and the version of each node.

# Get current worker count
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/get-current-worker-count

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/worker-count
Returns the cluster's current worker count and the minimum and maximum it can be scaled to.

# Get disabled K3s components
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/get-disabled-k3s-components

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/k3s-disabled-components
Read the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), on top of the provider shape's own defaults. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states (a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider) answer 409 with a detail message.

# Get ingress load balancer plan
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/get-ingress-load-balancer-plan

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/load-balancer-plan
Read the UpCloud plan Ankra has recorded for the cluster's ingress load balancer beside the plans its live load balancers run on. load_balancer_plan is null when no plan was ever recorded: Ankra then leaves the balancer's plan alone. When UpCloud cannot be read, load_balancers_observed is false and load_balancers is null rather than empty.

# Latest restorable state snapshot of a UpCloud cluster
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/latest-restorable-state-snapshot-of-a-upcloud-cluster

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/state-snapshots/latest
The newest captured state snapshot (an encrypted etcd snapshot) a start of the UpCloud cluster may restore: its id, what triggered it (`stop`, `power_schedule` or `scheduled`), when it was captured and the Kubernetes version it holds. `snapshot` is null when the cluster has no restorable capture. Pass the id as `restore_snapshot_id` to start the cluster from it.

# List node groups
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/list-node-groups

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/node-groups
Lists the cluster's worker node groups with each group's instance type, node count, autoscaling bounds, labels and taints.

# List nodes
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/list-nodes

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/nodes
Lists the cluster's machines with each one's role, node group, instance type, location, state, private and public IPs, the kubelet version it reports and, where recorded, the provider's own status.

# List standalone VMs
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/list-standalone-vms

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/vms
Lists the cluster's standalone VMs (servers on the cluster network that are not Kubernetes nodes) with their instance type, location, state, addresses and provider ID.

# List UpCloud load balancer plans
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/list-upcloud-load-balancer-plans

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/load-balancer-plans
List UpCloud's managed load balancer plans, read live with the given credential: the choices for load_balancer_plan when creating an UpCloud cluster. development runs one load balancer node; the production plans run two (highly_available) and differ in session capacity.

# List UpCloud NAT gateway plans
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/list-upcloud-nat-gateway-plans

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/gateway-plans
Bearer PAT authentication; RBAC permission `clusters.read`. Lists the live UpCloud NAT gateway plans the credential's account can create (GET /1.3/gateway/plans) with bandwidth, server count and whether the plan is highly available, plus the plan a create without gateway_plan gets and the notice a day-2 plan change carries.

# Read control-plane sizing
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/read-control-plane-sizing

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/control-plane
Returns the control-plane count, the counts the cluster supports, the control planes' instance type, and whether a count or instance-type change is possible right now, with the reason when it is not.

# Read node
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/read-node

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/nodes/{node_id}
Returns one machine of the cluster with its definition, its latest recorded info and data, and its dependencies and relationships. Answers 404 when the node is not part of the cluster.

# Read node cloud-init log
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/read-node-cloud-init-log

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/nodes/{node_id}/cloud-init-log
Bearer PAT authentication; RBAC permission `clusters.operate`. Dispatches the read-only `upcloud_node_cloud_init_log` job: over the platform's bastion SSH lane it reads the node's `cloud-init status --long` and the tail of /var/log/cloud-init-output.log (the debug surface for node-group user_data), and waits for the report within a bounded budget; a slower job answers the operation ids to poll. Repeated calls attach to an in-flight run instead of dispatching duplicates. Browser mutations require CSRF.

# Read private cluster access
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/read-private-cluster-access

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/access-info
Returns what you need to reach the cluster's machines over SSH: the bastion's public IP, the control-plane IPs and the cluster name.

# Read SSH keys
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/read-ssh-keys

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/ssh-keys
Returns the SSH key credentials authorised on the cluster's servers (`ssh_key_credential_ids`) and the organisation's SSH key credentials that can be attached.

# Resize a standalone VM
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/resize-a-standalone-vm

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/vms/{vm_id}/instance-type
Resizes a standalone VM in place to the given `instance_type`. Answers 404 when the VM does not exist. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resize control-plane nodes
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/resize-control-plane-nodes

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/control-plane/instance-type
Changes the instance type of every control plane. On a running cluster the control planes are resized one at a time behind an etcd quorum check and a drain, and the response carries the `operation_id` to follow (clusters with fewer than three control planes are refused); on a stopped cluster the new type is applied at the next start and no operation is returned.

# Resize node group
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/resize-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/node-groups/{group_name}/instance-type
Changes the instance type of every worker in the node group. Each node is power-cycled, so the workers are drained and resized in bounded batches; `force_drain` bypasses PodDisruptionBudgets for that drain. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Resync SSH keys
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/resync-ssh-keys

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/ssh-keys/resync
Re-applies the cluster's configured SSH keys to its servers and returns the IDs of the resources queued for the update.

# Scale node group
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/scale-node-group

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/node-groups/{group_name}/scale
Sets the node group's node count to `count`. A scale-down drains the removed workers through their PodDisruptionBudgets; `force_drain` bypasses them for this request. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Scale UpCloud cluster workers
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/scale-upcloud-cluster-workers

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/scale-workers
Sets the cluster's worker count to `worker_count` and returns the previous and new counts. A scale-down drains the removed workers through their PodDisruptionBudgets unless `force_drain` is true. Requires `clusters.operate`.

# Start an UpCloud cluster
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/start-an-upcloud-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/start
Recreate the UpCloud cloud resources for a stopped cluster and reconcile it back to a running state.

# Stop an UpCloud cluster
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/stop-an-upcloud-cluster

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/stop
Initiate async deletion of UpCloud cloud resources (servers, networks, gateways, SSH keys) without removing the cluster from the database.

# The persistent volumes deleting a UpCloud cluster removes
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/the-persistent-volumes-deleting-a-upcloud-cluster-removes

https://platform.ankra.app/openapi.json get /api/v1/clusters/upcloud/{cluster_id}/deprovision-volumes
What deleting the cluster does to its persistent volumes: the cloud volumes its CSI driver provisioned that `DELETE /api/v1/clusters/upcloud/{cluster_id}` deletes with the cluster, or keeps when the cluster's retention_policy retains them. Read it before the delete to name the volumes and ask for `accept_volume_data_loss`. A cluster whose inventory was never synced, or could not be read, is unknown, never none.

# Update bastion SSH allowlist
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-bastion-ssh-allowlist

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/bastion/allowed-ips
Bearer PAT authentication; RBAC permission `clusters.write`. Replaces the cluster's bastion SSH source allowlist and dispatches the bastion update that applies it: the bastion's SSH port then accepts only the listed IPv4 sources, the platform's own egress addresses and private network sources, and drops everything else. An empty list clears the allowlist. Clusters that never set one keep SSH open from anywhere.

# Update control-plane count
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-control-plane-count

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/control-plane
Changes the number of control planes to `count`. On a running cluster the control plane can only grow, and the new control planes join live (`mode` `rolling`, with an `operation_id` to follow); a reduction is applied offline to a stopped cluster and takes effect at its next start.

# Update disabled K3s components
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-disabled-k3s-components

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/k3s-disabled-components
Replace the k3s packaged components the platform keeps disabled on this running cluster (k3s --disable), for example ["traefik"] on a cluster that brings its own ingress. k3s distribution only. The list is stored on every k8s node definition of the cluster. The maintenance read lane compares each control plane's k3s server config against it within about five minutes and flags the ones missing an entry; the reconcile lane then patches the config and restarts k3s on one control plane at a time, in the cluster's k8s update chain. Control planes already carrying every entry are not touched. Invalid states answer 409 with a detail message: a kubeadm or Scaleway cluster, no k8s node resources, a cluster of another provider, a list that drops a stored entry (re-enabling a bundled component is not supported yet, so the list only grows), a list that adds coredns (load-bearing for in-cluster DNS), and any change while a node update, version upgrade or node restart is in progress on the cluster.

# Update node-group labels
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-node-group-labels

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/node-groups/{group_name}/labels
Replaces the Kubernetes labels on every node in the node group with the given `labels` map. By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update node-group taints
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-node-group-taints

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/node-groups/{group_name}/taints
Replaces the taints on every node in the node group with the given `taints` list (each a `key`, an optional `value` and an `effect` of `NoSchedule`, `PreferNoSchedule` or `NoExecute`). By default the change runs in the background and the call answers 202 `{"status": "accepted"}` (409 if the same change is already in flight); pass `wait=true` to run it in the request and receive the result.

# Update SSH keys
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-ssh-keys

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/ssh-keys
Replaces the SSH key credentials authorised on the cluster's servers with `ssh_key_credential_ids` and starts rolling the keys out. An unknown or repeated credential, or two credentials carrying the same public key, is refused with 409.

# Update UpCloud zone pool
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/update-upcloud-zone-pool

https://platform.ankra.app/openapi.json put /api/v1/clusters/upcloud/{cluster_id}/zones
Extend an UpCloud cluster's zone pool. Zones can only be added; the cluster must run network_mode 'wireguard_mesh' and the grown pool must keep at least 3 zones with at least 3 control planes. Every new zone gets its own router, private network and NAT gateway; day-2 growth then spreads across the pool. Answers 404 while the organisation's network_overlay feature flag is off.

# Upgrade Kubernetes version
Source: https://docs.ankra.ai/api-reference/upcloud-clusters/upgrade-kubernetes-version

https://platform.ankra.app/openapi.json post /api/v1/clusters/upcloud/{cluster_id}/upgrade-k8s-version
Upgrades the cluster to `target_version`, which must be in the supported version catalogue and must not downgrade or skip a minor version. The cluster must be online with no change in progress; the nodes are upgraded as a rolling operation whose `operation_id` is returned, and `force` continues past a node drain that PodDisruptionBudgets refuse.

# Create an SSH key credential
Source: https://docs.ankra.ai/api-reference/upcloud-credentials/create-an-ssh-key-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/upcloud/ssh-key
Creates an SSH key credential from `name` and either `ssh_public_key` or `generate=true`; a generated RSA-4096 key pair's private key is returned once, in this response. A public key the organisation already stores under another credential is refused with 400. Requires `credentials.write`; answers 201.

# Create an UpCloud API credential
Source: https://docs.ankra.ai/api-reference/upcloud-credentials/create-an-upcloud-api-credential

https://platform.ankra.app/openapi.json post /api/v1/credentials/upcloud
Creates an UpCloud API credential from `name` and `api_token`. The token is checked against the UpCloud API before it is stored in Vault; an invalid token answers 400. Requires `credentials.write`; answers 201.

# Get UpCloud credential capacity (browser session)
Source: https://docs.ankra.ai/api-reference/upcloud-credentials/get-upcloud-credential-capacity-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/upcloud/{credential_id}/capacity
Browser session authentication; any member of the organisation that owns the credential. Reads the capacity and usage the UpCloud API exposes for this credential, live from the provider. Pass `measurement_version=1` to receive the versioned contract, which keeps measurements the provider did not report as null; without it the response omits `measurement_version` and projects unknown OVH and HPE Morpheus measurements as 0 for older clients. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# Get UpCloud credential quotas (browser session)
Source: https://docs.ankra.ai/api-reference/upcloud-credentials/get-upcloud-credential-quotas-browser-session

https://platform.ankra.app/openapi.json get /org/credentials/upcloud/{credential_id}/quotas
Browser session authentication; any member of the organisation that owns the credential. Reads the UpCloud limits and usage behind this credential and normalises them into one dimension per limit-bearing resource, with the dimensions under pressure listed first and the path to raising a limit. Pass `measurement_version=1` to keep an unreported `used` as null; without it an unreported usage is projected as 0, and `remaining` and `utilisation_percent` stay absent either way so no headroom is invented. Any other `measurement_version` answers 400. A credential of another provider or organisation answers 404; a provider API that refuses the read answers 400 with the provider's detail.

# List SSH key credentials
Source: https://docs.ankra.ai/api-reference/upcloud-credentials/list-ssh-key-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/upcloud/ssh-keys
Lists the organisation's SSH key credentials. The list is the same under every cloud provider. Each item carries the stored public key with the fingerprint (as `ssh-keygen -l` prints it), key type and comment derived from it; a stored value that is not a readable key keeps its row, with a null `fingerprint` and `fingerprint_error` saying why.

# List UpCloud API credentials
Source: https://docs.ankra.ai/api-reference/upcloud-credentials/list-upcloud-api-credentials

https://platform.ankra.app/openapi.json get /api/v1/credentials/upcloud
Lists the organisation's UpCloud API credentials with their metadata; the secret material is never returned.

# Get application service usage
Source: https://docs.ankra.ai/api-reference/usage/get-application-service-usage

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/applications/{application_id}/usage
The instance time and storage of every managed service instance whose reviewed plan serves the application, one line per instance, meter and period. An instance that serves other applications too says so with is_shared. Included during the pilot: no amount. Requires billing.read and applications.read.

# Get application service usage (browser session)
Source: https://docs.ankra.ai/api-reference/usage/get-application-service-usage-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/applications/{application_id}/usage
The instance time and storage of every managed service instance whose reviewed plan serves the application, one line per instance, meter and period. An instance that serves other applications too says so with is_shared. Included during the pilot: no amount. Requires billing.read and applications.read.

# Get managed service instance usage
Source: https://docs.ankra.ai/api-reference/usage/get-managed-service-instance-usage

https://platform.ankra.app/openapi.json get /api/v1/org/service-admission/instances/{instance_id}/usage
A managed service instance's instance time and storage, one line per meter and period. Instance time runs from the instance's deployment to its release and is counted while its cluster could be seen; storage is what the bound volume claims in its namespace requested. Minutes the platform could not see read unknown, never zero. Included during the pilot: no amount. Requires billing.read, and that the instance be visible to the caller as GET .../instances/{instance_id} decides.

# Get managed service instance usage (browser session)
Source: https://docs.ankra.ai/api-reference/usage/get-managed-service-instance-usage-browser-session

https://platform.ankra.app/openapi.json get /org/service-admission/instances/{instance_id}/usage
A managed service instance's instance time and storage, one line per meter and period. Instance time runs from the instance's deployment to its release and is counted while its cluster could be seen; storage is what the bound volume claims in its namespace requested. Minutes the platform could not see read unknown, never zero. Included during the pilot: no amount. Requires billing.read, and that the instance be visible to the caller as GET .../instances/{instance_id} decides.

# Get organisation usage
Source: https://docs.ankra.ai/api-reference/usage/get-organisation-usage

https://platform.ankra.app/openapi.json get /api/v1/org/billing/usage
Everything the organisation used of Ankra over a window, per meter and period: worker vCPU-hours, ordered playground time, managed service instance time and storage, hosted logs and metrics, and AI requests and tokens. Each line carries its unit, quantity, coverage and price state; usage nobody measured reads unknown with no quantity, never zero, and only a line with a published rate carries an amount, in euro cents. Requires billing.read.

# Get organisation usage (browser session)
Source: https://docs.ankra.ai/api-reference/usage/get-organisation-usage-browser-session

https://platform.ankra.app/openapi.json get /org/billing/usage
Everything the organisation used of Ankra over a window, per meter and period: worker vCPU-hours, ordered playground time, managed service instance time and storage, hosted logs and metrics, and AI requests and tokens. Each line carries its unit, quantity, coverage and price state; usage nobody measured reads unknown with no quantity, never zero, and only a line with a published rate carries an amount, in euro cents. Requires billing.read.

# Create a cluster variable
Source: https://docs.ankra.ai/api-reference/variables/create-a-cluster-variable

https://platform.ankra.app/openapi.json post /api/v1/org/clusters/imported/{cluster_id}/variables
Creates a variable with a `name`, `value` and optional `description` on the cluster and returns it. Answers 409 when the cluster already has a variable with that name.

# Create an organisation variable
Source: https://docs.ankra.ai/api-reference/variables/create-an-organisation-variable

https://platform.ankra.app/openapi.json post /api/v1/org/variables
Creates an organisation-wide variable with a `name`, `value` and optional `description` and returns it. Answers 409 when a variable with that name already exists.

# Delete a cluster variable
Source: https://docs.ankra.ai/api-reference/variables/delete-a-cluster-variable

https://platform.ankra.app/openapi.json delete /api/v1/org/clusters/imported/{cluster_id}/variables/{variable_name}
Deletes the named variable from the cluster. Answers 404 when the cluster or the variable does not exist.

# Delete an organisation variable
Source: https://docs.ankra.ai/api-reference/variables/delete-an-organisation-variable

https://platform.ankra.app/openapi.json delete /api/v1/org/variables/{variable_name}
Deletes the named organisation variable. Answers 404 when it does not exist.

# List cluster variables
Source: https://docs.ankra.ai/api-reference/variables/list-cluster-variables

https://platform.ankra.app/openapi.json get /api/v1/org/clusters/imported/{cluster_id}/variables
Lists the variables defined on the cluster, with their values and descriptions. Answers 404 for a cluster outside the organisation.

# List organisation variables
Source: https://docs.ankra.ai/api-reference/variables/list-organisation-variables

https://platform.ankra.app/openapi.json get /api/v1/org/variables
Lists the organisation-wide variables with their descriptions. Needs `variables.read`. A variable marked `is_secret` is listed with `value: null`; read it back with the reveal route. Platform-owned settings are not listed.

# List where an organisation variable is used
Source: https://docs.ankra.ai/api-reference/variables/list-where-an-organisation-variable-is-used

https://platform.ankra.app/openapi.json get /api/v1/org/variables/{variable_name}/usage
Lists the live stack members in the organisation that refer to the variable as `${{ ankra.<name> }}`: manifests, applications, add-on values and namespaces, and stack variables, each with its cluster and stack, and whether a cluster or stack variable of the same name shadows the organisation value. Needs `variables.read`; never carries a value. `unreadable` counts members whose stored content could not be decoded, so a non-zero count means the list may be incomplete.

# Reveal an organisation variable value
Source: https://docs.ankra.ai/api-reference/variables/reveal-an-organisation-variable-value

https://platform.ankra.app/openapi.json get /api/v1/org/variables/{variable_name}/value
Returns one variable's stored value, including a secret one. Needs `variables.write`, and every reveal is recorded in the organisation audit log. Answers 404 when it does not exist.

# Update a cluster variable
Source: https://docs.ankra.ai/api-reference/variables/update-a-cluster-variable

https://platform.ankra.app/openapi.json put /api/v1/org/clusters/imported/{cluster_id}/variables/{variable_name}
Replaces the variable's `value` and `description` and returns it; omitting `description` clears it. Answers 404 when the cluster or the variable does not exist.

# Update an organisation variable
Source: https://docs.ankra.ai/api-reference/variables/update-an-organisation-variable

https://platform.ankra.app/openapi.json put /api/v1/org/variables/{variable_name}
Partially updates the variable: each of `value`, `description` (null clears it) and `is_secret` is applied only when present, so a description or the secret flag can change without the value. Needs `variables.write`. Answers 404 when it does not exist and 403 for a platform-owned name.

# Bring a workspace up
Source: https://docs.ankra.ai/api-reference/workspaces/bring-a-workspace-up

https://platform.ankra.app/openapi.json post /api/v1/org/workspaces
Bearer PAT authentication; RBAC permission `workspaces.use`. Brings the caller's workspace for a repository and kind up, or answers the live one: 201 with a workspace this call created (placed on the repository's CI cluster, else the organisation's CI pool, else its pipeline cluster, and `provisioning` until a read finds its pod ready), 200 with the existing one. A ready workspace whose profile changed, and a failed one, are replaced.

# Cancel a workspace run
Source: https://docs.ankra.ai/api-reference/workspaces/cancel-a-workspace-run

https://platform.ankra.app/openapi.json post /api/v1/org/workspaces/{workspace_id}/runs/{run_id}/cancel
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Cancels a run: a command that has not started never will, and a running one gets SIGTERM with its whole process group. The run reads `cancelled` (without `finished_at`) until a read sees it end. A run that already ended answers as it is.

# Export a workspace run's results
Source: https://docs.ankra.ai/api-reference/workspaces/export-a-workspace-runs-results

https://platform.ankra.app/openapi.json post /api/v1/org/workspaces/{workspace_id}/runs/{run_id}/exports
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Uploads what a run left behind to the organisation's backup vault and answers a presigned GET of it: `patch` is the binary git diff an `apply` run made against the snapshot, `dirs` a gzipped tar of the named directories of the run's working directory. `{"empty": true}` when there is nothing to upload.

# Get a workspace
Source: https://docs.ankra.ai/api-reference/workspaces/get-a-workspace

https://platform.ankra.app/openapi.json get /api/v1/org/workspaces/{workspace_id}
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Reads one workspace. A `provisioning` workspace is checked first (devbox-preflight in its pod) and answered `ready`, `failed` with the reason, or still `provisioning`. The owner's read counts as a use and pushes `expires_at` out by the idle TTL.

# Get a workspace run
Source: https://docs.ankra.ai/api-reference/workspaces/get-a-workspace-run

https://platform.ankra.app/openapi.json get /api/v1/org/workspaces/{workspace_id}/runs/{run_id}
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Reads a run. One that has not ended is read from the pod (devbox-status) and its state recorded: `running`, `finished` with its exit code, `not_started` with the reason as its exit code, or `lost` when the pod no longer has its files.

# Get repository workspace profiles
Source: https://docs.ankra.ai/api-reference/workspaces/get-repository-workspace-profiles

https://platform.ankra.app/openapi.json get /api/v1/org/pipeline-repositories/{repository_id}/workspace-profiles
Bearer PAT authentication; RBAC permission `workspaces.use`. Answers the repository's workspace profiles keyed by kind: the image, size and service sidecars a workspace of that kind runs. A caller with `workspaces.manage` reads them whole; one with only `workspaces.use` reads which kinds exist, each as an empty profile. An empty object means its workspaces take their image from the repository's pipeline.

# List workspaces
Source: https://docs.ankra.ai/api-reference/workspaces/list-workspaces

https://platform.ankra.app/openapi.json get /api/v1/org/workspaces
Bearer PAT authentication; RBAC permission `workspaces.use`, or `workspaces.manage` with `all=true`. Lists the caller's live workspaces, newest first, or with `all=true` every member's and every run workspace (an unattended run's own workspace, `purpose` `run`), so one a run left behind can be found and deleted. `is_capped` is true when the listing stopped at 500.

# Presign a workspace bundle upload
Source: https://docs.ankra.ai/api-reference/workspaces/presign-a-workspace-bundle-upload

https://platform.ankra.app/openapi.json post /api/v1/org/workspaces/{workspace_id}/bundles
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Answers a presigned PUT for the client's git delta bundle, keyed by its SHA-256 under the workspace's own prefix in the organisation's backup vault, and whether the workspace already holds it (`exists`: the PUT can be skipped). The bundle is named to a run by `bundle_object_key`.

# Replace repository workspace profiles
Source: https://docs.ankra.ai/api-reference/workspaces/replace-repository-workspace-profiles

https://platform.ankra.app/openapi.json put /api/v1/org/pipeline-repositories/{repository_id}/workspace-profiles
Bearer PAT authentication; RBAC permission `workspaces.manage`. Replaces the repository's workspace profiles; `null` or `{}` clears them. Every profile is validated as a workspace would be rendered from it. A running workspace picks the change up at its owner's next bring-up, which replaces it.

# Start a workspace run
Source: https://docs.ankra.ai/api-reference/workspaces/start-a-workspace-run

https://platform.ankra.app/openapi.json post /api/v1/org/workspaces/{workspace_id}/runs
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Starts a command in the workspace against the client's snapshot and answers the run `accepted` (202) without waiting for it: the pod syncs the snapshot (base fetched from origin with the repository's credential, the uploaded bundle on top) and starts the command detached. Follow it on the stream. Only a redacted preview of the argv and the names of the forwarded environment variables are stored.

# Stream a workspace run's output
Source: https://docs.ankra.ai/api-reference/workspaces/stream-a-workspace-runs-output

https://platform.ankra.app/openapi.json get /api/v1/org/workspaces/{workspace_id}/runs/{run_id}/stream
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Relays a run's output as server-sent events from the given byte offsets: `stdout` and `stderr` events carry `{"data": "<base64>"}` with the id `<stdout offset>:<stderr offset>` after them; `exit` (`{"code", "started", "state", "message"}`) ends a run that ran to an exit, and a run that ended without an exit code for a reason the platform could tell (its `error_message`, such as running the workspace out of memory) gets that explanation as one `stderr` event without an id just before it and as the exit's `message`; `reconnect` (`{"stdout_offset", "stderr_offset", "reason"}`) ends a stream the platform cut (lost frames, a gateway restart, a dropped session, a 30 minute connection) and says where to resume; `error` (`{"message", "state"}`) ends one for a run the workspace no longer has. A keepalive comment is sent after 15 s of silence. `Last-Event-ID` wins over the offset parameters. The command runs on in the pod whatever happens to the connection, so output arrives exactly once across reconnects.

# Tear a workspace down
Source: https://docs.ankra.ai/api-reference/workspaces/tear-a-workspace-down

https://platform.ankra.app/openapi.json delete /api/v1/org/workspaces/{workspace_id}
Bearer PAT authentication; RBAC permission `workspaces.use` for the caller's own workspace, `workspaces.manage` for another member's. Tears the workspace down (its namespace, pod and volume go with it) and answers it `destroyed`; a destroyed workspace answers as it is. A teardown the cluster refused leaves it `tearing_down` with the reason, and is retried by the next call.

# Changelog
Source: https://docs.ankra.ai/changelog

Product updates and announcements

Every change to the Ankra platform, newest first. Use the tag filter beside this page to narrow it to `Pipelines`, `Security`, `Cost`, `Clusters`, `AI`, `GitOps`, `CLI`, `API` or `Fixes` - the selection is in the URL, so a filtered view is a link you can share. Subscribe at [docs.ankra.ai/changelog/rss.xml](https://docs.ankra.ai/changelog/rss.xml) to get each change as it ships.

Changes up to the end of August 2026 are kept as monthly records. From September 2026 each change has its own entry, and each week's smaller fixes are collected in one **Also shipped** entry. Command-line releases have their own [CLI changelog](/integrations/ankra-cli-changelog).

**2026-11-03**

## Each project's notifications and AI board threads can go to its own Slack or Teams channel

A notification route in a project now delivers only that project's notifications; an organisation-wide route still hears everything. A route created without a choice is in its creator's project, so check older routes. Board threads can bind a channel per project too, with the organisation's channel as the fallback.

[One channel per project →](/guides/notification-routing#example-one-channel-per-project)

**2026-11-02**

## Ankra AI also fixes a failed test step on a pull request

A failed `run` step (your tests, or any script the pipeline runs) on the setup pull request or on a pull request from a branch of your repository now gets the same fix as a failed build or image gate: Ankra AI commits the fix to that branch and watches the run its commit starts; before, a failing test reached nobody.

[When a pull request fails its checks →](/concepts/applications#when-a-pull-request-fails-its-checks)

**2026-11-01**

## Concurrency flags take an expression, so pull requests supersede old runs while pushes always finish

`cancel_in_progress` and `cancel_queued` now accept one `${{ }}` expression, settled for each run. One pipeline can let a pull request's new commit supersede its old run, while a push to your default branch always finishes and keeps only its newest waiting commit. It reads what is known before a run starts: the event, the commit and declared manual inputs. Anything it cannot settle counts as false, and `ankra pipeline validate` warns about it.

[A concurrency policy per event →](/guides/pipeline-reference#a-concurrency-policy-per-event)

**2026-11-01**

## Disconnect one application from a managed service that keeps running for the others

In closed beta: you can take one application environment off a managed service without deleting the service. A review comes first, and says that the shared credential is not revoked. Nothing changes until the application's next deploy, which rolls its workloads off the connection. Ankra then removes the connection Secret once no pod reads it and, unless you keep it, the namespace's network access. Available in the new Ankra portal, the CLI, the API, the AI Assistant and MCP.

[Disconnect an Application from a Managed Service →](/guides/disconnect-an-application-from-a-managed-service)

**2026-10-31**

## Add an application environment on a new cluster, copied from one you already run

In the new Ankra portal, **Add** beside an application's environments now offers **On a new cluster…**: Ankra creates the cluster with a copy of the stacks the environment's cluster runs, then deploys the application there as a new environment with the same image and settings and an address of its own. Secret overrides can come along; data does not.

[Add an environment on another cluster →](/guides/application-environments#add-an-environment-on-another-cluster)

**2026-10-31**

## Ankra leaves your own VMs, networks and storage alone on a shared Proxmox VE

You can connect a Proxmox VE installation that already runs your own VMs. Ankra only adds what it needs next to them. When saving the credential would touch your networks or storage, it stops before changing anything. Creating a cluster clones only Ankra's own template and never overcommits the memory on your hosts. Every VM Ankra creates is tagged `ankra` so you can tell it apart from yours.

[Connecting a Proxmox VE that already runs VMs →](/platform/credentials/proxmox#connecting-a-proxmox-ve-that-already-runs-vms)

**2026-10-30**

## Ankra AI is in the Microsoft Teams Store

Ankra AI is now published on the Microsoft Teams Store. In Teams, open **Apps**, search for **Ankra AI** and press **Add**, or use **Get it from the Teams Store** and **Open in Teams** on the portal's Microsoft Teams card. A tenant that restricts Store apps needs a Teams administrator to allow it once under **Manage apps**, and the app package stays available as a fallback for tenants that block Store apps entirely.

[Ankra AI on the Microsoft Teams Store →](https://marketplace.microsoft.com/en-us/product/teams-app/WA200012870)

**2026-10-30**

## The GitOps status shows the commit a cluster is in step with, and when each diverged file was found

The GitOps status now shows the commit a cluster is in step with and the Git head Ankra last read, with times, and each listed preserved file's detection time and decision; `ankra cluster gitops status` prints them with CLI v0.52.2 or later. The last sync time can read days old on a current cluster, because a commit that leaves its directory unchanged moves the applied commit without a sync. Deciding a file still takes the API.

[Applied Commit and Git Head →](/concepts/gitops#applied-commit-and-git-head)

**2026-10-30**

## The DevOps AI model by Ankra: \$50 a month on every plan, and the model that answers when you run out

Every catalog now carries **DevOps AI**, Ankra's own model, served on Ankra's own servers with the Ankra CLI skills preloaded. Every plan, the free tier included, gets \$50 a month on it, separate from the free monthly allowance; past that it bills per token. When the free allowance or your credit runs out, AI features switch to the DevOps AI model instead of stopping. Pick it in the model picker to use it on purpose.

[The DevOps AI model by Ankra →](/platform/ai-provider#the-devops-ai-model-by-ankra)

**2026-10-30**

## PersistentVolumes work on kubeadm Proxmox VE clusters

A `PersistentVolumeClaim` on a kubeadm Proxmox VE cluster now gets a disk on your Proxmox storage, attached to the VM that runs the pod. Nodes register with the providerID and topology labels the bundled CSI needs, and the driver talks to the API root. Nodes created before the fix need replacing, and the API token needs `Datastore.Audit`.

[Persistent Volumes on Proxmox VE Clusters →](/guides/proxmox-persistent-volumes)

**2026-10-28**

## A GitOps sync that would remove much of a cluster waits for you, and a migration re-run names each database it replaces

A GitOps sync that would remove a large share of a cluster, such as two of its four stacks, applies nothing until you remove them through Ankra. A restore into a database Ankra already restored into needs `--overwrite-database`, so the `ankra migrate up` cutover names each one. A stopped cluster's state snapshot is kept while it stays stopped. Ankra AI, MCP and service accounts can schedule a scale-to-zero stop only on a cluster a person confirmed as non-production.

[Large Removals Are Held →](/concepts/gitops#large-removals-are-held)

**2026-10-28**

## Resize the only control plane of a running Hetzner cluster, with a few minutes of API downtime

A Hetzner cluster with one controller no longer has to be stopped to change the controller's server type. Ankra resizes it in place: the Kubernetes API is down for a few minutes while the server reboots, and workloads on the workers keep running. You accept the downtime first, with **Resize with API downtime** in the dashboard or `--accept-api-downtime` on the CLI. Other providers still need three controllers or a stopped cluster.

[Change the control plane instance type →](/guides/operate-ankra-managed-clusters#change-the-control-plane-instance-type)

**2026-10-28**

## A guide to running Ankra on Talos Linux clusters

A new guide sets out what Talos owns - the nodes, the OS and the control plane - and what Ankra adds above the Kubernetes API, from Stacks and GitOps to backups, access and AI operations. It imports a Talos cluster, declares its first Stack, and covers Pod Security admission and the CNI.

[Talos Linux Clusters →](/guides/talos-clusters)

**2026-10-28**

## A guide to building Bazel repositories on Ankra Pipelines

A new guide runs Bazel on Ankra Pipelines: Bazelisk and the output tree on the shared workspace, a disk and repository cache kept between runs, JUnit results from `bazel-testlogs`, an optional remote cache, and a Bazel-built binary scanned, gated and published as an image.

[Bazel →](/guides/bazel-pipelines)

**2026-10-28**

## The Hetzner guide covers the payment method, SSH key and server types you need first

The Hetzner Clusters guide now says up front that creating a Hetzner cluster needs a payment method on the organisation and an SSH key credential, and walks through the new portal's wizard at **Infrastructure → Clusters → Add a cluster → Hetzner**. Its examples use `cpx12` and `cpx22`, because the `cx` line is often unavailable in `fsn1` and other locations; check what a location sells with `ankra cluster hetzner server-types` first.

[Hetzner Clusters →](/guides/hetzner-clusters#before-you-start)

**2026-10-28**

## A new film walks through a Hetzner cluster from create to an app over TLS

The Hetzner Clusters guide has a new video: a real cluster in `fsn1` with one `cpx32` control plane and two `cpx22` workers, created from the dashboard and the CLI. All three nodes were Ready five minutes after the create call, and a small stack then answered on the cluster's own hostname with a Let's Encrypt certificate.

[Hetzner Clusters →](/guides/hetzner-clusters#create-the-cluster)

**2026-10-28**

## Projects: give each team its own room inside your organisation

Every organisation on the new portal now has projects. A project holds its own clusters, applications, pipelines and cost; people, roles and the invoice stay organisation-wide. Everything you have is in your Default project, so nothing changes until you create a second one. Then move resources into it, invite **Project only** members who see nothing else, read cost by project, and use `ankra project` and `--project` from the CLI.

[Projects →](/concepts/projects)

**2026-10-27**

## With no AI allowance left, Ankra upgrades vulnerable Python packages on a pull request itself

When the image gate blocks a pull request on vulnerable Python packages and your organisation's AI allowance is used up, Ankra no longer waits for the allowance. It moves each package a lock file pins to a release that fixes it, checks the new pins against the packages' own requirements, and commits that to the pull request on GitHub. The run that commit starts checks the result, and anything left waits for the allowance.

[When a pull request fails its checks →](/concepts/applications#when-a-pull-request-fails-its-checks)

**2026-10-27**

## Kubernetes upgrades have a guide with tested resume and recovery paths

A new guide covers upgrading Kubernetes on clusters Ankra provisions: measured timings per node, the restore points that exist, and a pre-upgrade checklist. It shows how to resume a hop a PodDisruptionBudget or a cancel stopped with `ankra cluster operations retry`, how Ankra rolls back a failed control plane, and how to rebuild a cluster from its off-cluster state with a stop and a restoring start, each tested end to end.

[Upgrade Kubernetes on a Cluster →](/guides/kubernetes-upgrades)

**2026-10-27**

## Each application environment can follow its own branches, and a pipeline can see where a push deploys

Give an environment a branch rule and pushes to matching branches deploy there: production follows `main`, development `develop` or every branch except `main`, staging `release/*`. Rules use the same patterns as `when.branches`, and changing one is never itself a deploy. In a pipeline, `ankra.environments` lists the environments the run's push deploys to, so a stage can run only on its way to production.

[Environments and branch rules →](/guides/application-environments)

**2026-10-26**

## Ankra AI fixes a failing pull request on its own branch, merge conflicts included

A failed build or security gate on a pull request from a branch of your repository is now fixed on that pull request: Ankra AI commits the fix to its branch and watches the new run, with no second pull request. A pull request that conflicts with its base gets a merge commit that resolves it. Forks still get a diagnosis. With the AI allowance used up, the pull request says when the fix will start.

[When a pull request fails its checks →](/concepts/applications#when-a-pull-request-fails-its-checks)

**2026-10-26**

## A managed service's connection reaches its application without a redeploy

In closed beta: once a managed service is ready, Ankra writes its connection Secret into the namespace of each application it serves on the same cluster, without redeploying or restarting anything, while no running pod of the application references it. When running pods already reference it, the application's next deploy writes it and rolls them together. The API's new `connection_delivery.pickup` says whether an application needs a deploy or a restart to read it.

[Connect to a Managed Service →](/guides/connect-to-a-managed-service#how-your-application-receives-the-connection)

**2026-10-26**

## Importing an application keeps the CI you already have

When the repository you import already builds and pushes its image, from GitHub Actions, GitLab CI, Bitbucket Pipelines or CircleCI, Ankra now adopts that pipeline: it deploys the image your CI publishes and the setup pull request adds no second pipeline or Dockerfile. CI that only runs tests is kept. The analysis also tells you when your CI is not starting, and how to fix it.

[When your repository already has CI →](/concepts/applications#when-your-repository-already-has-ci)

**2026-10-24**

## The welcome credit is now €59 for 60 days

New organisations now unlock €59 of welcome credit when they save a payment method, instead of €249. The credit is still valid for 60 days. New Ankra Cloud accounts receive the same €59 sign-up credit. Credit that was granted before this change keeps its original amount and expiry date.

[Welcome credit →](/platform/billing#welcome-credit)

**2026-10-23**

## The merge train keeps testing while GitHub declines a merge

When GitHub declines the first car's merge, for example because a required check is still running, the pull requests behind it now keep building and testing instead of waiting. A merge declined because a required check failed leaves the train after 15 minutes instead of three hours, so one red check no longer holds the train.

[The merge train →](/pipelines/merge-train#merges-github-declines)

**2026-10-22**

## Approve a portability or next.config pull request in the Launch Plan and Ankra opens it

A portability pull request, or the next.config pull request that moves your `vercel.json` routing into `next.config`, is now an action you can approve in the Launch Plan. Open it once under your approval and Ankra opens it on your repository at the plan's commit. If Ankra cannot make the change with confidence, it says why a person has to, and opens nothing. Ankra never merges these pull requests.

[Portability pull requests →](/use-cases/vercel-to-ankra#portability-pull-requests)

**2026-10-22**

## Move a pull request to the front of the merge train

With CLI 0.47.0 or later, an organisation administrator can put a pull request at the front of a repository's merge train with `ankra pipeline train front <pull request>`. It goes ahead of every pull request that is still waiting or being tested, and those are tested again on top of it. Pull requests that already passed or are being merged stay ahead.

[The merge train →](/guides/ankra-pipelines#the-merge-train-test-every-pull-request-as-it-will-merge)

**2026-10-21**

## Ankra AI acts on an approved Launch Plan without asking again

Once you approve a Launch Plan, Ankra AI runs the approved actions without asking you again: in your chat, in an agent run, or over MCP. Anything outside the plan still asks first. Each approved action runs once. The approval stops working when it expires, when you revoke it, or when the plan changes. Only your own runs can use it.

[MCP server →](/platform/mcp-server#how-calls-behave)

**2026-10-21**

## Move a vendor's data into your cluster under the Launch Plan's one approval, with a rollback window

In closed beta: when you move a service into your cluster, the Launch Plan now carries its data migration. Postgres moves by dump and restore through a backup vault, and S3-compatible object storage is copied with checksums. At one cutover the vendor sources go read-only and the last changes are copied, then your app's variables switch in one change. During a rollback window, `ankra application data-migration rollback` puts everything back. Ankra never deletes data at the vendor.

[Moving your data →](/use-cases/vercel-to-ankra#moving-your-data-closed-beta)

**2026-10-21**

## The proof of a Vercel project's setup pull request is compared with Vercel's own preview

For a Vercel project, the proof run now requests the same routes on Vercel's preview of the commit as on the ankra.cc preview. It compares status, content type, JSON keys or page title and landmarks, and size. The proof card marks each route as match, differs (with the reason) or unknown. Unknown is never counted as a match, and a difference is a warning that does not fail the proof.

[Compared with your Vercel preview →](/use-cases/vercel-to-ankra#compared-with-your-vercel-preview)

**2026-10-20**

## The PR shepherd drives the pull requests Ankra opens to ready, and merges them only if you opt in

An **Ankra PR shepherd** check now follows each setup pull request. When your CI never starts, Ankra runs its own pipeline, build and proof on the head. It merges the base branch in when the pull request falls behind, resolves conflicts only in Ankra's own files, and fixes its own failures up to 3 times. It merges only where you opted in, per organisation or per application.

[The PR shepherd →](/concepts/applications#the-pr-shepherd)

**2026-10-20**

## Vercel to Ankra: one Launch Plan, one approval, and your crons and variables come along

On Vercel and GitHub pages, the Chrome extension now shows where your project stands and one Launch Plan to approve. Bring variables over from Vercel. In the setup pull request:

* A standalone Next.js build ships as just its server.
* Vercel crons become CronJobs.
* Rewrites and headers are listed with where to move them.

[Vercel to Ankra →](/use-cases/vercel-to-ankra)

**2026-10-20**

## A run handed to Ankra platform builders is now scanned, gated and published

When a cluster's agent is too old to run pipeline steps and the build goes to Ankra platform builders, its scans now run on Ankra's platform scanner instead of being skipped. The image gate judges them under the same policy, and the image is published when the gate approves. If the scanner is unavailable, the scan fails with the reason and nothing is published.

[Ankra platform builders →](/guides/ankra-pipelines#ankra-platform-builders)

**2026-10-19**

## Guided setup takes a new organisation from a free cluster to a live website

Four steps: create a free cluster, add a payment method to unlock €249 of credit for 60 days, choose the Ankra default or a new GitHub repository, then describe a website in one sentence and Ankra deploys it with a public address. Welcome credit now comes with a saved card, not at sign-up, and you are never charged without a top-up. Playgrounds are moving to Ankra Cloud dev clusters: free for 24 hours, kept with a card.

[Guided Setup →](/get-started/guided-setup)

**2026-10-19**

## New use case: self-host an AI agent observability backend from one shared stack profile

A vendor can now hand its whole backend to customers as one shared stack profile. The new use case walks a platform engineer through Moyai's: the trace API, highly available Postgres, S3, an Iceberg REST catalog, an LLM and Prometheus, applied to Proxmox, HPE Morpheus, an imported cluster or any cloud with a dry run, secret files and one deploy, then upgraded with a rollout.

[Self-host an AI agent observability backend on-prem →](/use-cases/self-host-ai-agent-observability)

**2026-10-17**

## A card is required to create resources on Ankra Cloud whatever credit you hold, and automatic top-up stays off until you turn it on

On Ankra Cloud, creating a resource now needs a card on file, whatever credit the account holds. Organisations Ankra invoices under a custom agreement need no card. Credit is still spent first, and the card pays only the rest. On the Ankra platform, saving a card does not switch automatic top-up on: you turn it on under **Billing** with your own threshold, amount and daily and monthly caps, and Billing warns you while it is not on.

[Credit and payment method →](/platform/billing#credit-and-payment-method)

**2026-10-17**

## A cancelled run now runs its finally stages before it concludes

Cancelling a run that had started now stops its main and `on_failure` stages, then runs its `finally` stages before the run concludes `cancelled`, so cleanup happens after a cancel too. This replaces the 2026-10-16 note that a cancelled run skipped them. `ankra pipeline cancel --force` skips the cleanup and concludes the run at once.

[Cancelling a run →](/guides/pipeline-reference#cancelling-a-run)

**2026-10-17**

## List and clear what Ankra's AI remembers about you from the CLI

`ankra ai memories list` shows the memories Ankra's AI has saved for you in the current organisation, newest first, and `ankra ai memories clear` deletes all of them after a confirmation. Both act on your own memories only. They need the ankra CLI v0.40.0 or later.

[AI Memory and Feedback →](/platform/ai-memory)

**2026-10-17**

## Security patches, Kubernetes patch upgrades and other routine changes are recorded as pre-approved standard changes

The audit log now marks routine changes as pre-approved standard changes for ISO 27001 change management, naming the catalogue entry and why each qualified: security-advisory add-on upgrades, Kubernetes patch upgrades, autoscaling, scheduled power actions, access expiry and token rotation. Security upgrades also name the advisories they fix in their GitOps commit. Pre-approval is on by default; admins can turn it off under **Organisation settings > Security**.

[Change Management →](/security/change-management)

**2026-10-17**

## Manage everything the CLI can create from Terraform with provider 0.3.0

The Ankra Terraform provider now covers what the Ankra CLI can create, change or delete: clusters on every cloud, managed Kubernetes, node groups, credentials, Helm registries, variables, cluster settings, alerts, DNS, applications, pipelines, stack profiles, backups, members, tokens and organisation settings. Set `project_id` on the provider if your organisation uses projects.

[Ankra Terraform Provider →](/integrations/terraform)

**2026-10-17**

## Run every stage when you need to, keep chosen stages from ever being skipped, and skip a push with \[skip ci]

Path filters can now be set aside. Run every stage with `--full` on `ankra pipeline run` or `rerun`, or add the `ankra:full-run` label to a GitHub pull request. A `full_run` block can run every push to main in full, and each full run records why. Your organisation can name stages a pull request can never filter away. A pushed commit with `[skip ci]` records a skipped run, except on the default branch by default.

[Setting path filters aside →](/guides/pipeline-reference#setting-path-filters-aside)

**2026-10-16**

## on\_failure stages now run only when a run fails, and finally stages run after a failure too

An `on_failure` stage ran after a green run and was skipped after a failed one, and a `finally` stage was skipped whenever the run failed. Now an `on_failure` stage runs only when a main stage failed, and a `finally` stage runs whatever the outcome. A run cancelled as a whole does not run its `finally` stages yet.

[Failure and cleanup stages →](/guides/pipeline-reference#failure-and-cleanup-stages)

**2026-10-14**

## Applications can refuse images that did not come from your pipeline gate

Set an application to `warn` or `enforce` and each deploy checks that its images carry a signed statement from your organisation's pipeline. Manage the mode and your signing keys in the UI or with `ankra application provenance` and `ankra org provenance`.

[Verified provenance at deploy →](/security/deploy-provenance)

**2026-10-14**

## Chat with Ankra and deploy from inside Lovable with the Chrome extension

The Ankra — Chat & Deploy extension for Chrome adds an **Ask Ankra** button to your Lovable projects. Chat with Ankra AI, connect the project's GitHub repository, and deploy it to your cluster without leaving Lovable. If your organisation has no cluster yet, it can request a temporary Playground for you. While the Chrome Web Store listing is in review, download it from ankra.ai and load it into Chrome yourself.

[Chat and deploy from inside Lovable →](/use-cases/lovable-to-ankra#chat-and-deploy-from-inside-lovable)

**2026-10-13**

## A new application's setup pull request now fixes itself when its checks fail

When the setup pull request fails its build or security checks, often on dependencies the repository already had, Ankra AI commits a fix to that same pull request and its status comment says so in plain words. Creating the application from the portal also approves the generated pipeline in your name, so the first runs are not held for an approval.

[Applications →](/concepts/applications#when-the-setup-pull-request-does-not-pass-its-checks)

**2026-10-11**

## Run your tests and lint in Ankra Workspaces instead of on your laptop

`ankra exec` runs a command for your checkout, uncommitted changes included, in a warm pod on your organisation's CI pool and streams the output back. `ankra dev install` routes the heavy commands you and your coding agents already type - `go test`, `golangci-lint`, `pnpm typecheck` - there automatically. A repository whose pipeline runs elsewhere can be connected for Workspaces only.

[Run tests and lint in Ankra Workspaces →](/guides/ankra-workspaces)

**2026-10-10**

## The merge train: every pull request is tested as it will merge

Turn on a repository's merge train and Ankra tests each queued pull request squashed onto the base branch and the pull requests ahead of it, then merges it through GitHub when that run passes. A failing pull request leaves the train and the rest are retested without it. Every merge is a tree a run already passed, so `promote_from: pull_request` publishes the tested image instead of rebuilding. GitHub only.

[The merge train →](/guides/ankra-pipelines#the-merge-train-test-every-pull-request-as-it-will-merge)

**2026-10-09**

## A repository Ankra cannot build no longer gets a setup pull request

Setup now stops before the pull request when a repository holds nothing that keeps running, or no Dockerfile that Ankra found or could write. It used to open a pull request that could never deploy a working application. The setup ends as failed, its message says what Ankra found and what to add, and it ends: No setup pull request was opened and nothing was deployed.

[How it works →](/concepts/applications#how-it-works)

**2026-10-09**

## Promote a pull request's tested image instead of rebuilding on merge

A publish stage can now declare `promote_from: pull_request`. When a merge carries exactly the files a pull request run already built, scanned, gated and tested, the merge publishes that run's approved image as its own `sha-<7>` tag instead of building and testing it again. Any other merge builds in full as before, and the run says why.

[Promote a tested image instead of rebuilding →](/guides/pipeline-reference#promote-a-tested-image-instead-of-rebuilding)

**2026-10-09**

## Pipeline steps record what they used, and each stage gets a resource suggestion

Every step now records its memory peak and CPU use next to what it asked for, so a stage that declares 14Gi and peaks at 8 GiB shows on the run itself. The API suggests `resources.memory` and `resources.cpu` per stage from its latest successful runs, and says how many runs each suggestion rests on. Suggestions are advice only: your pipeline changes only if you change it.

[Capacity and concurrency →](/guides/ankra-pipelines#capacity-and-concurrency)

**2026-10-09**

## Acknowledge or accept findings no add-on owns, per workload or per image

A disposition needed a finding attributed to an add-on, so findings in operator-managed database pods, plain manifests, control-plane pods and charts outside the catalogue could never be acknowledged or accepted. `ankra security dispositions preview|create --scope workload` pins the decision to one workload, and `--scope image` to an image digest wherever it runs. The same `scope` works from the API and the MCP tools.

[What a disposition is pinned to →](/guides/cluster-security#what-a-disposition-is-pinned-to)

**2026-10-09**

## Generated pipelines keep their package caches between runs

A new application's generated test stage now keeps its package caches: npm, pnpm or Yarn, Go modules and builds, pip, uv, Poetry or Pipenv, and cargo. Each is keyed on the lock file and saved only after the step passes. A pull request starts warm from the default branch and never writes into it. `fallback: none` keeps a cache off shared volumes on older agents.

[Caches →](/guides/pipeline-reference#caches)

**2026-10-09**

## UpCloud node groups: a plan from another family replaces the nodes instead of stranding them

UpCloud changes a server's plan in place only within its plan family, so resizing a STARTER group to a general-purpose plan such as `4xCPU-8GB` was refused after each node had been stopped, and the retries left the nodes off. A cross-family change now replaces each node with the new plan and the resize says so, a control-plane change across families is refused up front, and a server whose in-place resize fails is powered back on.

[Node groups →](/platform/cluster-nodes#node-groups)

**2026-10-09**

## Run every pipeline pod on a dedicated node group

`ankra cluster agent ci set --node-group pipelines` puts every pipeline pod of the CI cluster on that node group: step pods, their cache and artifact helpers, and image builds select its nodes and tolerate its taints, with no pipeline change and no Kyverno policy. The portal's Pipelines settings page edits the placement, the CI slots and the storage class.

[Step placement →](/guides/ankra-pipelines#step-placement)

**2026-10-08**

## Ankra Cloud dev clusters: Kubernetes on one server

Ankra Cloud Kubernetes can create a dev cluster: one server running k3s that is the control plane, the only node and its own network edge. It has no control-plane fee, so you pay for the server. It has no high availability and is not for production. Pick **Dev cluster on one server** in **Create Cluster**, or pass `--dev-cluster` to `ankra cluster managed create` (CLI v0.24.0). It is offered zone by zone, and Ankra Cloud is in closed beta.

[Dev clusters →](/guides/ankra-cloud-kubernetes#dev-clusters)

**2026-10-08**

## Path filters per event: check a pull request's component, build everything on push

A stage's `when` can name its event: `when.pull_request.paths` filters pull requests, `push: {}` leaves pushes unfiltered, so a monorepo needs one stage per component, not duplicates. A stage whose `if:` calls `always()` or `skipped()` now runs past a skipped need. Converted workflows keep their own pull request paths, and `ankra pipeline validate --changed-file` prints each stage against each event.

[Event-scoped filters →](/guides/pipeline-reference#event-scoped-filters)

**2026-10-08**

## Pull request runs apply their path filters to the files the pull request changes

A pull request run had no list of changed files, so every `when.paths` filter passed and every stage ran. Ankra now reads the changed files from GitHub, GitLab or Bitbucket, up to 300, and keeps them on the run for dispatch and re-runs. A list it cannot read in full never skips a stage, and the run's `paths_unverified` says why.

[How path filters decide →](/guides/pipeline-reference#triggers)

**2026-10-08**

## Every sign-in is bound to the browser that started it

Every sign-in - password, social account, your organisation's single sign-on provider or an invitation link - now ties the identity provider's answer to the browser that asked for it, with OpenID Connect `state`, `nonce` and PKCE. A response this browser did not start is never completed; the sign-in restarts once instead. Connecting another sign-in method is bound the same way. Day to day nothing changes: if a long-idle tab lands on "sign in again", signing in once more completes it.

[Sign-in and SSO →](/security/identity-and-access#sign-in-and-sso)

**2026-10-08**

## See what your organisation used of Ankra, meter by meter

One usage report covers worker vCPU-hours, playgrounds, managed service time and storage, Ankra hosted logs and metrics, and AI, per month or day, split by cluster, application or managed service. Each line says how completely it was measured - a period nobody measured reads as not measured, never 0 - and what it costs. Managed services and hosted logs and metrics are included during the pilot. Read it through the API, the AI Assistant or `ankra org usage` (CLI v0.27.0).

[Usage →](/platform/usage)

**2026-10-08**

## Steps of a run stay on the node their workspace is attached to

Each step of a run, and its cache and artifact helpers, now runs on the node its `rwo` workspace is attached to, so sequential steps no longer wait for the volume to move. When that node is gone, cordoned or not Ready, the step log says why the pin was dropped. Helpers also carry the step's tolerations, so caches restore on a tainted node group. `ankra pipeline get` shows where each step ran.

[Workspace access →](/guides/pipeline-reference#top-level-keys)

**2026-10-08**

## A step says whether its caches restored, and why not

A step's cache result is now `hit` only when every cache restored, `partial` when some did, and `restore_failed` when a restore broke, each cache carrying a reason such as `download_failed`. `ankra pipeline get` shows it in a CACHE column, `--step <key>` prints the per-cache table, and the run timeline shows a chip. Where a step's network allows it, the restore runs inside the step's own pod.

[What a step reports about its caches →](/guides/pipeline-reference#what-a-step-reports-about-its-caches)

**2026-10-08**

## Ankra Cloud Kubernetes: development and production control planes

An Ankra Cloud Kubernetes cluster now has a control plane you choose at create. **Production** runs three replicas, is highly available and costs €40 a month per cluster. **Development** runs one replica and has no control-plane fee, so you pay for the nodes only. It is not for production: an upgrade or a host node failure interrupts the Kubernetes API while it restarts. The choice cannot be changed afterwards.

[Choosing a control plane →](/guides/ankra-cloud-kubernetes#choosing-a-control-plane)

**2026-10-07**

## A publish stage can give the published image extra tags, such as latest

`kind: publish` takes a `publish.tags` list: each entry becomes another tag on the digest the gate approved, in the application's repository, with no second push - a moving `latest`, or `"0.2.${{ ankra.run.number }}"`. Expressions resolve when the run is planned, the stage's `when:` applies, and a tag the registry refuses fails the step by name.

[The publish block →](/guides/pipeline-reference#kind-specific-blocks)

**2026-10-07**

## A declared registry project that does not exist is created, or the declaration is refused

`ankra application registry set` with `--admin-credential` now checks that the declared project exists on your registry. A missing project is created with that credential - private, or public with `--project-public` - when it may create projects; otherwise the declaration is refused naming the project and host, instead of every later build failing at the push.

[Have the project, or let Ankra create it →](/guides/harbor-registry#what-harbor-needs-first)

**2026-10-07**

## Create registry robots on a Harbor you run yourself

The **Registry robots** page and `ankra registry robots create` can now create a robot on a Harbor your organisation runs and has connected as an OCI registry. Pick the registry, a credential of yours that may manage robots there, and one of that registry's projects, such as `collectorcharts`: the robot reaches only that project. Ankra acts only with your credential.

[Robots on a Harbor you run yourself →](/guides/harbor-registry#robots-on-a-harbor-you-run-yourself)

**2026-10-06**

## Protecting a CloudNativePG stack now backs it up

Protecting a stack with a CloudNativePG cluster never gave the `Cluster` its barman-cloud archiver, so every restore point failed with "the cluster has no plugin configured". Protecting the stack, or taking a restore point by hand, now wires the archiver and its object store into the stack, and unprotecting removes both. Wiring it restarts the instances one at a time; a scheduled backup never does, and skips a stack that is not wired yet.

[Protect a stack →](/guides/backups#protect-a-stack)

**2026-10-05**

## Cluster groups on environment follow each cluster's Environment

A dynamic cluster group on `environment` now matches the **Environment** set on each cluster. Before, it matched a copy taken when cluster groups launched, so a group on `environment` = `production` missed clusters created or moved to production since then, and kept a cluster moved out of production. Roles assigned over the group, and the Kubernetes access they bundle, now follow a cluster's environment: platform permissions within about a minute, Kubernetes access within about 90 seconds.

[Restrict production to a DevOps role →](/guides/roles-and-access#example-restrict-production-to-a-devops-role)

**2026-10-04**

## Tag runs no longer use shared pipeline caches

A pipeline run triggered by a tag, or a rerun of one, now starts with empty cache volumes. Before, it shared a cache scope with feature branches and pull requests, so a release could start from files another branch's run left behind. The step reports `cache_result: disabled`. Other runs keep their caches, and a tag run takes as long as a run with a cold cache.

[How a stage's cache is scoped →](/guides/pipeline-reference#fields-common-to-every-stage)

**2026-10-04**

## One component can build both an image and a release bundle

Declare `build.component` on a build stage to name the component it belongs to, so `build-portal-image` can build portal's image beside a `build-portal` release bundle. A component's bundle now publishes to its own `<component>-bundle` repository, so the image and the bundle no longer overwrite each other's commit tag. `ankra pipeline validate` reports a stage that belongs to no component before a run.

[Which component a build belongs to →](/guides/ankra-pipelines#which-component-a-build-belongs-to)

**2026-10-02**

## See pipeline capacity live, and steps waiting for a CI slot no longer burn their timeout

The Pipelines settings page shows your CI slots, steps in flight and queued runs, and edits the parallel run and step limits. The run limit now defaults to 16. A queued run can say it is waiting for a CI slot, a step's timeout and duration start when it begins, and steps show their queue wait. Current agents change slot counts live, up to 128, without a restart.

[Capacity and concurrency →](/guides/ankra-pipelines#capacity-and-concurrency)

**2026-10-02**

## Extra registry projects, and robot accounts bound to the one you pick

Everything an organisation publishes lands in one registry project, so every robot account could reach all of it. You can now create up to five extra projects with `ankra registry projects create` or from the **Registry robots** page, push the images you want kept apart there, and bind a robot account to that project alone with `--project`. A robot reaches the one project it is bound to and nothing else.

[Scoping a robot to one project →](/guides/harbor-registry#scoping-a-robot-to-one-project)

**2026-10-01**

## Secret value digests can no longer be used to check a guessed value

Without the reveal permission you see each Secret value as a digest, which shows that a value changed. That digest used to be an unkeyed SHA-256 prefix anyone could compare against guesses. It is now keyed per cluster with a key only the platform holds, so it cannot be used to check a guessed value. The AI assistant also finds Secrets only by name, namespace and labels, never by their stored content.

[Configs →](/platform/kubernetes-insights#configs)

**2026-10-01**

## Helm release values and kubectl Secret reads need the Secret reveal permission

A Helm release now hides the passwords, tokens and keys in its values, rendered Secrets and notes until a member with `kubernetes.secrets_reveal` clicks **Reveal values**. An upgrade that still carries a hidden placeholder is refused.

`kubectl` through Ankra refuses Secret requests from members without the permission, whatever their access grant. Every Helm reveal and every Secret request it lets through is written to the audit log.

[Secrets need their own permission →](/guides/cluster-access#secrets-need-their-own-permission)

**2026-10-01**

## The Teams claim code is sent in a private chat and no longer changes while you use it

When **Ankra AI** is added to a team or group chat, it now sends the claim code that connects your Microsoft tenant to the person who added it in a private chat, instead of posting it in the channel. The welcome card shows when the code expires, and messaging the bot again returns the same code until it is close to expiry, so a colleague talking to the bot no longer invalidates the code an admin is about to redeem.

[Connecting Microsoft Teams →](/platform/ai-connections#connecting-microsoft-teams)

**2026-10-01**

## The cost estimate prices GPU node groups, starting with UpCloud

The what-if draft and **Compare providers** now price GPU node groups. Each group has a **GPUs** field, a GPU group is placed only on a GPU size, and every UpCloud GPU plan can be priced, spot plans included. Providers with no GPU sizes in the price book show the group as not priced instead of quoting a CPU size. The cluster cost card no longer prices UpCloud B200, RTX PRO 6000 and GPU spot nodes at zero.

[What if the node groups changed? →](/platform/cloud-cost#what-if-the-node-groups-changed)

**2026-10-01**

## Connect your own identity provider for single sign-on, with nothing to request from Ankra

An owner or admin can now connect the organisation's own OpenID Connect provider - Microsoft Entra ID, Okta or any other - under **Organisation** → **Settings** → **Single sign-on**. The provider decides who is a member and, through group mappings, which role they hold. A member it stops admitting is suspended at the end of the re-verification window, 24 hours by default, which stops their sessions, API tokens and Kubernetes access together.

[Single Sign-On →](/guides/single-sign-on)

**2026-10-01**

## The Credentials page fills the window, and its empty states lead somewhere

The **Credentials** page now fits the window: the title and the search, filter and sort row stay in place while the cards scroll. With no credentials yet, the page says what they are for and offers a shortcut to each kind (source control, cloud providers, container registries, access keys), opening the provider list at that group. A search or filter that matches nothing offers **Clear filters**.

[Credentials →](/platform/credentials#view-credentials)

**2026-10-01**

## Registry robots list Ankra's own robots, and yours can hold exact permissions and expire

The **Registry robots** page and `ankra registry robots list` now show every login your registry project honours: the ones you created and the ones Ankra manages (`ci`, `pull`, one per application), read-only. A robot you create can hold exactly the permissions a job needs, such as deleting artifacts or moving tags, instead of push or pull, and can be set to expire. Each robot names the one project it is bound to.

[Robot accounts you create yourself →](/guides/harbor-registry#robot-accounts-you-create-yourself)

**2026-10-01**

## Invitations can be accepted by people who sign in with Microsoft

Someone invited to an organisation who signed in with Microsoft was told their email address was not verified, with no way to verify it. The link in the invitation email now confirms the address when they open it and sign in, so the invitation can be accepted. An invitation sent before this change needs a resend from **Organisation → Members** to carry the new link, and a resend retires any link mailed earlier.

[Roles and access →](/guides/roles-and-access)

**2026-10-01**

## Reading a Kubernetes Secret's values needs its own permission and is audited

Opening a Secret in Ankra now shows its key names only. To see the values, click **Reveal values**: that needs the new `kubernetes.secrets_reveal` permission, which `owner`, `admin` and `operator` hold and `member` and `viewer` do not, and each reveal is written to the audit log. The API follows the same rule, and the AI never sees the values. Custom roles that held `kubernetes.write` were given the new permission.

[Kubernetes Resources →](/platform/kubernetes-insights#configs)

**2026-10-01**

## Pipeline steps reserve half their CPU, so more of a run fits on one node

A step used to reserve the whole CPU figure its stage declared. A run's steps share one node, so that node filled up and the rest of the run waited, whatever the cluster's node count. A step now reserves half of its `resources.cpu` (at least 100m) and can still use all of it while the node has CPU free. Memory is reserved in full, as before. Nothing in a pipeline definition changes.

[Capacity and concurrency →](/guides/ankra-pipelines#capacity-and-concurrency)

**2026-10-01**

## Creates and scale-ups that a cluster's pod range cannot hold are refused up front

A cluster Ankra builds holds at most 64 nodes with the default network ranges. A create, a node group change or an autoscaler scale-up that would go past that is now refused with a message naming the range and the limit, instead of adding nodes that join and never become Ready.

[Network ranges and their limits →](/platform/cluster-mesh#network-ranges-and-their-limits)

**2026-10-01**

## Ankra's builders run at most three builds per organisation at a time

The builder pool is shared by every organisation. One organisation's burst of builds now waits its turn after three instead of holding every builder, so another organisation's build starts without waiting for it.

[Waiting for a builder →](/concepts/applications#waiting-for-a-builder)

**2026-09-30**

## Applications are available to every organisation

Applications are out of closed beta and on for every organisation, with nothing to request. Connect a GitHub repository and Ankra generates the Dockerfile, chart and pipeline, builds the image, and deploys it. Pull request previews, branch demos, the application registry, publishing an application as an add-on, builds on Ankra's own builders and the Claude Design import come with it.

[Applications →](/concepts/applications)

**2026-09-30**

## Self-managed AWS clusters are available to every organisation

Ankra-built k3s and kubeadm clusters on EC2 are out of closed beta. Every organisation now sees AWS EC2 next to Amazon EKS in the create-cluster dialog, and the `ankra cluster aws` commands and the AWS cluster endpoints are served for everyone.

[AWS clusters →](/guides/aws-clusters)

**2026-09-30**

## The AI section is available to every organisation

The **AI** section of the sidebar is out of closed beta: Home, Board, Chat, Inbox, Automations, AI Agents and Settings are on for every organisation. That brings the AI board and its agents, automations, AI code review, Slack and Teams connections, ticket sync, and chat autonomy, where low-risk writes can run without a confirmation once you pick **Auto**.

[Ankra AI overview →](/platform/ai-overview)

**2026-09-30**

## Cluster Mesh and multi-zone UpCloud clusters are available to every organisation

Cluster Mesh and the WireGuard overlay it runs on are out of closed beta. Any organisation can join its clusters into one mesh, and stretch an UpCloud cluster across a pool of zones. New Ankra-built clusters get a network identity from the organisation's pools, so they can join a mesh later.

[Cluster Mesh →](/platform/cluster-mesh)

**2026-09-30**

## Cloning a stack with its data is available to every organisation

Cloning with data is out of closed beta. The clone dialog's **Data** step and `--with-data` carry a stack's volumes and database contents to the target through a backup vault, for every organisation.

[Clone a stack →](/guides/clone-stack)

**2026-09-30**

## Log sources are available to every organisation

Log sources are out of closed beta. Any organisation can connect a cluster to Loki, Elasticsearch or OpenSearch under **Settings** → **Integrations**, search them from the **Search** tab on the cluster's **Logs** page, and let Ankra's AI query them. **Log Source** is no longer marked **Coming soon**.

[Log sources →](/integrations/log-sources)

**2026-09-30**

## The organisation audit log can be exported with an API token, so SIEM forwarding can run on a schedule

The audit-log export only accepted a signed-in browser session, so a scheduled job holding a token was redirected to the sign-in page. `GET /api/v1/org/organisation/audit-logs/export` now takes a service token or personal API token holding `audit.read`, with the same filters, CSV and JSON formats and 100,000-row cap as the portal download.

[Forwarding to a SIEM →](/security/audit-export#forwarding-to-a-siem)

**2026-09-30**

## MCP clients hand you portal links

The Ankra MCP server now tells clients to give you a link to the portal page for what they are describing. `list_clusters` and `get_cluster_details` return each cluster's `portal_url`, and the new read-only `get_portal_url` tool returns the address of any other page - a stack, an add-on, a pod, an application, a pipeline run, a ticket, an alert or a CVE - opening in the right organisation. A new Portal URLs page lists every page and how its address is built.

[Portal URLs →](/platform/portal-urls)

**2026-09-29**

## Bitbucket Cloud pull requests reach Ankra AI review, mention replies and pipelines

Ankra's Bitbucket webhooks subscribed to pushes only, so reviews, `@ankraai` replies and pull request pipelines never started. Webhooks now carry pull request events and are registered for repositories with AI review on or connected to Ankra Pipelines. Drafts are honoured, replies thread under the question, and `event.provider` reads `bitbucket`, as documented. Reconnect each Bitbucket credential to grant the new pull request permission; until then, GitOps sync keeps working.

[Grant the pull request permission →](/integrations/bitbucket-cloud#granting-the-pull-request-permission)

**2026-09-29**

## Connecting Bitbucket Cloud works end to end again

Repository lists froze once Atlassian removed the workspace listing Ankra read, and GitOps settings could not save a Bitbucket repository. Both work again, with a branch picker. Organisation credentials can be deleted, their webhooks removed first; tokens refresh before they expire; a connection must be finished by the Ankra user who started it; and **View source** opens on bitbucket.org.

[Bitbucket Cloud →](/integrations/bitbucket-cloud)

**2026-09-29**

## `ankra cluster exec` runs one command in a pod and exits with its exit code

`ankra cluster exec <pod> -n <namespace> -- <command> [args...]` runs one command in a pod - a `psql -c`, a `curl` to localhost, reading a mounted file - and exits with its exit code, so scripts and CI can branch on it. The command reaches the container exactly as given, its output streams as it runs, and every run is audited like a terminal session. It needs CLI 0.20.0 and cluster agent 2.1.1166 or newer.

[One-off commands →](/platform/pod-terminal#one-off-commands)

**2026-09-29**

## Ankra Cloud is a cluster provider, managed and self-managed

The create-cluster dialog offers Ankra Cloud two ways. **Ankra Cloud Kubernetes** is a control plane the Ankra team runs, with node pools, autoscaling and upgrades driven from Ankra. **Ankra Cloud** builds kubeadm or k3s on Ankra Cloud servers behind a bastion and a NAT router, with the cloud controller and CSI driver deployed for you. One Ankra Cloud credential serves both. It is in closed beta, enabled per organisation on request.

[Ankra Cloud Clusters →](/guides/ankra-cloud-clusters)

**2026-09-29**

## Domains you hold in Avura can serve your clusters and root their generated domains

Connect an Avura workspace to its Ankra organisation from Avura, then share domains one at a time. A shared domain can be added as a custom DNS zone with no credential of your own, its records are edited under Settings > Avura, and it can be the Custom Ankra domain without delegating it to Ankra's nameservers. Ankra sees only the domains you share, and disconnecting is refused while anything still uses them.

[Use Avura domains with Ankra →](/guides/avura-domains)

**2026-09-28**

## A restore point you take by hand is kept, and a restore stays undoable for a week

A second **Back up now** in one afternoon used to expire the first within minutes, and with it the safety restore point taken before an in-place restore. Retention now counts only scheduled restore points: one you take yourself is kept for the policy's longest period, and a safety restore point for seven days. The Backups tab also names each restore point and says whether it can still be restored.

[Protect a stack →](/guides/backups#protect-a-stack)

**2026-09-28**

## Deleting a cluster names its persistent volumes and deletes them only once you accept it

A plain delete of a Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway or AWS cluster left its CSI volumes billing, and only `--force` deleted them, silently. Every delete now lists the volumes and deletes them, forced or not, once you accept it: a checkbox in the dashboard, a prompt or `--accept-volume-data-loss` in the CLI, `accept_volume_data_loss` on the API. A `retain` retention policy keeps them.

[Persistent volumes →](/platform/cluster-settings#persistent-volumes)

**2026-09-28**

## A forced stop keeps your volumes; only a deprovision deletes them

A stop with `--force` deleted the cluster's CSI volumes on DigitalOcean, UpCloud, OVH, Hetzner, AWS and Scaleway, although a stop is reversible and a start expects its persistent volumes to still be there. A forced stop now cancels in-flight work, tolerates unreachable infrastructure and removes load balancers as before, but keeps every volume. They keep billing while the cluster is stopped; a deprovision deletes them once you accept it.

[Stopping and starting a cluster →](/guides/upcloud-clusters#stopping-and-starting-a-cluster)

**2026-09-22**

## A stack profile version can be deprecated, and nothing deploys it again

A published version could only ever be superseded. When one turns out to be incompatible, to carry a critical bug or to ship a CVE, the owner can now deprecate it - from the History tab or `ankra stack-profiles deprecate` - with a reason, a note and the advisories behind it. Every launch, rollout and update then refuses it with that reason, and deployments still on it are flagged. The current version cannot be deprecated; `undeprecate` restores one.

[Deprecate a version →](/concepts/stack-profiles#deprecate-a-version)

**2026-09-21**

## Backup Vaults and stack restore points are available to every organisation

Backups are out of closed beta and on for every organisation, with nothing to request. Register or provision a backup vault, protect a stack on a schedule, take restore points and restore a stack in place from the portal, the CLI and the API; `ankra migrate` moves its data through the same vaults. Cloning a stack with its data stays in closed beta, enabled per organisation on request.

[Backups and restore points →](/guides/backups)

**2026-09-20**

## Using a stack profile is a page, not a dialog

A profile with two dozen inputs never fitted the dialog **Use Profile** opened. It now opens a page: the destination and the inputs take the main column, and a summary beside them stays in view while you scroll, with a checklist that ticks off as the form fills in and the **Create draft** button. A History version, a deployment update and the application wizard all land there with cluster and version already chosen.

[Instantiate a profile →](/concepts/stack-profiles#instantiate-a-profile)

**2026-09-19**

## A managed node pool can be handed to your own autoscaler, and Ankra refuses to change it

Ankra never changed a managed pool's node count on its own, but a scale, a size replacement or a delete could still override a count your own cluster autoscaler had reached. A pool marked `externally_managed` now refuses every one of those from the portal, the CLI, the API and Ankra AI until the flag is cleared, and the pool listing shows the live count from the provider next to the last count Ankra wrote.

[Externally managed node pools →](/guides/managed-kubernetes#externally-managed-node-pools)

**2026-09-19**

Also shipped this week

**Build context** - a `build` stage with a `context` and no `dockerfile` builds that context's own Dockerfile, and a build refused before it starts says why. [→](/guides/ankra-pipelines)

**Semgrep pack** - a generated scan stage leaves out the GitHub Actions pack once Ankra has confirmed your repository commits no GitHub Actions workflow. [→](/guides/ankra-pipelines)

**2026-09-17**

## Merge when green has an on/off switch per GitHub installation

Merge when green shipped with no control. Each GitHub installation's row now carries a **Merge when green** switch beside its AI mode, for organisation admins, and the same switch is `merge_when_green` on the binding profile, writable with a personal access token through `PUT /api/v1/org/ai-gateway/scm-bindings/{provider}/{binding_external_id}`. A request is honoured only in Agent mode, and with the switch on a `Depends-on:` line holds a pull request's merge behind the one it names.

[Merge when green →](/integrations/github#merge-when-green)

**2026-09-17**

## The pull request review reads the other half of a cross-repository change

The cross-repository pass read default branches only, so it missed a client fix still open in the other repository, and it fired only on removals. The review now reads companion pull requests - a `Depends-on:` line, or any linked pull request in a related repository - and shows each on its own branch, with state, head and diff. Changed contracts are searched alongside removals. `@ankraai` replies see the same companions.

[The other half of the change →](/platform/ai-code-review#the-other-half-of-the-change)

**2026-09-16**

## Stopping a cluster keeps its state, and control planes grow without a stop

On Hetzner, OVHcloud, UpCloud and DigitalOcean a stop used to lose everything stored in the cluster itself, and StatefulSets came back on empty disks. Stop now captures an encrypted snapshot of the cluster's state before the machines go, and the next start restores it, so workloads return with their Secrets and reattach their disks. Adding control planes no longer needs a stop either; the docs page explains what is kept and how to opt out.

[Stop cluster](/platform/cluster-settings#stop-cluster)

**2026-09-15**

## Cluster Mesh no longer moves a running cluster onto a new pod range, a move that crashed its controller manager

`make-ready --pod-cidr` no longer moves a running cluster onto another pod range: that move crashed kube-controller-manager, which exits at start while any node holds a range outside `--cluster-cidr`. The request is now refused by name. `--pod-cidr 10.244.0.0/16` still puts a cluster an earlier move split back onto the range its nodes run. Two clusters sharing the kubeadm default pod range cannot mesh until the move is redesigned.

[Moving a cluster onto a fresh pod range →](/platform/cluster-mesh#moving-a-cluster-onto-a-fresh-pod-range)

**2026-09-15**

## An application opens as a workspace, and its Security section ranks findings by exploitability

An application now opens as a workspace: Overview, Pipelines, Deployments, Previews, Security, Environment, Source & config and Settings, each its own page, with `?tab=` links redirecting. Demos are called Previews. Security ranks findings by CISA KEV, then EPSS, then severity, with a Known exploited filter and a sheet per finding carrying CVSS, EPSS, CISA's deadline and required action, the fix and the advisory. Exploitability reads Unknown until the catalog has synced. The Applications list gains a Needs attention filter.

[The application workspace →](/concepts/applications#the-application-workspace)

**2026-09-15**

## A stack profile carries its backup policy, so a fleet launch protects every instance

Saving a protected stack as a profile now keeps its protection. The builder shows a **Protection** section - whether to protect, which backup vault, how often - and the vault travels by name, resolved against the organisation you launch into, so one profile protects a whole fleet. A launch with no ready vault says so and keeps the draft rather than starting a stateful stack unprotected. Public profiles carry no vault name.

[Protection: backups travel with the profile →](/concepts/stack-profiles#protection-backups-travel-with-the-profile)

**2026-09-15**

## Ankra says when a branch's runs are queueing behind each other

A `concurrency.group` that varies per branch with no `cancel_in_progress` makes a new commit's run wait for the run it replaces. `ankra pipeline validate` now says so as advice - never blocking, never failing the command - naming the group and the line that changes it. A queued run's waiting reason carries the same recommendation when it is stuck behind its own branch, and a converted GitHub workflow gets a conversion note. Your existing definitions keep their behaviour.

[Newest commit wins →](/guides/ankra-pipelines#newest-commit-wins)

**2026-09-15**

## Protect a stack, take restore points, and restore it in place

Protecting a stack schedules its databases and named volumes into a backup vault you own, and installs the backup data plane. Take a restore point whenever you like, read what it carries and what it could not, then restore the stack in place behind a typed confirmation. `ankra runs` follows every capture and restore, and a protection pill now says where data is exposed. CloudNativePG and Percona restore in place is not available yet.

[Backups and restore points →](/guides/backups)

**2026-09-14**

## A generated pipeline is checked against your repository, so a missing Dockerfile shows up before you merge

Ankra now checks a generated `.ankra/pipeline.yaml` against your repository before proposing it, not only against the pipeline grammar. Each `build` stage's Dockerfile is resolved the way the builder resolves it and looked for in your branch plus the files the same run commits. Findings name the stage and appear on the setup run, so nothing is discovered by a push that fails after you merge.

[Ankra Pipelines →](/guides/ankra-pipelines)

**2026-09-14**

## Generated test stages run your project's own commands

A generated test stage now follows the lock file your component commits. A `uv.lock` project runs `uv sync --locked && uv run pytest`; `pnpm-lock.yaml` and `yarn.lock` run pnpm and Yarn with a frozen lockfile instead of npm. Go components each get their own `GOCACHE` and `GOTMPDIR` inside the workspace, and a monorepo's workspace is sized by its component count.

[Ankra Pipelines →](/guides/ankra-pipelines)

**2026-09-14**

## Convert an application from its GitHub workflow to Ankra Pipelines with one click

An application still building from a GitHub Actions workflow now shows **Convert to Ankra Pipelines** on its journey card and **Convert** in the Applications list; `ankra application pipeline convert <application-id>` does the same. The click takes effect at once: Ankra stores the converted pipeline, builds the next push through it, switches the generated workflow off on GitHub, and opens a pull request that commits the pipeline file and removes the workflow.

[Migrate an existing application with one call →](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call)

**2026-09-14**

## Protect a stack with a backup block in the cluster file

A stack can now declare its own backup policy in the cluster file, and Ankra takes the scheduled restore points from it. Databases are captured by default; volumes only the ones you name, so protecting a stack does not start copying every claim in its namespaces. A file that omits the block leaves protection exactly as it was, and an apply that narrows protection says what stops being covered. Closed beta, enabled per organisation.

[Protect a stack →](/guides/backups#protect-a-stack)

**2026-09-14**

## Hetzner clusters are priced from Hetzner's live price list

Cloud Cost now reads Hetzner's price list every hour with your stored Hetzner credential and prices each server type, load balancer, IPv4 and volume per location, instead of from a built-in copy that predated Hetzner's June 2026 increase. A server ordered before that increase keeps the list it was ordered under, matching the two rates your invoice shows for the same type. Estimates read `medium` confidence, not `high`, when no live list could be fetched.

[Where the prices come from →](/platform/cloud-cost#where-the-prices-come-from)

**2026-09-14**

## UpCloud clusters built before the mesh overlay can now join a Cluster Mesh

`make-ready` now joins an existing UpCloud node to the WireGuard overlay from its update job, so a cluster built before the overlay converges instead of looping. Service ranges may overlap across members; a second cluster on the default pod range is refused by name until `--pod-cidr auto` moves it onto a fresh range, one node at a time. `ankra cluster mesh up` runs readiness, make-ready and the joins for a set of clusters in one command.

[Make an existing cluster mesh-capable →](/platform/cluster-mesh#make-an-existing-cluster-mesh-capable)

**2026-09-14**

## Create your own robot accounts on the Ankra registry

Ankra minted every registry login itself. You can now create robots of your own for anything that logs in without Ankra in the loop - CI you run, a laptop, a cluster Ankra does not manage. `ankra registry robots create <name>`, the **Registry robots** page, or the API mints one with **push** or **pull** rights on your project and shows its secret once; list, rotate and revoke it the same way, and reference its managed credential `ankra-harbor-robot-<name>` anywhere.

[Robot accounts you create yourself →](/guides/harbor-registry#robot-accounts-you-create-yourself)

**2026-09-14**

## An application that already builds no longer tells you to merge its setup pull request

The Applications list and the application journey no longer say **Merge the setup pull request to go live** once your application builds on an Ankra pipeline or on your own workflow: that pull request only proposes committing Ankra's generated files. A push now also re-checks a setup pull request still recorded open against GitHub, and an application whose pipeline Ankra stores and runs is recorded as building on Ankra Pipelines. **Reconcile** moves an existing application over.

[Ankra Pipelines →](/guides/ankra-pipelines)

**2026-09-12**

## Stack READMEs, code review and background runs follow your model settings

Stack README generation, AI code review with no model picked, and background agent runs now follow your organisation's model settings instead of a fixed Claude model, defaulting to the **Think** tier: GLM 5.2 on the Ankra provider. **Stack README** and **AI code review** each get their own setting, and only admins can change a function's model. Chat on the default models now counts against the free monthly AI allowance.

[Models per function →](/platform/ai-provider#models-per-function)

**2026-09-12**

Also shipped this week

**Pipeline commands** - `ankra pipeline run` and `list` take the application and commit from the checkout you are in, and say which. [→](/guides/ankra-pipelines)

**Adding an application** - `ankra application add --wait` follows the analysis and prints the setup pull request's link, or why it failed. [→](/get-started/quickstart)

**Unreachable repositories** - adding an application checks only the repository you add, so one the GitHub App cannot reach elsewhere no longer blocks it. [→](/integrations/github)

**Credential health** - `ankra credentials get` says whether Ankra can use a credential and, for an unusable GitHub one, why. [→](/integrations/github)

**2026-09-11**

## Self-managed k3s clusters on AWS EC2

Ankra now builds self-managed k3s or kubeadm clusters on EC2: a VPC across one or three zones with NAT egress (or a VPC you adopt), a bastion, nodes in private subnets with no public IP, the AWS cloud controller and EBS CSI driver on instance profiles, a Network Load Balancer for Traefik, stop and start, node groups, upgrades and teardown with a retention policy. The provisioning credential covers it. Closed beta, enabled per organisation on request.

[AWS clusters →](/guides/aws-clusters)

**2026-09-11**

## Cluster Mesh says up front when a cluster can never join, and retries a member whose setup stalled

A cluster created with networking off has no Cilium release the platform manages, so a mesh could never reach it. Readiness now says so under a new `cilium_stack` check, and the join and make-ready refuse it instead of leaving the member in `configuring`. A member whose trust-root job never ran, or never reported, is re-dispatched by the mesh reconciler after fifteen minutes rather than waiting for a peer change that never comes.

[Cluster Mesh requirements →](/platform/cluster-mesh#requirements)

**2026-09-11**

## Update a stack to a newer profile version in place

A deployment behind its profile used to be updated by instantiating the profile again, which produced a second stack renamed around the name collision. **Update** on the profile's Deployments tab now replaces the contents of the stack that deployment already runs, in place, so Kubernetes rolls the workloads, and records the deployment at the new version - so the "behind" counters follow. Non-secret inputs are carried forward; secret inputs are asked for again.

[Versioning, diffing, and updates →](/concepts/stack-profiles#versioning-diffing-and-updates)

**2026-09-10**

## Cloned stacks deploy on their own; the ones missing secrets say what they need

Cloning a stack or a whole cluster no longer leaves a row of drafts to open and deploy one by one. **Deploy after cloning** is on by default and deploys every clone that has what it needs. A stack whose encrypted values had to be removed is held as a draft marked **Needs input**, and the clone result, the stack card and the builder name each member and field to re-enter, with a link straight to it.

[Clone a cluster →](/guides/clone-cluster#stacks-that-need-your-input)

**2026-09-10**

## Clone a cluster onto a different cloud provider

**Clone Cluster** can now build the copy on a cloud provider instead of an import cluster. Choose **Build on a cloud provider**, pick Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE or HPE Morpheus, and finish on that provider's create page: the cluster is provisioned and every source stack lands on it as a draft. Stacks the provider installs itself - cloud controller, networking, DNS, Cilium - are skipped and reported. The API takes `target_provider` and `target`.

[Clone a cluster →](/guides/clone-cluster#clone-a-whole-cluster)

**2026-09-09**

## Import a Claude Design export as an application

A canvas exported from Claude Design - artboards, `canvas.json` and images, a zip, or a saved canvas page - becomes a deployable application in one step: Ankra turns it into a static site, creates a GitHub repository with a Dockerfile, and registers the application. Use `ankra application import claude-design <export>`, **Claude Design** under Add application in the portal, or `POST /api/v1/org/applications/imports/claude-design`. Closed beta, enabled per organisation on request.

[From Claude Design to a live application →](/guides/claude-design-to-ankra)

**2026-09-08**

## Compare providers prices the fleet on AWS, Google Cloud, Azure, Proxmox and Morpheus too

The **Where the same fleet would bill** row now offers every provider Ankra can price. AWS, Google Cloud and Azure are priced from their own per-region catalogues, and each column says which region it was priced in. Proxmox VE and HPE Morpheus are priced per vCPU, GB and disk from your rate card, and the column names whether those rates are yours or Ankra's defaults. Unpriced is still never free.

[Compare providers →](/platform/cloud-cost#compare-providers)

**2026-09-07**

## A cluster's security history and scheduled report work from the CLI and MCP

The daily posture snapshots behind the trend chart and the weekly or monthly emailed security report now answer to an API token, `ankra security history` and `ankra security report-schedule` (show, `set`, `send`), and to four MCP tools: `get_cluster_security_history`, `get_cluster_security_report_schedule`, `set_cluster_security_report_schedule` and `send_cluster_security_report_now`. The two writes are confirmed before they run.

[Security reports →](/guides/security-reports)

**2026-09-07**

## Playground sizes have new prices, and a playground you already run keeps its price

New list prices, EUR a month excluding VAT: Trial free, Small €5.21 (2 vCPU / 4 GB), Medium €8.06 (4 vCPU / 8 GB), Large €15.19 (8 vCPU / 16 GB) and Extra large €28.01 (16 vCPU / 32 GB), storage bundled, pods and PVCs capped. A playground you already run keeps the price you ordered at. The billing page carries the rules: pro-rata by the second, nothing metered on top, an 8 GB organisation memory budget.

[Playground environments →](/platform/billing#playground-environments)

**2026-09-07**

## A package in the bill of materials now opens where it runs

Every figure in an SBOM component row opens the list it counts. The package name, and the images, workloads and clusters figures beside it, open a package page listing the images that carry that exact version, the workload containers running them and the clusters they run on; each entry links onward to the image's bill of materials, the workload's live page or the cluster's security tab. On the CLI: `ankra security sbom component`.

[Software bill of materials →](/guides/cluster-security#sbom)

**2026-09-07**

## Compare providers: staying put is a column, and today shows its list price

The cluster's own provider now appears beside the others: the same fleet re-sized in place on its own price book, marked **Stay**, so a cheaper plan family where you already run is weighed against a move. Today's tile shows what the same shape costs at list next to the metered bill. The estimate API accepts the cluster's own provider as the target for the same read.

[Compare providers →](/platform/cloud-cost#compare-providers)

**2026-09-07**

## Compare providers: the whole bill on every cloud, like for like

A cluster's cost page gains **Compare providers**: the same fleet - node groups, control plane, volumes and load balancers - priced on every provider Ankra can build on, side by side, with today metered where it runs. Matching is like-for-like by default, so a fleet on dedicated cores is never quoted as a saving on shared ones. A target the book can only partly price keeps a floor instead of a blank.

[Compare providers →](/platform/cloud-cost#compare-providers)

**2026-09-07**

## Pipeline logs and scan reports are kept without a backup vault of your own

A first pipeline run no longer waits on an object-storage bucket. An organisation with no ready backup vault has its step logs, scan reports and declared artifacts kept in an Ankra-managed default vault, under a key prefix of its own, with the same retention and the same per-object download links - so `scan`, `gate` and `publish` work from the start. Register a vault of your own for data residency, and it takes precedence from the next step onward.

[Ankra Pipelines →](/guides/ankra-pipelines#before-your-first-run)

**2026-09-07**

## Everything the Security Center shows is now on the CLI and the MCP server

Dispositions, compliance frameworks and their evidence export, per-cluster benchmarks, policy violations, the policy mode switch, NetworkPolicy over-privilege, the security baseline install, add-on posture, workloads, namespaces, pods and an application's image versions each gained an `ankra security` command and an MCP tool, and every Security Center route now answers to an API token under `/api/v1`. Writes confirm first and enforce the same permissions as the portal.

[MCP tool reference →](/platform/mcp-tools#security-center)

**2026-09-07**

## A stack shows what it is running, not only what it declares

A stack's new **Runtime** tab shows what its add-ons put on the cluster: the hosts its Ingresses publish, as links you can open; the pods it owns, with the status `kubectl` prints; its Services and their ports; and the events raised against its own objects. Pods are attributed by ownership rather than namespace, so stacks sharing a namespace never show each other's. A listing that could not be read says so instead of reading as empty.

[What a stack is running →](/concepts/stacks#what-a-stack-is-running)

**2026-09-07**

## Security drills down from the cluster to a container

A cluster's Security page now opens on **Stacks**: one row per stack with its attribution, actionable and known-exploited findings and SBOM coverage, plus an **Outside any stack** row so the rows add up to the cluster. A stack's members expand into the workloads they deploy, then their pods, then each container's CVEs. The same path is on the API, the CLI (`ankra security stacks|stack|pod`) and Ankra AI.

[Cluster security →](/guides/cluster-security#cluster-security-view)

**2026-09-07**

## Licence risk on every bill of materials, and a warning when a private repository owes its source

Every SBOM package now carries a licence risk tier - network copyleft (AGPL, SSPL), source-available (BUSL, Elastic), copyleft (GPL), weak copyleft, permissive or unclassified - as a filter, a summary figure, a per-image breakdown, a CSV column and a CLI flag. An application whose repository is private and whose newest scanned version links a network-copyleft package gets a **Licence obligation** notice naming the packages that oblige you to publish your source or move them behind a separate service.

[Licence risk →](/guides/cluster-security#licence-risk)

**2026-09-05**

## Pod security enforced by Kubernetes itself, not a policy engine

Version 5 of the security baseline drops Kyverno. Pod security is enforced by Pod Security Admission, built into every API server, with a ValidatingAdmissionPolicy stopping anyone but the agent lowering a managed namespace's label. Nothing here runs as a pod. The Security Center's Policies tab now shows the full check table for every cluster, with or without a policy engine, and says which mode and standard it is in.

[Security baseline →](/guides/cluster-security#security-baseline)

**2026-09-05**

## Ankra Pipelines: `egress-https` reaches only public addresses

The tier could reach any address on 443, and port 53 on any pod in the cluster. It now excludes RFC1918, link-local and carrier-grade NAT with their IPv6 equivalents, and restricts DNS to `kube-system`. This breaks a step that reaches a private HTTPS endpoint, so `ci_egress_allowed_cidrs` names the ranges a step may still reach. An image policy prefix ending in a separator now admits exactly its own boundary.

[Ankra Pipelines →](/guides/ankra-pipelines#what-a-step-runs-as)

**2026-09-05**

## Ankra Pipelines: a pull request from a fork no longer shares a cache with trusted runs

A pull request from a fork resolved the same cache volume a trusted run does. A restricted fork run now resolves no shared cache at all, and every claim carries a trust scope of `default_branch` or `branch` that no exact key or prefix match crosses. Claims written before the deploy were backfilled as untrusted, costing one cold build per key, once. Fork runs are budgeted as well as restricted.

[Ankra Pipelines →](/guides/ankra-pipelines#what-is-in-place-today)

**2026-09-05**

## Ankra Pipelines closes seven ways a run could get more authority than an administrator approved

A security review found seven ways a caller holding only `pipelines.manage` could give a run more authority than an administrator ever approved. All seven are closed: one approval route, requiring a human actor and the repository's current default-branch definition, and a dispatch that resolves its `ref` through the host and proves any caller-supplied `head_sha`. Re-approve your definitions at this release, and re-run anything that was mid-flight.

[Ankra Pipelines →](/guides/ankra-pipelines#logic-is-open-authority-is-closed)

**2026-09-05**

## Ankra Pipelines: a stage nothing can run is skipped, not left hanging

A pipeline declaring a stage kind Ankra cannot execute yet validated cleanly, then sat `pending` forever, holding its run and its concurrency group. Those kinds now raise a validation warning and the planner skips them with reason `kind_unavailable`, so the run concludes on the stages that do execute. `uses:` is refused at validation, `scan.fail_on` tightens the gate per scanner, and `ci_run_retention_days` bounds how long concluded runs are kept.

[Ankra Pipelines →](/guides/ankra-pipelines#what-is-in-place-today)

**2026-09-05**

## Every container has its own CVE, SBOM and KEV reports

A stack's Security tab opens on its running pods, grouped under the add-on or manifest that deploys each, with every container listed and three openers into a dedicated container view: CVE, SBOM and KEV. That view carries the image's findings, its bill of materials with the CycloneDX and CSV downloads, and the ring of links around it. An unscanned cluster reads Not scanned rather than clean.

[Cluster security →](/guides/cluster-security#the-container-view)

**2026-09-05**

Also shipped this week

**Microsoft Teams** - the welcome card's **Connect to Ankra** button opens the portal with the claim code filled in, instead of a 404. [→](/platform/ai-connections#connecting-microsoft-teams)

**Playground** - the create wizard and cards say storage is local to the host and not backed up, and a plan's full storage size is yours. [→](/guides/cluster-sandbox)

**2026-09-04**

## A pod's Security tab shows the vulnerabilities and bill of materials of each container

A pod's detail page has a Security tab listing every container and init container with the CVEs the scanner attributes to it, through the pod's owner chain, and the bill of materials of its image. Findings opens the image's CVE list and Components its package inventory, the same views the Security Center uses. A container no report covers reads Not scanned; one without a bill of materials reads Absent.

[Cluster security →](/guides/cluster-security#pod-security)

**2026-09-04**

## A stack's Security tab shows every vulnerability and bill of materials behind what it deploys

A stack's detail page has a Security tab reading every CVE, every CISA-listed exploited vulnerability and every bill of materials behind the workloads its add-ons and manifests deploy, as one object. An add-on is attributed by its Helm release identity, a manifest by the objects its YAML declares, both walking two owner levels down. The findings and components views carry facets computed for the stack alone.

[Cluster security →](/guides/cluster-security#stack-security)

**2026-09-04**

## Files you maintain by hand in your GitOps repository survive every sync

The reconciler's export of stored state wrote back to Git without checking who last wrote each file, so a value maintained by hand - an image tag pinned above a chart's `appVersion` for a CVE fix - could be reverted. Every write path now applies one rule: `.ankra-owned.json` records a digest of the bytes Ankra last wrote, and a file whose bytes no longer match it is kept, never overwritten.

[GitOps →](/concepts/gitops#what-ankra-writes-back-to-git)

**2026-09-04**

## Ankra Pipelines: connect a repository and watch it run

Connecting a repository is now self-service, and on GitHub the same call reads its committed `.ankra/pipeline.yaml` as the definition of record. A new application's setup pull request commits that file instead of a generated GitHub Actions workflow. `checkout` joins `run` as a stage that executes end to end, and a pull request changing a protected section runs with the last approved authority instead, saying so on the check run.

[Ankra Pipelines →](/guides/ankra-pipelines)

**2026-09-04**

## Ankra Pipelines: build, scan, gate and publish by digest

A commit is now a straight line to a deployed image. `build` produces a digest in a rootless BuildKit pod and pushes it to your organisation's CI staging repository; `scan` runs Trivy, Semgrep and Checkov against it; `gate` judges them against a policy a pipeline may only tighten; and `publish` re-tags the one digest `gate` approved. A pull request from a fork runs restricted rather than refused.

[Ankra Pipelines →](/guides/ankra-pipelines)

**2026-09-04**

## Ankra Pipelines: the review reads the run, and you can say merge when green

Ankra's pull request review answered whether a change was passing from a GitHub check run alone, so a repository on Ankra Pipelines got a review blind to its own pipeline. It now resolves the commit's newest run first and carries its facts: the failing step, findings by tool and severity, the gate verdict, the build digest. Mention `@ankraai merge when green` and Ankra merges the moment those conditions hold.

[Ankra Pipelines →](/guides/ankra-pipelines#what-a-pull-request-gets)

**2026-09-04**

## Migrate an existing application onto Ankra Pipelines with one call

Moving an application already running its own CI meant converting the workflow by hand and opening the pull request yourself. `GET /org/applications/{id}/pipeline` now reads what builds it today and what a migration would do, and `POST .../pipeline/migrate` converts it and opens the pull request for you. Merging that pull request is what switches the application over, with no separate Reconcile click.

[Migrate from GitHub Actions →](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call)

**2026-09-04**

## If you opt in, a build your CI cluster cannot run falls back to Ankra's platform builders

`ci_build_fallback: platform_builders` was a setting with nothing reading it back. When the CI cluster's own agent cannot run pipeline steps and an organisation has opted in, a `build` step now runs on Ankra platform builders instead, with the same push, scan, gate and publish downstream. The step's `executor` records which lane actually built it.

[Ankra Pipelines →](/guides/ankra-pipelines#what-is-in-place-today)

**2026-09-03**

## Live usage, agent and GitOps posture from chat and the MCP server

Nine `ankra cluster` commands the assistant and the MCP server could not answer now have tools. Ask what is eating CPU on a cluster and Ankra AI reads live usage per node or pod from metrics-server, never a cached figure. It also reads GitOps sync state including the two failures the overview hides, reports and upgrades the agent, lists every Helm release, and discovers managed clusters already running.

[MCP Tool Reference →](/platform/mcp-tools)

**2026-09-03**

## Raise support tickets from chat and the MCP server

The assistant could diagnose a problem but not hand it to a human, and an MCP client had no way to open a ticket at all. Tell Ankra AI to raise a support ticket and it proposes one with the subject, category, severity and the cluster you were looking at; confirm, and it is filed. Ask what support said and it reads the thread; reply in chat and it lands on the ticket.

[Support →](/platform/support#from-ankra-ai-and-the-mcp-server)

**2026-09-03**

## One status comment per pull request

Ankra used to leave several comments on a pull request as it worked, each in its own place and each edited on its own clock. It now keeps one comment with a section for each thing it has to say - the pipeline, the preview, the review, and the promotion when there is one - updated in place. An older preview card is adopted into it rather than left beside it.

[Pull request reviews →](/guides/pipeline-agents)

**2026-09-03**

## Convert a workflow into an Ankra pipeline from chat

Ask Ankra AI to convert an existing GitHub Actions workflow, GitLab CI file, Bitbucket Pipelines file or CircleCI config into `.ankra/pipeline.yaml`, and to validate a definition you have written. It answers with the file and every diagnostic: what it mapped, what it could only carry over as a plain `run` step, what it refused. Actions with an Ankra equivalent are mapped; the rest is kept as the script it was.

[Migrate from GitHub Actions →](/guides/migrate-from-github-actions)

**2026-09-03**

## Ask Ankra AI to create your alerts

Ankra AI could list your alerts and mute them, but asked to create one it could only point you at the New alert button. Describe the alert in chat and it now proposes a Create alert action with severity, the clusters or environments it watches, the conditions and the cooldown spelled out. It writes only conditions the evaluator implements, so an alert it creates cannot sit dead while reading as configured.

[Alerts →](/guides/alerts#creating-alert-rules)

**2026-09-03**

## A rollout Ankra verifies as healthy no longer sends you a message

After you approve a change in chat, Ankra opens a follow-up turn once the rollout settles and verifies chart version, health and sync. That turn was treated as a reply you were waiting on, so every verified rollout sent a completion message to Slack or Teams and to the inbox. A verification that finds the rollout healthy is now quiet; one that finds a failure, or parks a fix, still reaches you.

[Notification routing →](/guides/notification-routing)

**2026-09-02**

## A software bill of materials for the fleet

The Security Center gains an SBOM tab: every package the scanner found in every container image, where it runs, and whether a finding names it. When the next CVE lands you search the package and read the workloads, namespaces and clusters running that exact version, without a rescan. Images are keyed by digest and stored once. Generation is opt-in per cluster and off by default.

[Cluster security →](/guides/cluster-security#sbom)

**2026-09-02**

## Security by namespace, workload and pod

A Workloads tab breaks the fleet down the way a platform team owns it: cluster, then namespace, then workload, then pod. Each namespace row carries its scanned workloads and images, the pods running there right now, the actionable findings by severity, the known-exploited count and the last scan. Show pods resolves each workload's owner chain to its live pods. A container the scanner never covered says Not scanned.

[Cluster security →](/guides/cluster-security#workloads)

**2026-09-02**

## A what-if draft that predicts the bill before you resize

Every cluster's cost drill-down carries a what-if draft: the node groups as they run today, with the load balancers beside them, editable in place. Grow a group, shrink one, add a spot group, and the panel prices the draft and shows today's bill, the predicted bill and the change side by side. Pricing comes from the same price book the bill is metered from. Nothing is applied to the cluster.

[What if the node groups changed? →](/platform/cloud-cost#what-if-the-node-groups-changed)

**2026-09-01**

## Your money, in your currency

The organisation sets a default display currency; you can now set your own on top, and every cost figure you see follows - the fleet overview, cluster drill-downs, credentials, workloads and savings. Provider quotes got honest at the same time: UpCloud quotes arrive in US dollars and were being shown with a euro sign. Thirteen currencies are supported, each with a live exchange rate refreshed twice a day.

[Cost settings →](/platform/cloud-cost#settings)

**2026-09-01**

## A Cost center that answers whose money, and what it runs

The Cost page could say what the fleet costs, but not whose account the money is on, or what it is actually running. It now breaks spend down across six tabs: Clusters is the whole fleet in one table, Credentials groups the same money by the account paying for it, and Workloads answers where the money runs with names you recognise, linked through to each application.

[Cloud cost →](/platform/cloud-cost)

**2026-09-01**

## Cost for the capacity nobody publishes a price for

If your clusters run on Proxmox, VMware or hardware you imported yourself, the Cost page had nothing to show you. You can now state what it costs: a rate card is three monthly rates in your own currency - per vCPU, per GB of memory, per GB of storage - set on the credential that provisions the capacity. Proxmox ships with defaults; other private providers read not priced rather than free.

[Cloud cost →](/platform/cloud-cost#private-capacity-rate-cards)

**2026-09-01**

## The overview says what every cluster is

The cluster overview opens with a configuration card for every cluster kind: provider and region, the distribution actually running your API server, the Kubernetes version with the kubelet range, the CNI, and the node shape with each group's instance type and autoscaling bounds. Provider-managed clusters finally show their real version everywhere instead of a placeholder. Cells the platform has no honest data for disappear rather than reading Unknown.

[Cluster nodes →](/platform/cluster-nodes)

**August 2026**

Cluster Mesh across providers, cost evidence and a waste scan, power schedules, audit trails, and the largest CLI release yet

## Connect clusters with Cluster Mesh

**Cluster Mesh** connects your clusters into one Cilium ClusterMesh over the platform-managed WireGuard overlay - across providers, accounts and sites, with nothing exposed publicly. `ankra cluster mesh readiness` says whether a set of clusters can mesh and exactly why not; `create` and `join` do the rest: the mesh's shared certificate authority is minted and handed to every member, each member's Cilium re-renders with its identity and peer list, and every node gets an encrypted tunnel - and a route - to every node of every other member, with the `clustermesh-apiserver` dialled inside the tunnel on the peer's overlay address. Statuses (`pending / configuring / ready / degraded`) are derived from what each cluster's agent actually proved, never from intent, and a **global service** (`service.cilium.io/global`) resolves to healthy backends in whichever cluster has them. Clusters that already exist join the party with `ankra cluster mesh make-ready` - the identity and overlay range are allocated day-2 and the nodes converge in place, nothing deleted or recreated (one kubelet restart per node is the whole disruption). UpCloud and Proxmox are wired today; a Proxmox site brings one public address and a UDP port-range forward, and everything else is the platform's job.

[Cluster Mesh →](/platform/cluster-mesh)

## Notifications on your phone

The Ankra mobile app now receives push notifications, on iOS and Android.

Nothing arrives by default, and that is deliberate: a notification reaches a phone only when a **routing rule** sends it to a push audience, the same way a rule sends one to a webhook. Set the destination type to **Push notification** and pick the audience - all cluster members, or organisation admins - then filter by kind and severity as usual. "Every critical notification" and "only when a bastion goes offline" are each a single rule.

Devices add themselves. Sign in to the app, accept the prompt, and the phone appears under **Profile → Notifications**. The app holds no credential of its own: it hands the token to the signed-in page, which registers it against your session, so a device always belongs to exactly the member who signed in on it. From there you can mute one phone without signing out of it, remove it, or **Send test** - which delivers straight to that device without consulting any rule, so you can prove the path works before writing one.

Severity decides whether a notification interrupts. A critical arrives time-sensitive on iOS, so it breaks through Focus, and at high priority on Android, so it is delivered even in Doze; informational ones arrive quietly and will not light the screen. On Android the three importance levels are real notification channels - *Critical alerts*, *Warnings* and *Updates* - which means Android hands them to you: set *Warnings* to silent in system settings and it stays silent through every app update. Your existing snoozes apply unchanged, so a kind you have muted is muted on your phone too, and a notification addressed to one person reaches only their devices.

A device that registers but never rings is almost always a missing routing rule rather than a broken phone, which is why the devices page shows what the platform knows: the last delivery, and - when Apple or Google reports a token is dead, because the app was removed or the token rotated - the reason delivery stopped, rather than a silent gap.

[Mobile push notifications →](/guides/mobile-push)

## A Cost section with one-click savings

Cloud cost now has its own place in the sidebar, between Credentials and Security. **Overview** is the fleet rollup - projected month end with its pace against the run rate, month to date, run rate, priced coverage, the split by provider and the costliest clusters. **Savings** turns the same data into money: right-size idle capacity (one click opens Ankra AI's cost optimisation, whose scaling updates apply to the cluster after your confirmation), stop non-production clusters off-hours (one click writes a weekday 19:00 stop / 07:00 start pair - workers scale to zero, weekends stay down), and reduce unallocated spend - plus a per-cluster breakdown of where the money goes and the costliest namespaces fleet-wide, so every team sees the cost of what it runs. **Settings** holds the display currency - **euro by default** now - your effective discount and the network egress estimate, admin-only and applied to every figure at read time. The clusters list carries the rollup as a collapsible strip above the table. The same figures answer everywhere else: `ankra cost summary|cluster|settings` in the CLI, and `get_fleet_cloud_cost` / `get_cost_settings` / `update_cost_settings` in Ankra AI chat and over MCP.

[Cloud Cost →](/platform/cloud-cost)

## Cost recommendations that show their evidence

A savings recommendation used to ask for trust: *right-size this cluster* with nothing on screen proving anything was idle. Every cluster in **Cost → Savings** now opens its own drill-down page with the proof. For each node, the measured **average, p95 and peak** CPU and memory usage over a selectable window (24h / 7d / 30d) stands against what the scheduler reserved, with the node's own monthly cost and a defensible verdict: *underutilised* (with the saving from sizing to 1.5x the observed p95) only when even the busy moments fit well under the reservation on both resources, *spiky - keep headroom* when bursts make the average misleading - a bursty node is never called safe to shrink, whatever its average - and *no metrics* when usage is genuinely unknown, never "0% used". Around the node evidence: the 30-day cost trend, a component donut of where the money goes, the per-node usage charts so the pattern behind the statistics is visible, namespace allocation next to requested-vs-used efficiency, and the same one-click resolves, now with the evidence attached. The Overview gains a fleet cost trend, honestly scoped to the analysed clusters.

And because some waste never shows up in utilisation at all, a six-hourly **waste scan** now inventories your cloud accounts for resources that bill while doing nothing: stopped Hetzner servers (billed fully as long as they exist), unattached volumes, unassigned primary IPv4 and floating IPs, load balancers with no targets, and Kubernetes persistent volumes stuck in `Released`. Findings land on the Savings page and each cluster's drill-down with their monthly price and a one-click **Resolve with AI** naming the exact resource; a credential that could not be listed renders as a partial scan, never as "no waste". Two new reads carry it all: `GET /org/clusters/{id}/metrics/utilisation` and `GET /org/cloud-cost/waste`.

[Per-cluster drill-down →](/platform/cloud-cost#per-cluster-drill-down)

## API tokens the organisation owns

An API token used to belong to whoever created it, in two ways that made it a poor fit for automation. It authenticated only while that person was still a member, so removing someone from the organisation stopped every token they had minted - the deploy pipeline they set up two years ago fails with a `401` and nothing in the log says why. And it carried their whole authority rather than a capability anybody had chosen for it. It was not really scoped to an organisation either: the same header the CLI's `--org` flag uses re-pointed any token at any organisation its owner belonged to.

**Organisation → Service tokens** is the other kind. A service token authenticates as a *service account* - a principal the organisation owns, holding one role an administrator picked - so it survives offboarding, appears where any administrator can review and revoke it, and reaches its own organisation and no other. Creating one takes a name, a role and an expiry; the secret is shown once. Minting under an existing name adds a second token to that same account, which is how a credential is rotated with no gap: issue the new one, roll the deployment, revoke the old one, and the account keeps one continuous audit history across the rotation. Revoking stops a single credential and leaves the account's others alone; deleting an account's last token stands the account down, so a token minted under that name later needs its role granted again deliberately.

Minting requires `members.manage`, and so does reading the list - an inventory of standing credentials and the authority each one carries is not the member list. One guard goes further than the role-assignment surface needs: you cannot mint a token carrying permissions you do not hold yourself. Granting a colleague a role hands them nothing until they sign in as themselves, but a token works the moment it exists, so without that rule "can manage members" would quietly have meant "can escalate to owner". A service token can also be scoped to `mcp:read` or `mcp:write`, reaching the hosted MCP server only. The same surface is available to automation at `/api/v1/org/organisation/service-tokens`.

[Service tokens →](/guides/service-tokens)

## Move a cluster to another organisation

An imported cluster can now change organisations without being re-imported. From the cluster's **⋯** menu, the cluster overview or **Settings → Danger Zone → Move cluster**, an organisation admin picks a destination organisation they also administer, types the cluster name, and the cluster - with its agent, executions, resources, findings, insights and variables - now belongs there, still connected. Access grants, cluster-scoped role assignments, kube tokens, notification routes and mutes, report schedules and cluster group memberships from the previous organisation are detached and listed in the result; billing, audit and chat history stay where they were. Ankra-provisioned and managed Kubernetes clusters stay put for now - their provider credential belongs to the organisation that created them. Both organisations record the move in their audit trails. The move is refused while operations are running, while the cluster is in a cluster mesh, while it has DNS zones bound to the current organisation, for playground and sandbox clusters, and when the destination already has a cluster with that name. The same move is `ankra cluster move <cluster> --organisation <id|slug|name>` in the CLI and the `move_cluster_to_organisation` tool in Ankra AI, both behind the same two-organisation admin check.

[Move to another organisation →](/platform/cluster-settings#move-to-another-organisation)

## Security counts that open what they count

A finding row in the Security Center used to say **Open · 7** and **Resolved · 2** next to **7 clusters · 7 workloads** and leave you there: none of it was clickable, and the two resolved occurrences were not even loaded, so the sheet's own **Resolved** filter answered *no occurrences match* under a chip that said two. Every number on a row is now a way in. A status chip opens the finding on that status - the live ones filter the remediation plan, **Resolved** lists the occurrences the latest scan no longer reports, most recently resolved first, with the workload, the image and when each went away. The affected cell opens a new **Affected clusters** table: one row per cluster with its live workloads, the same four counts, and when it last reported the finding, each cluster deep-linking into its own Security tab with the finding already open. The chips are now labelled **Occurrences** and say so in the sheet - one per workload, container and image - which is why seven open occurrences can sit beside seven workloads and two resolved ones. Counts and lists come from the same query, so a chip never names a row the sheet cannot show; the API carries both as `clusters` on the finding detail and a paginated `GET /api/v1/org/security/findings/{finding_id}/occurrences?status=…&cluster_id=…`.

[Security Center findings →](/guides/cluster-security#findings)

## A verified email before invitations

Signing in now proves the mailbox before it proves anything else. An account whose email address is still unverified can no longer pick up an invitation sent to that address: **Pending invitations** stays closed and accepting one answers *Verify your email address before acting on invitations* until the verification link has been opened - then the same account is admitted and the invitation is waiting where it was. A first sign-in with a provider that does not share an email address at all (some Microsoft Entra ID and social identities) is refused with a clear message instead of creating an organisation that could never be contacted or invited; sign in with an account that carries an address. Accounts created before this keep signing in as they did.

[Roles and access →](/guides/roles-and-access)

## The Ankra registry cleans up after itself

Images pushed to your organisation's private Ankra registry no longer accumulate forever. Every organisation project now carries a retention policy that Harbor runs once a day: an artifact is kept while it was pushed within the last 30 days, and the three most recently pushed tagged versions of every repository are kept regardless of age. Older tagged images beyond those, and the untagged leftovers of overwritten tags once they are 30 days old, are removed. Plan rollbacks around it - a version is reachable while it is one of the last three or under 30 days old - and redeploy long-lived workloads from a recent build so a reschedule never reaches for an image that is gone. Registries you operate yourself are not touched.

[Image retention →](/guides/cicd-pipeline#image-retention)

## Move a Docker deployment into a cluster in one command

Getting an application off Docker Compose used to be two jobs, and the second one was the hard one: translating the services into Kubernetes objects, and then getting the data out of the containers and into the databases you just deployed, by hand, with a laptop in the middle holding a copy of production.

`ankra migrate up ./app --cluster production` does both. It converts the Compose project into a stack, applies it to the cluster, waits until each database workload has a ready pod, dumps the deployment's PostgreSQL, MySQL and MariaDB databases, and restores them in-cluster. `--plan` prints what it found first and changes nothing: the databases with their sizes read from the running containers, the estimated dump size against your free disk, and an explicit list of what will not be carried across. The run is re-runnable, so you rehearse against a live source and then cut over with `--stop-source`, which stops the source's non-database services before the final dump and prints the `docker start` command to bring them back.

The dumps travel through your own [backup vault](/guides/backups): the CLI uploads to your bucket on presigned URLs, and the cluster's agent runs a Job that verifies the SHA-256 sums and restores. Ankra never holds the data, no vault credential reaches the cluster, and nothing on your machine needs `kubectl` or a database client. The individual steps stay available as `ankra migrate convert`, `export`, `data`, `restore` and `restore-status` when you want to inspect what each produced.

Compose is only the format that ships with it. The conversion and the export are done by a **module**, and any executable named `ankra-module-<name>` on your `PATH` or in `~/.ankra/modules` is one: it answers `describe`, `detect` and `convert` with JSON on stdin and stdout, adds `export` if it can dump its own databases, and can be written in any language. `ankra migrate modules` lists what you have, and a worked example in about a hundred lines of Python ships in the CLI repository.

[Moving a Docker deployment →](/guides/migrate-from-docker) · [Writing a module →](/guides/migrate-modules)

## The inbox knows who a message is for

A notification is now addressed either to the whole organisation or to one person. Personal messages reach only their addressee, wear a **For you** marker in the Activity feed, and count separately - so a direct message never drowns in the organisation's pile. Filter the Activity page by audience (**All messages / For you / Organisation**) to see just yours or just the shared ones. Reading, acknowledging and dismissing were already per person; the audience makes the distinction visible everywhere, API included (`audience` on every notification, an `audience` list filter, and `personal_unread` on the counts).

[Activity & Inbox →](/platform/activity-inbox#organisation-messages-and-messages-for-you)

## A DevSecOps agent on every AI team

Every organisation's default AI team gains a sixth member: **DevSecOps**, a security specialist whose job is to resolve the critical and high vulnerabilities in the images running on a cluster. Open it from a cluster's chat and it reads that cluster's security report, maps each vulnerable image to the connected application deployed there - or to the add-on the report attributes it to - and fixes at the source: base-image and dependency bumps opened as pull requests on the application's repository, one per application with every CVE it clears listed, and add-on upgrades proposed with a rollback. Known-exploited CVEs come first; a CVE with no fix is reported, not hidden. Its capability envelope refuses deleting a resource, an application, a stack, or an add-on, so a finding is never made to disappear by removing what runs.

Organisations that already have the five-agent team get the DevSecOps agent the next time anyone opens **AI → Agents**; a default you deleted stays deleted. It arrives ready to act: it ships acting as your organisation's agent identity, which Ankra provisions on the operator role the first time the roster is opened - no board-staffing setup first - while its **Propose** autonomy keeps every cluster write behind your approval. Stand the identity down under **Settings → Autonomy → Board staffing** if you would rather it only reports.

[The DevSecOps agent →](/platform/ai-agents#the-devsecops-agent)

## Default and catalog AI agents now run on the Quick model unless you chose one

The six default roles and the four catalog agents (Incident Responder, Gap Scanner, Reviewer, Nightly Auditor) now ship pinned to **Quick**, and agents already seeded or hired from those templates that nobody had pinned move to Quick too. Agents you created yourself, and any agent whose model you chose, keep their setting. Raise a single agent to **Think** or **Expert** from its Edit dialog when its work needs deeper reasoning.

[Model →](/platform/ai-agents#model)

## Every AI agent can run on a cheaper model and carry a daily token limit

Every organisation AI agent now has two cost controls of its own. **Model** pins the agent's turns to a rung of your model catalog - **Quick**, **Think**, **Expert**, or a custom entry - instead of leaving each turn to the router; the DevSecOps agent ships on **Quick**. **Daily token limit** caps what the agent may consume in one UTC day across its runs and persona chats. An agent that reaches its limit is not dispatched again until midnight, a turn already running finishes with one wrap-up iteration rather than being cut mid-thought, and a notification - in the inbox and through your notification routes - names the agent, the tokens used, and how to raise the limit. Today's usage sits beside the limit on the agent page. The DevSecOps agent ships with a 2,000,000-token day; the other defaults stay unlimited until you set one.

[Models and daily token limits →](/platform/ai-agents#model)

## Debug pods that impersonate a workload

A distroless image has no shell to attach to, and a crash-looping container is gone before a terminal can reach it. **Debug** on any pod now spins up a separate pod that impersonates it - the same service account, the same node, the same volumes and volume mounts, the same environment variables and `envFrom` sources, the same tolerations and security context - under an image chosen for its tools: netshoot by default, or busybox, alpine, ubuntu, or any image you name. You land in its terminal with the workload's mounts and environment in front of you, and the workload itself is never modified. **New debug pod** on the pods list does the same from a namespace, with nothing mirrored.

Two things are deliberately not copied. Labels never are, so a debug pod never sits behind the workload's Service or inside its PodDisruptionBudget; and host namespaces are left alone. Every debug pod carries a lifetime (30 minutes to 8 hours) that the kubelet enforces on its own, the agent removes expired ones, and creating or deleting one writes an audit row naming the image and what was mirrored. Creation needs `kubernetes.write` and `kubernetes.exec`. From the CLI: `ankra cluster debug create --namespace <ns> --from-pod <pod>`, plus `list`, `delete` and `images`. Needs cluster agent 2.1.1074 or newer.

[Debug pods →](/platform/debug-pods)

## Every pod terminal session is recorded

Opening a terminal into a pod used to leave no trace. It now writes an `open_pod_terminal` audit row, and everything typed and everything the container answered is stored with the session (up to 4 MiB; longer sessions are marked truncated). In the organisation audit log and a cluster's Audit tab, the row shows the session's facts - who, which container, which shell, how long, how it ended - and **Replay session** plays the recorded output back into a read-only terminal with the typed input listed beside it. `ankra org terminal-session <id> --transcript` prints the same recording. Transcripts are readable with `audit.read` and never travel inside the audit row itself.

[Recorded sessions →](/platform/pod-terminal#recorded-sessions)

## Multi-zone UpCloud clusters on a WireGuard mesh

UpCloud has no multi-zone region - every private network, router and load balancer is bound to one datacenter - so an UpCloud cluster was a single failure domain, and the only answer to "what if Helsinki goes down" was a second cluster.

A cluster can now be created across a **zone pool**: pass `zones` (at least three, with three control planes, one per zone) and Ankra builds a router, private network and NAT gateway in every zone, joins the nodes with a platform-managed kernel WireGuard mesh over UpCloud's account-wide utility network, and has Kubernetes advertise the overlay address on every node. Control planes spread one per zone, node groups spread across the pool or pin to a zone with `zone`, day-2 growth follows the pool, and `ankra cluster upcloud zones` adds zones later. Losing a zone costs capacity, not the cluster. Load balancers and volumes stay in the primary zone - both are zone-local on UpCloud - and every node carries the standard topology labels.

Multi-zone placement is rolling out per organisation; ask us to enable it for yours.

[Multi-zone clusters →](/guides/upcloud-clusters#multi-zone-clusters)

## GitOps repoints are atomic, and a wrong branch cannot strand a cluster

Moving a cluster to a different GitOps repository or branch with `ankra cluster apply --allow-repoint` used to commit the switch first and write the cluster's state to the new source second. A target Ankra could not write to - a branch that did not exist, a branch protected against direct pushes - left the cluster bound to it with its sync baseline cleared, one sync away from applying whatever stale file sat at the target's head.

The write now happens first, on the same transaction as the switch, so a failed write changes nothing: the cluster keeps syncing from its current source and the error says so. A branch that does not exist is refused before anything is attempted, together with the branches the repository does have. The refusal you see without the flag also describes what a repoint actually does - Ankra writes the cluster's current state to the new source before syncing from it - instead of predicting a prune from the target's current contents.

[Repointing a cluster →](/reference/importcluster#specgit_repository)

## Find an organisation by typing its name

If you belong to many organisations, the profile menu's **Switch organisation** submenu used to run off the bottom of the screen with no way to scroll it, and the **All organisations** and **Create organisation** links at its foot went with it. The submenu now opens with a search box: start typing anywhere in it to narrow the list by name, slug or id, press **Enter** to switch to the first match, or use the arrow keys to pick one. The list scrolls within the screen, and the links stay pinned below it - **All organisations** now shows how many you belong to.

The **All organisations** page gained the same search, lists your current organisation first, and pages through the rest twenty at a time; its page controls, previously decorative, now work.

[Switching organisations →](/concepts/organisations#switching-organisations)

## Known exploited vulnerabilities (CISA KEV) and EPSS in the Security Center

A CVSS 9.8 nobody is exploiting used to outrank a CVSS 7.5 that is being exploited right now. The Security Center now cross-references every finding with the public CISA Known Exploited Vulnerabilities catalog and the FIRST EPSS exploit-prediction scores, joined platform-side by CVE id, so no image data leaves your cluster and Trivy Operator needs no extra configuration.

Findings carry a **KEV** marker with CISA's date added and remediation deadline, plus the EPSS probability and percentile. Filter with the new **Known exploited (CISA KEV)** chip, sort by **Exploitability** (KEV first, then EPSS, then severity), and read a **Known exploited** tile on the fleet scorecard. Cluster, workload, and add-on posture views count known-exploited findings, remediation candidates rank them first, and the scheduled security email calls them out with their own banner. Alert rules gain two `security_findings` metrics - `kev` and `new_kev_cves` - and the new-CVE notification now flags KEV listings of any severity. The same fields ship on the security API (`known_exploited`, `kev_date_added`, `kev_due_date`, `kev_ransomware_use`, `epss_score`, `epss_percentile`, plus a `known_exploited` filter) and in the AI security context.

[Exploitation intelligence →](/guides/cluster-security#exploitation-intelligence-cisa-kev-and-epss)

## Every CVE has an Ankra advisory page

A finding used to hand you off to the scanner's advisory site - avd.aquasec.com, nvd.nist.gov - to learn what a CVE actually is. The Security Center now has its own **advisory page** for every CVE: the platform reads the public record from the NVD 2.0 API and OSV, parses it, and renders it in the Security Center's vocabulary. The **Advisory** link on every findings row and **Open advisory** in the finding sheet lead there.

The page carries the analyst description with CWE ids and aliases; CISA's KEV entry, the EPSS probability and CISA's SSVC decision under **Exploitation**; the lead CVSS score with its vector spelled out component by component and every published assessment behind it; the affected products and version ranges from both sources, written as "2.34 before 2.39 (fixed in 2.39)"; the organisation's own findings for the CVE with a link into each; and the sources' references grouped patches-first. It tells "not read yet" (the page polls while the platform fetches the record, and opening it puts that CVE at the front of the queue) apart from "no public record", and a provenance footnote says when NVD and OSV were last read. Stored records are re-read every two weeks. The API serves the same content at `GET /api/v1/org/security/advisories/{cve_id}`.

[Advisory pages →](/guides/cluster-security#advisory-pages)

## Known-exploited vulnerabilities are now impossible to miss, and the Security Center answers in milliseconds

The KEV signal was easy to walk past: a small marker in a column, on a list sorted by scan time. Now, when CISA lists any of your actionable findings, the Overview, the Findings page, and every cluster's Security tab open with a red **exploited in the wild** banner that says how many vulnerabilities are being exploited, how many are past CISA's remediation deadline, and how many CISA links to ransomware campaigns - with **Review exploited findings** and **Fix with AI** one click away. Findings open ranked by **Exploitability** (KEV first, then EPSS, then severity), each listed row shows CISA's deadline in explicit tense and a **ransomware** marker, the **Known exploited** tile carries the overdue and ransomware subsets, and the finding sheet quotes CISA's own entry: vulnerability name, vendor and product, and **CISA required action**. The API adds `kev_vendor_project`, `kev_product`, `kev_vulnerability_name`, and `kev_required_action` on findings and candidates, and `known_exploited_overdue` and `known_exploited_ransomware` on the overview; the AI security context carries the deadline and required action too.

Underneath, the Security Center stopped re-counting every scanner observation your organisation has ever recorded on each page load. The overview, the findings list and its filter counts, the remediation candidates, and the cluster posture now read from posture rollups the platform keeps current inside the same transaction that records a scan or a disposition change - so a findings page that took four to twelve seconds on a large fleet (and timed out under load) answers in milliseconds, and acknowledging a finding is reflected on the very next load.

[Exploitation intelligence →](/guides/cluster-security#exploitation-intelligence-cisa-kev-and-epss)

## kubeadm is the default distribution everywhere

A cluster created without a `distribution` now gets **kubeadm** - vanilla upstream Kubernetes with Cilium - on every surface: the API, the CLI `--distribution` flag, the AI create tools and the Terraform provider, matching what the create wizards already preselected. An omitted `cni` follows the distribution: Cilium on kubeadm, Flannel on k3s. k3s stays fully supported - pass `--distribution k3s` (or `"distribution": "k3s"`) to get it - it is just never a default. Existing clusters are untouched.

## Order playgrounds at the size you need

The playground is no longer one fixed try-it size. **Create cluster** now offers **Playground** as a first-class option: pick a size - from the free Trial up to 16 vCPU / 32 GB - and Ankra provisions it on its own infrastructure, no cloud account or credentials needed. Each size shows its flat monthly price in the picker.

Only the free Trial is limited to one per organisation; paid playgrounds can be many, bounded by a per-organisation memory budget of 8 GB by default. Ordering a paid size requires billing permissions, a billing plan and a payment card on file - the Trial needs none of that. When a size does not fit, the picker offers a **limit-increase request** - the new limit and a short justification, reviewed by the Ankra team, with a notification when it is decided. The free monthly AI allowance gains the same request path from the billing page's allowance card.

Paid playgrounds also **resize in place** (Settings → General, or `ankra cluster playground resize`): the quota and the monthly price change, billed pro-rata across the change, and nothing you deployed is touched. Billing is fair by construction - it runs from the moment the environment is ready, never from the order that placed it - and every order, resize and destroy leaves a notification receipt. Organisations with long-overdue invoices have new paid orders refused and, after three weeks, paid playgrounds reclaimed.

The price you order at is the price you keep - later catalog changes never re-rate a running environment. Sizes the shared pool cannot place right now are shown greyed out rather than hidden, and the free trial keeps its one-click path everywhere it exists today: the first-run screen, the create-cluster dialog's banner, and `ankra cluster playground create`.

The whole lane now speaks every surface: alongside the portal, the `/api/v1` API and the CLI, **Ankra AI and the MCP tool catalog** can list the sizes with live availability and budget headroom, order a playground, check its provisioning, resize it, destroy it, and file a limit-increase request. The mutating actions are confirmation-gated - the approval card names the size and the monthly price before anything is ordered - and every billing gate applies identically to what a chat agent orders and what a click orders.

Limit requests live under billing, and the billing page now shows it: a **Playground memory budget** card reports how much of the budget your paid playgrounds use, carries the same request path the size picker offers, and - like the AI allowance card beside it - shows a pending request under review and a declined one with its outcome, so a decision is discoverable where the request was made.

Billing now opens with **This month** - what each thing has cost so far and where it is heading. Compute and playgrounds, which are charged to your invoice in EUR, sit in one group; the AI allowance included with your plan, priced in USD and never invoiced, sits in another - so the two currencies are never added together. Every row reads the same way: what you used, so far, projected, and the limit that applies. Playground spend, previously invisible on every billing surface, is now reported and split from compute, and each invoice shows its playground share as its own column. Two fixes landed with it: the playground memory budget counts only environments you actually have (a destroyed or failed environment no longer holds your budget), and reads the organisation whose billing page you are on rather than the one you last switched to.

The playground memory budget now names the playgrounds it counts - plan, name, memory and when each was ordered - on the billing page's budget card and in the plan catalog (`GET /org/clusters/playground/plans`, and the `list_playground_plans` chat and MCP tool). A budget past its limit, such as a Large ordered before the budget existed, reads as what it is rather than as a miscount, with a line on what over budget means: new playgrounds and upgrades wait, what you run keeps running. The order gate now counts exactly what the catalog shows. And billing stops when the receipt says it does: destroying a playground closes its price of record at the request, not when the teardown finishes.

[Playground →](/guides/cluster-sandbox)

## A Nodes section for every cluster

Every cluster gains a **Nodes** section in its sidebar, directly above Kubernetes: the infrastructure view of the machines it is made of. The overview joins what the cloud provider knows about each VM with what Kubernetes knows about the node - role, group, instance type with vCPU, memory, disk and list price from the live catalog, a GPU chip from the node's feature-discovery labels, Kubernetes readiness with the kubelet version, the VM's state, location and addresses - and puts the controls on the row: cordon, uncordon and drain with progress, restart the VM, resize the bastion, open the node in Kubernetes, or the provider's record. A machine Kubernetes has never seen reads *Not joined* or *Not a node*, never as broken. Stat tiles sum the fleet - machines by role, ready nodes, vCPU, memory, GPUs, monthly run rate - and say *not reporting* rather than zero when a figure cannot be read.

Node groups, the control plane and the bastion each get a tab. The node-groups tab carries everything Settings → Nodes offered plus **Max out**: Ankra reads your cloud account's remaining quota through the cluster's credential and sizes a group to the most it can hold - the tightest of remaining servers, vCPUs and memory for the group's instance type, capped at 100 - naming the bound and the added cost before you confirm, and saying *unavailable* when a provider hides its limits rather than guessing. The bastion tab shows its health as the scheduler last recorded it, with diagnose-over-SSH, restart and resize. The same quota report is on the API as `GET /org/clusters/{provider}/{cluster_id}/quotas`. Settings → Nodes redirects to the section, so older links keep working.

Playgrounds carry their **size card** on the overview: a paid one names the direction and the monthly difference before a resize (*Upgrade to Medium: +€15.30/mo*), and the free trial offers **Upgrade to a paid size** instead of a card with no control.

The same tab adds **standalone VMs**: a machine on the cluster's network that is not a Kubernetes node - a database host, a build box, a jump host of your own - provisioned the way the bastion is, with the cluster's SSH keys, private-network only unless you give it a public address, and kept running when the cluster is stopped because it carries your state. Add one by name and size from the live catalog, then restart, resize or remove it from its row; VMs also appear in the machines table with the role **VM**. Available on Hetzner, UpCloud, DigitalOcean, OVH and Proxmox clusters, and the bastion and every VM are now metered into the cluster's cost as **Bastion & VMs**. The UpCloud node-group picker reads the cluster's live catalog too, so GPU plans appear with their accelerator fit and price. The API carries VMs under `/org/clusters/{provider}/{cluster_id}/vms`.

[Nodes →](/platform/cluster-nodes)

## Agent Skills for every AI assistant, not just two

`ankra skills install` used to reach Cursor and Claude Code. It now detects the AI assistants
configured on your machine and installs Ankra's curated Agent Skills into all of them: Claude
Code, the Claude app, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI, OpenCode, Cline, Zed,
OpenClaw, and anything that reads `AGENTS.md`. `--client` replaces `--editor` (kept as a
deprecated alias) and takes a list, `all`, or `auto`; `ankra skills clients` shows what was
detected and where each assistant's skills land.

Assistants with no skills mechanism of their own get the skills in a shared library plus an index
in the file they always load - which is what makes the skills work there at all. The Claude app,
which cannot read your filesystem, gets one uploadable bundle per skill. Assistants with slash
commands also get the Ankra workflows: `/ankra-new-cluster`, `/ankra-ship-service`,
`/ankra-connect-app`, `/ankra-triage`, `/ankra-promote`, `/ankra-harden` and `/ankra-profile`.

The skill set grew to twenty-two, adding end-to-end coverage for getting started, building
clusters (provider, region, instance family), domains and DNS, deploying applications, wiring an
app to services that already run (an LLM gateway, Harbor, a database), stack profiles,
troubleshooting, security, and supervising Ankra's own AI agents - and every `ankra` command the
skills document is now verified against the CLI's real command tree at build time.

[Agent Skills →](/integrations/agent-skills)

## A ticket now shows what its agent is doing right now, and opens the session it is doing it in

A ticket said an agent was assigned and, while a run was live, showed a pulsing dot - and then nothing moved for the whole run, so there was no way to tell a busy agent from a wedged one. The timeline now ends in a live panel while a run is in flight: a spinner, the step the agent is on with what it is calling it on, and the last few steps behind it, updating as the run moves. A queued run, and one parked waiting for a person, say that instead of claiming to be working.

The session behind it is now reachable, which it was not from anywhere. **Open the agent's session** on the live panel, the **is working** chip at the top of the ticket, the timeline entries recording that a run started and how it ended, and the **Agent run** entry under **Linked** all open the transcript of the run working *that* ticket - to read its tool calls and results, answer a question, decide an approval, or guide it. Every run has its own address (`/organisation/ai/agents/runs/<run id>`), so a pasted link opens the run it names; previously each of these landed on the agent's most recent run instead, which for an agent working several tickets was the wrong session. Picking a run on an agent's page puts it in the address too, and the fleet run history opens the run you clicked rather than its agent. Fixed alongside: a finished run's transcript replayed as tool calls and silence, because the agent's own prose was dropped on the way to the page.

[Watching an agent work →](/platform/ai-board#watching-an-agent-work)

## The pod page is condensed too, and it shows what a container asks the GPU for

Following the node page, a pod's **Overview** now opens on state chips (phase, QoS, the GPU it requests, restarts with their recency), an identity strip, and tiles for containers ready, restarts and the CPU / memory / GPU requested against limits. Each container is one compact card - state, restarts, the previous termination such as `OOMKilled (exit 137)`, image with copy, **requests → limits per resource including `nvidia.com/gpu`**, ports, probes with their inferred status and the command line - instead of a fully expanded three-column block; init containers sit in the same list. Conditions read as one row each with the kubelet's message only when something is wrong, the network, security, scheduling, topology, service-account, DNS and advanced cards fold into **Placement** and **Runtime**, volumes get a panel that names their source, and labels and annotations are collapsed and grouped like the node page's.

[Pod details →](/platform/kubernetes-insights#workloads)

## A blocked ticket now asks its question as a choice - pick an option, or answer with something else

When an AI board agent found two ways forward and needed a person to pick one, it wrote them into a comment, moved the ticket to **Blocked**, and the page showed a blocked ticket with prose to read and a comment box to answer in - so the decision was easy to miss and easy to answer in a way the agent then had to re-ask about. An agent that blocks on a choice now hands the options over as data (`decision_options` on `ticket_update_status`, with a `decision_prompt`), and the ticket page opens on the question: each option with its summary, the recommended one marked, an optional note, and **Something else** for an answer in your own words. **Send decision** records a `Decision:` comment on the timeline and resumes the agent, which acts on the answer without asking again. The answer is also on the API at `POST /api/v1/org/ai-tickets/{ticket_id}/decision`.

The same choice now reaches you wherever the ticket does. In **AI chat** (and over MCP) `ticket_get` shows the pending question and the new `ticket_decide` tool records your answer. The CLI gains an AI board: `ankra tickets list|get|events|comment|transition|decide`, with `ankra tickets get T-8` printing the options and `ankra tickets decide T-8 --option a` (or `--answer "..."`) answering them. In **Slack and Teams** the thread reply that announces the block, and the escalation card while the ticket still waits, carry the options as buttons - the recommended one highlighted - and **Something else** asks for a thread reply starting with `Decision:`, which is recorded as the answer rather than as a plain comment.

[Answering a choice →](/platform/ai-board#answering-a-choice)

## The cluster domain is your own domain once a custom DNS zone publishes it

An organisation whose domain lives in its own DNS account cannot register it as its Ankra domain, so it sets it as the Preview domain and declares it as a custom DNS zone - and was still told its cluster domain was `<cluster>.<org>.ankra.cc`. `${{ ankra.cluster_domain }}` now resolves to the Preview domain whenever a custom DNS zone declared for the organisation or the cluster covers it, and the same rule drives Ankra AI's hostname advice (`get_preview_domain` reports `cluster_domain` and who publishes it), `ankra cluster domain` (a new **Public domain** line), and the Preview domain's "hostnames will not resolve" warning, which no longer fires for a domain the cluster's own external-dns publishes.

[Built-in variables →](/concepts/variables#built-in-variables)

## The node page is redesigned, and it knows about GPUs

A Kubernetes node's page now opens on a header of readiness, role, accelerator, instance type, provider and placement chips, a fact strip, and stat tiles for what the scheduler can hand to pods - CPU, memory, GPU, ephemeral storage and the pods placed on the node against its limit. Conditions read as **Healthy** or **Problem** with reason, message and last transition rather than a raw `True`/`False`; the system, network, allocatable-resources, taints and cached-images cards replace the old key/value lists; and labels are grouped by prefix with search and click-to-copy, so a node carrying sixty discovery labels is readable.

On a GPU node - `nvidia.com/gpu`, a MIG profile, `amd.com/gpu`, Intel or Gaudi - an **Accelerator** card reads the GPU Feature Discovery labels the GPU operator stamps on the node: product, family and compute capability, count and memory per GPU, CUDA driver and runtime, sharing strategy (exclusive, time-slicing, MPS, MIG with its active profile), vGPU, driver-upgrade state and the operator components deployed, plus whether the device plugin is advertising allocatable GPUs yet. With a Prometheus metrics source connected it reads the DCGM exporter too: utilisation, framebuffer, temperature, power, clocks and the pod attached to each GPU, the pods on the node requesting GPUs, and per-GPU charts on the **Metrics** tab.

[Kubernetes Nodes →](/platform/kubernetes-nodes)

## AI board tickets now show what a fix actually changed - the cluster, the stack, the operation, and a bill of materials

A ticket tracking a fix the AI chat or an agent applied used to show a timeline of tool names and a **Pending action** link that opened the whole Inbox - nothing on the page said which cluster or stack was touched, what changed in it, or whether the apply had actually run. The ticket now carries a **Changes** ledger, one entry per applied action like a commit log: the tool, who approved it, the risk and reversibility, the cluster and stack with the namespaces involved, the times it was proposed and settled, and the operation it created on the cluster's operations ledger with its step outcome - the entry reads **applying** while the apply is still running and **failed** if it failed after the tool returned. Expanding an entry shows the same bill of materials the approver reviewed: addons with chart and version, manifests with kind and namespace, and their diffs. A **Bill of materials** panel in the rail folds every change into the ticket's blast radius - clusters, stacks, namespaces, addons, manifests and executions, each linked to its page - and **Cluster context** gained **Stacks** and **Operations** shortcuts. The ledger is also on the API at `/api/v1/org/ai-tickets/{ticket_id}/changes`.

[Changes and the bill of materials →](/platform/ai-board#changes-and-the-bill-of-materials)

## Declared registries can keep their flat component repositories, and an application can be moved to another GitHub credential

Two follow-ups from wiring the first organisation onto its own Harbor. A monorepo's images were always addressed as `<project>/<app>/<component>`, so a registry whose pipeline had been publishing `commerce-images/backend` for months looked unpublished to Ankra; `flat_repositories` on the image registry declaration (**Settings → Image registry**, `ankra application registry set --flat-repositories`) makes publish readiness, the deploy gate and the generated workflows use `<project>/<component>` instead. Where the names differ altogether - `commerce-images/commerce-backend` - `component_repositories` names each component's repository outright (`--component-repository backend=commerce-backend`, or one field per component in the settings panel). And the GitHub credential an application was created with can now be changed - `ankra application credential set <application-id> --credential <name>` - so an application bound to an App installation that cannot reach its repository no longer has to be deleted and recreated.

[Using your own registry →](/concepts/applications#using-your-own-registry)

## Every application now gets its own registry robot account - on Ankra's registry and on a Harbor you operate

Applications used to log in to the registry with one push robot shared by the whole organisation, and an application that publishes to a Harbor you run got no robot from Ankra at all - you created one by hand and pasted it into the repository's Actions secrets. Ankra now mints a push robot **per application** (`robot$<project>+app-<application-id>`) on the project it publishes to, stores it as a managed registry credential, and writes it into the repository as the build's login, so a leaked secret is rotated or revoked for that one application and a deleted application takes its robot with it. On your organisation's Ankra registry this happens on setup and reconcile, with no action needed; applications onboarded earlier get theirs the next time **Fix automatically** runs or when you create it from **Settings** → **Image registry**. On a registry you operate, name a credential with project administrator rights as `admin_credential_name` on the image registry declaration and Ankra mints, rotates and revokes the robot there too - without it, your robots stay yours and untouched. Create, rotate and revoke from the application's settings, with `ankra application registry robot get|ensure|rotate|revoke`, or on the API at `/api/v1/org/applications/{application_id}/registry-robot`.

[Robot accounts →](/concepts/applications#robot-accounts)

## DigitalOcean GPU Droplets are now priced in the cloud cost view

Fixed: a DigitalOcean cluster with a GPU Droplet worker (`gpu-h100x1-80gb`, `gpu-l40sx1-48gb`, and the rest of the `gpu-*` sizes) showed only its CPU nodes on the Cloud Cost card and in the cluster **Cost** view. The GPU size had no row in the price catalog, so the worker was priced at zero and dropped out of the compute total - the coverage counter was the only hint that the estimate understated the bill, while the create wizard, which reads DigitalOcean's live prices, showed the real figure. Every GPU Droplet size DigitalOcean sells - RTX 4000 Ada, RTX 6000 Ada, L40S, H100, H200, MI300X, MI325X, and the Spot GPU sizes - is now priced at its on-demand hourly list rate. GPU Droplets are billed per second with no monthly cap, so the hourly rate is used as published rather than fitted to a capped month. The correction lands on the next hourly metering pass; there is nothing to do.

[Cloud cost →](/platform/cloud-cost)

## A zone in your own DNS account is now served from every cluster in the organisation

A DNS zone you keep in your own provider account can be declared **once, for the whole organisation**, and every cluster - the ones running now and every one created afterwards - gets its own Ankra-managed `external-dns` for it. Until now the declaration was per cluster (`ankra cluster custom-dns-zones`), so a freshly created cluster came up with its Ingress hostnames on your domain dropped silently and its certificates waiting for DNS that nothing was publishing. `ankra org dns credentials create` stores your external-dns webhook credential (into the platform's secret store - it embeds the token, so no read surface returns it), and `ankra org custom-dns-zones add --zone <zone> --credential <name>` declares the zone; each cluster's controller is pinned to exactly that zone with its own record ownership, so it can never fight Ankra's own controller, another cluster's, or records you publish yourself. A cluster's own declaration of the same zone still wins on that cluster, `ankra cluster custom-dns-zones list` now says where each zone was declared, and withdrawing the organisation's declaration tears down only the controllers Ankra rendered. The same is available on the API at `/api/v1/org/custom-dns-zones`.

[Serving a zone in your own DNS account from every cluster →](/concepts/applications#serving-a-zone-in-your-own-dns-account-from-every-cluster)

## Node groups now show their availability zones

On an OVH cluster in a 3-AZ region, `ankra cluster node-group list` and `ankra cluster ovh node-group list` now end each line with `az=` and the zones the group's nodes were placed into, and the node-group listing API carries them as `availability_zones`. Until now the only way to see where a group's nodes sat was one `ovh nodes get` call per node, which is how two groups named for zones a and b came to sit entirely in zone c on a cluster built for multi-AZ without anything on the listing saying so.

That placement was the balancer working as designed rather than a rendering fault: a group added without `--availability-zone` takes the zone with the fewest instances cluster-wide, so a one-node group lands wherever the cluster is thinnest. The guide now says so, the `--availability-zone` flag help says so, and the `create_node_group` audit action records the zone the request asked for, blank included, so whether a group was created pinned is answerable from the audit trail from now on.

[Availability zones →](/guides/ovh-clusters#availability-zones)

## Top-level hostnames on your custom domain now publish through Ankra

With a [custom Ankra domain](/concepts/applications#the-preview-url) registered, the `external-dns` Ankra installs on your clusters can now publish DNS records anywhere under the domain - top-level hostnames like `app.example.com` included - instead of only inside each cluster's `<cluster-id>.<org-id>.<domain>` subzone. Existing clusters are re-credentialed automatically on the reconciler's next pass; there is nothing to do. On the shared `ankra.cc` domain the scope is unchanged: each cluster's external-dns writes only its own delegated subzone, because names directly under `ankra.cc` are shared platform namespace.

## Start and stop clusters from the cluster menu

**Start cluster** and **Stop cluster** now sit in the cluster's **⋯** menu, on the cluster overview and on the clusters list — no more digging into **Settings → General → Danger Zone** to power a cloud cluster on or off. A running self-managed cloud cluster (Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE, HPE Morpheus) offers **Stop cluster**; a stopped one offers **Start cluster**, including the choice to restore everything or the control plane first. Both entries open the same confirmation dialogs as the Danger Zone — stopping still asks you to type the cluster name — and are disabled while another operation is running on the cluster.

[Stopping and starting clusters →](/platform/cluster-settings#stop-cluster)

## Ask Ankra AI from a pull request comment

Mention `@ankraai` in a comment on a pull request in a repository the Ankra GitHub App is installed on, or in a connected Bitbucket Cloud workspace, and Ankra AI answers on the pull request with the diff and the pull request's metadata as its context. Ask it to explain a change, to check a failing pipeline against the diff, or to review the pull request on demand. The mention is matched case-insensitively, anywhere in the comment, and is answered regardless of the draft, branch, and daily-budget rules that gate automatic reviews. On GitHub, Ankra reacts with 👀 the moment it picks the mention up, so you know it is working before the answer lands; Bitbucket Cloud has no comment reactions, so there the answer is the first sign.

In an integration set to **Agent** mode the reply can go further: when the fix is clear, Ankra proposes it as ready-to-apply file changes and, on GitHub, offers to open it as a pull request. On Bitbucket Cloud, where Ankra cannot open one, it suggests a branch name and a commit message instead. **Ask** mode stays read-only.

Mention replies sit next to the automatic **AI review** that runs on every opened or updated pull request, and **PR previews** for applications. All three are switched on per installation under **Organisation settings → Integrations**, with repository rules for the exceptions.

[Ankra AI on pull requests →](/integrations/github#ankra-ai-on-pull-requests)

## A preview domain now tells you it needs DNS, and a demo stops claiming a URL that does not resolve

Fixed: a demo published on your own **Preview domain** reported ready with an `https` URL that had never resolved, and nothing anywhere said why.

Ankra publishes DNS only inside the subzones it delegates. The external-dns credential it provisions for a cluster is scoped to that cluster's own Ankra subzone, so a preview hostname on your domain is filtered out by the DNS provider before a record is written - and the sync goes on logging `All records are already up to date`, because from external-dns's point of view there is nothing in scope. Publishing those records was always yours to do, and that was written down nowhere.

Saving the settings now says so when the domain answers nothing, naming the wildcard to create and the staging cluster's own ingress address to point it at. It also names the consequence for TLS, because the two preconditions were being checked independently and only one of them enforced: an HTTP-01 challenge is answered over the hostname being certified, so an unpublished preview domain costs you the certificate as well as the URL. A domain you have already pointed at the cluster says nothing, as before.

A demo whose hostname does not resolve is no longer reported ready the moment its pods are up. It waits briefly for the name to answer, and is published anyway if it does not, so a domain nobody has pointed still gives you a demo rather than a failure - just not one that claims to be reachable.

The docs now state outright that DNS for preview hostnames is the operator's responsibility when a preview domain is set, and what a working wildcard has to point at.

## Previews on your own domain now get certificates

Fixed: setting a preview domain silently turned off TLS for demos, and there was no way to turn it back on.

Demos published on a staging cluster's own Ankra subzone have always been issued a certificate per preview hostname. Setting your own **Preview domain** stopped that, on the assumption that an organisation bringing its own zone would bring its own wildcard certificate and name it in the **TLS secret** field. That assumption does not survive contact with a stock cluster: ACME issues wildcards only through DNS-01, the ClusterIssuer Ankra's networking stack installs is HTTP-01 only, and Ankra ships no DNS-01 solver for its own DNS provider. The field could not be filled, so demo ingresses carried no TLS and preview URLs quietly came back as `http://`.

Nothing about your own base domain required a wildcard. Each demo's hostname is concrete when the ingress is written and resolves publicly, so the same per-host HTTP-01 challenge completes. Ankra now requests a certificate on both paths, under the same check it already ran: only when the staging cluster carries a verified ACME HTTP-01 ClusterIssuer, so a cluster without one stays on `http` rather than advertising TLS against a certificate nothing will issue.

The new **Certificate issuer** field names a different ClusterIssuer, for a cluster whose issuer is not the one the networking stack installs. A **TLS secret** on its own still means you supply the certificate and Ankra requests nothing.

Where previews would land on plain `http`, saving the settings now says so, in the portal and in `ankra org ai-environment`, instead of succeeding without comment.

## The preview settings are reachable from the CLI

`ankra org ai-environment get|set` reads and writes the preview domain, ingress class, TLS secret and certificate issuer. These are the settings you script when standing up on-demand environments on your own domain, and until now `ankra org domain` covered only the organisation's root domain - a different setting on the same screen with a much wider blast radius. Only the flags you pass are written, and passing one with an empty value clears that field alone.

`ankra org domain --help` now names the preview domain as the separate setting it is, and points to the right command for it.

## Removing a cluster domain now sticks

Fixed: the documented procedure for switching an organisation's Ankra root domain could not be completed. Removing a cluster's domain worked - and then the domain came back, active and under the same name, about fifty seconds later. Since the switch is refused while any cluster domain still lives under the old root, every removal was undone before the next one could be made, and the switch was permanently out of reach.

Two things put the domain back. Ankra treats being an organisation's staging cluster as a standing request for a domain, and it read "this cluster has no domain" as "this cluster needs one" - a removal and a cluster that never had one were indistinguishable. A removal is now recorded as a deliberate act and **held**: nothing re-creates the zone, including the `external-dns` Ankra runs on that cluster, until you ask for it back with `ankra cluster domain <cluster> --enable`. A read reports `Opted out: yes` while the hold stands, so a domain that is gone no longer looks like one that is between passes.

The second was a playground. A playground publishes a wildcard DNS record in the organisation's zone, and that record is reconciled rather than written once - so deleting it only lasted until the next pass. A refused switch now separates the records you can clear from the ones the platform re-asserts, names the writer of each, and names the playground environment to destroy instead. `ankra cluster playground destroy <cluster_id>` is new: the platform has served that call since playgrounds shipped, but the CLI could not reach it.

The refusal also explains itself better on the cluster-domain side, and the docs now answer the two questions that decide whether the switch is safe on a domain you already use:

* **Ankra confines itself to one subzone of the domain you register.** Registering `example.com` creates `<org_short_id>.example.com` and nothing else. Records already published at the apex or under any other name are never read, written or deleted - not by the switch, and not by anything Ankra runs afterwards.
* **A switch never re-labels a zone.** Labels come from the cluster and organisation ids, so a cluster keeps its label across a switch - and with it the `--txt-owner-id` of its `external-dns` and any GitOps path built from it. The TXT ownership registry stays matched to its records, which is what makes a `--policy=sync` controller safe across the change.

[Switching the root domain →](/concepts/applications#the-preview-url)

## Approve or reject any ticket awaiting approval

Fixed: a ticket an agent parked at **Awaiting approval** without a plan - asking for a decision rather than a plan review, such as "needs a capacity decision or an alert threshold raise" - offered nothing to decide it with. The Approve and Request-changes buttons lived inside the Plan panel, which only renders when a plan exists, and the review endpoint refused the verdict outright. Every ticket awaiting approval now carries a decision panel at the top of the page: **Approve** releases the ticket to **Executing**; **Reject** asks for a reason and sends the ticket back to **Planning**, where the agent reads the reason and re-plans. The same panel decides automation approval gates on the run (**Approve** / **Deny**) without a trip to the Inbox, and points at the **Needs your approval** card when the agent is parked on a risky action instead.

## Debugging a broken workload without handing out kubectl

The CLI could read a cluster - fifteen resource kinds, pod logs, metrics, operation steps - but it could not answer the questions a broken workload actually raises. Why is this pod not ready? What did the container that just died print? Which container ate the memory? Each of those ended in a cluster access grant and kubectl through the gateway: broader standing access than the task needed, and outside the record Ankra keeps of everything else.

Four commands close that gap, and none of them needs a grant.

`ankra cluster logs --previous` reads the log of the container instance that terminated. For a pod in CrashLoopBackOff that is the only output with the failure in it, and it was the one log the CLI could not reach. `--previous` is always a bounded read, because the log is closed - it prints and exits rather than waiting on a stream that can never produce another line.

`ankra cluster describe <kind> <name>` answers "why is this not ready?" in one call: the object's conditions, a pod's per-container state with the detail that explains it - CrashLoopBackOff and its exit code, ImagePullBackOff and its registry error, restart counts - and the events whose `involvedObject` is that resource.

`ankra cluster events --for pod/my-pod` scopes an event listing to one object using a server-side field selector rather than filtering a namespace-wide list by name. That is the difference between "the pod is Pending" and "no node matches the nodeSelector".

`ankra cluster top pods|nodes` shows live CPU and memory from the Kubernetes metrics API. `ankra cluster metrics` queries Prometheus, which is the right tool for trends but the wrong one for "which container just got OOMKilled" - and it needs Prometheus to have been installed. `top` reads metrics-server directly, so it works on any cluster that has one.

`ankra cluster logs` also grew `-l <selector>` and `--all-containers`, so a three-replica Deployment is one command instead of a pod listing followed by three invocations, and a stuck pod's init container is read alongside its app containers. Every one of these commands takes `-o json|yaml` and honours `--cluster`, so CI and AI agents parse them instead of scraping tables.

[CLI reference →](/reference/cli/cluster)

## One choice that answers the rest of the form

Some profile inputs only make sense together. Deploying a chat stack on a small GPU or a large one changes the model id, the context length, the memory ceiling and the size of the model store at once - and until now the form asked for each of those separately, so an operator had to know all four answers to change one decision.

A profile author can now give an input **options**, and have each option **set** the others. Pick *Qwen3 32B on an L40S* and the model id, the context length, the GPU memory ceiling and the volume size move together; pick *Qwen3 8B on an L4* and they move back. The choice renders as a card of options above the rest of the form, every input an option answers shows the value it was given and which choice gave it, and typing over one marks it *customised* with a reset that hands it back to the option. A required input an option answers counts as answered.

Nothing about this is specific to GPU sizing: a profile can declare any number of such inputs - model size, storage tier, ingress mode - each driving its own slice of the form. The platform resolves the choice server-side in one fixed order (a value you set, then what the option sets, then the input's own default), so `ankra stack-profiles apply --set model_size=32b` deploys the whole set from the CLI, the AI assistant and Terraform build the same stack from the same selection, and a deployment's recorded parameters are the values that actually deployed. Options are authored on the builder's Inputs tab, where the mistakes publish would refuse show up inline while you edit; `ankra stack-profiles get` lists what every choice sets before you bind anything.

[Choices that set other inputs →](/concepts/stack-profiles#choices-that-set-other-inputs)

## Microsoft Teams catches up with Slack

The Ankra bot has been in Teams for a while, but it could only talk. Every button Slack users had - acknowledging an alert, approving a remediation, confirming a change the AI proposed, picking up an escalated ticket - simply did not exist there, and two of the three commands the app advertised did nothing when you typed them.

Teams now has all of it. Alert cards carry **Acknowledge** and **Snooze 1h**; AI remediation approvals carry **Approve** and **Deny**; a change the AI proposes arrives as a card only the person who asked can decide, and if the cluster moved underneath it the card re-renders with what changed before letting you confirm anyway. An escalated ticket's thread reply carries **Assign to me**, and **Approve plan** / **Request changes** while a plan is awaiting a verdict. A decided card is replaced by its outcome, so nobody acts on it twice. `help`, `status` and `logout` all answer.

Every button runs as your own Ankra user through your linked account, so your role decides what it may do and the audit log records your name.

Alert cards themselves are fixed too. A Teams channel destination with no custom template used to receive Slack's card format, which Teams cannot render - so a production alert arrived as a single line of raw text with no detail and no buttons. Teams destinations now get a proper Adaptive Card with the severity, the resource, the cluster and the actions. Ticket threads stopped rendering Slack's emphasis markers, which Teams reads as italics rather than bold.

## Connecting Teams is one click

Connecting a Teams tenant took five steps: download a zip, sideload it, add the bot, read a claim code out of a chat message, and retype it into a browser.

The bot's welcome card now carries a **Connect to Ankra** button. Press it and the portal opens with the claim code already filled in - press **Connect** and the tenant is bound. Pasting the code by hand still works exactly as it did.

For an admin starting from the portal, the Microsoft Teams card is now a guided setup rather than a list of instructions. It leads with the path that works in every tenant - the app package - as three steps that track where you are: **Download package** (with a copy-link for handing the URL to a Teams administrator), the exact **Apps** → **Manage your apps** → **Upload an app** → **Upload to your org's app catalog** path with a callout for tenants where custom uploads are switched off, and the claim code. Downloading the package and confirming the upload advance the steps, done steps fold up and can be reopened, and **I already have a claim code** jumps straight to the end. Arriving from the bot's welcome card lands on the last step with the first two already ticked. Once a tenant is connected the guide sits behind **Add tenant**, matching Slack's **Add workspace**.

[Connecting Microsoft Teams →](/platform/ai-connections#connecting-microsoft-teams)

## Routing rules you can read before you trust them

An alert firing can reach a destination two ways at once: the alert's own **Notifications** → **Destinations** list, and a routing rule whose Kind covers alert firings. Ankra has always delivered that once, but nothing said so, and the safe-looking move was to detach the destination from every alert - which quietly turns off the delivery you were relying on. It is now documented as a guarantee: **a notification is delivered at most once per destination**, routing rules are netted against the alert's own destinations, and no rule - include or exclude, at any priority - can suppress an alert's own destinations.

Kind is no longer one value. A rule can name a list of kinds, or invert it: "Operation failed and Reconciliation failing, nothing else" is one rule instead of two, and "everything except Alert firing, because alerts already have their own destinations" is one rule instead of ten. Existing single-kind rules and API clients on the old `kind` field keep working unchanged.

And rather than reasoning it out, you can ask. **Preview** on the Routing rules page - and `ankra alerts routes preview` - resolves a hypothetical notification against your rules and lists the destinations it would reach, the ones it would not, and the reason for each, including which rules a **Stop on match** skipped and which deliveries de-duplication dropped. It is a dry run: nothing is sent.

[Notification routing →](/guides/notification-routing) · [Alerts →](/guides/alerts)

## Notification cards fill in, whatever kind they are about

A destination stores one payload template, and that template renders every notification the destination receives. Only alert firings ever filled it in. An operation failure, an agent update, a reconcile failure or an AI insight routed to the same Teams or Slack channel arrived as a title above a column of blank rows - Resource, Type, Job, Cluster and Condition all empty - even when the notification's own title named the failing resource.

Every notification kind now resolves the same variables. `{{resource_name}}`, `{{resource_type}}`, `{{job_name}}`, `{{namespace}}` and `{{condition_type}}` are read from what the notification actually recorded, and `{{cluster_name}}` is resolved for every kind rather than for the five that happened to store it. An alert firing that reaches a destination through a routing rule keeps its condition, its job and a button that opens the firing itself. Where a kind genuinely has no value for a row - a cluster-level alert has no job, an agent update has no condition - **the row is dropped instead of shipping empty**, so the built-in Slack, Teams, Discord and PagerDuty presets are correct for every kind with no editing. If you would rather show something, `{{resource_name|not applicable}}` supplies your own fallback.

The **Test** button now sends the same sample through the same renderer a real delivery uses, with every variable populated - so a template that renders under Test renders on delivery. Testing a routing rule sends the sample as that rule's kind.

[Template variables →](/guides/webhooks#template-variables) · [Empty values and fallbacks →](/guides/webhooks#empty-values-and-fallbacks)

## Demo and preview links are now https

Branch and pull-request demos on a cluster's delegated `ankra.cc` subdomain used to serve plain http, because nothing issued a certificate for that zone. Now, when the staging cluster runs the Ankra networking stack, every demo's ingress requests a Let's Encrypt certificate automatically - so the preview link you share is https, with a certificate browsers trust. This applies across every surface that deploys demos: the portal, the CLI, the AI assistant, and automatic pull-request previews.

[Preview demos →](/concepts/applications#preview-demos)

## Public DNS is visible in the UpCloud create wizard

Every Ankra-provisioned cluster can come up with its own delegated subdomain on `ankra.cc`, with external-dns installed and wired to it - no domain to buy, no DNS provider to configure. The UpCloud create wizard now surfaces this as an **Include Public DNS** checkbox (on by default) beside the networking stack option, so you can see what you are getting and opt out if you bring your own DNS.

[UpCloud clusters →](/guides/upcloud-clusters)

## Clusters that power themselves back on

When something outside the platform stops every server of a cluster - a cloud account running out of credit, a project-wide power action in the provider's console, a facility outage - Ankra noticed within a minute and marked the cluster offline, and then waited for you to press start. The jump host already recovered itself; the nodes doing the actual work did not.

Clusters on Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, and Proxmox now recover on their own. Once a cluster has been offline for five minutes, the platform asks the provider to power every stopped server back on - and only the stopped ones, so a sweep can never reboot a node that is still running. A cluster you stopped deliberately, or one mid-create or mid-teardown, is never touched: recovery only acts on clusters the platform believes should be running.

Recovery is bounded the way you would want it to be. Each outage gets up to three power-on sweeps, spaced out over the first forty minutes; a cluster still dark after that - typically an account that is genuinely out of credit - is left for you, with the outage recorded so you can see exactly what was tried and when. A cluster that keeps losing power repeatedly in one day is also handed back to you, because restarting it clearly is not the fix.

## Metrics and log sources you can write in Git

A cluster's `spec.prometheus_metrics` and `spec.log_source` blocks used to be write-only from the platform's side: Ankra rendered them into the cluster document, but never read them back. Hand-adding either block in Git connected nothing, and because the document is regenerated wholesale from what the platform knows, the block you wrote could later be regenerated away.

Both members now round-trip. Write `spec.prometheus_metrics` or `spec.log_source` into `clusters/<cluster-name>-<cluster-id>/<cluster-name>.yaml` and the next sync connects the source, exactly as the settings page would; edit a field and the next sync updates it. The accepted fields are the ones the platform stores - `endpoint`, `credential_name`, `flavor` and `verify_ssl` for metrics; `provider`, `endpoint`, `credential_name`, `tenant_id`, `index_pattern`, `field_mappings` and `verify_ssl` for logs - and anything else is refused with an error naming the key, rather than quietly dropped.

Credentials stay out of the repository. A `username`, `password`, `token` or `auth_scheme` written inside a source block is refused by name, because ignoring it would leave a live secret in your Git history while you believed it was in effect. Create the credential in the platform and reference it by `credential_name`; a name that matches no credential on the cluster fails the sync instead of connecting a source that queries unauthenticated.

One asymmetry is deliberate: Git can create and update a source, never disconnect one. Deleting the block does not disconnect anything - the source survives and the block is re-rendered on the next push. Disconnecting stays a platform action, in **Settings** → **Data Sources**, because inferring a destructive intent from an absent key is exactly what deleted hand-written blocks before.

[ImportCluster schema →](/reference/importcluster#observability-sources-in-git)

## Add-ons that say who can see them

The add-on catalog mixed everything into one wall of identical cards: charts from Ankra's global catalog, charts from registries your organisation connected, and charts that pull with a credential all looked the same. The only way to tell them apart was leaving the page to check the repository list's **Global** column.

Every card now carries the answer. A **Public** badge marks an add-on from Ankra's global catalog, available to every organisation; **Organisation** marks one from a registry your organisation connected, visible to everyone in it; and a **Private** lock marks a chart whose registry pulls with a credential your organisation added - without ever naming the credential. A curated add-on that mixes public and credential-backed charts says so ("Partially private") instead of overstating either. The same badges follow the add-on onto its detail page, chart by chart.

[Add-ons →](/concepts/addons)

## The stack profile deploy form asks only for what it needs

Using a profile with a lot of parameters meant scrolling a long, flat list to find the few inputs that were actually blank. **Use Profile** now separates the inputs a profile left for you to fill from the ones it already answered, and folds the answered ones behind a single **Show N more inputs that already have defaults**. A profile shipping twenty-four parameters with five blanks opens showing five fields.

A counter tracks how many required inputs are still empty and turns green once nothing is outstanding. Profiles with many parameters gain a search box that matches on name, description, and the addon or manifest an input belongs to.

Every field now names the addon or manifest it writes into, so a profile that declares the same key on two different components - two `api-key` secrets for two different services, say - no longer shows two identical labels.

Secret inputs gained the controls they were missing: **Generate** produces a strong random value for the keys nobody is meant to invent by hand, alongside a reveal toggle and a copy button for the cases where the same value belongs in more than one field. Any input changed away from its default offers a one-click **Reset**.

Hostname inputs fill themselves in. A cluster's public domain is a generated
slug rather than its name, so a profile asking for `chat_host` used to send you
off to find it - gpu-chat's description literally told you to ask the AI. Pick a
target cluster and those inputs now offer **Use cluster domain**, which writes
the hostname the deploy will actually serve on. Switching cluster re-offers the
button rather than rewriting what you typed, so a hostname still pointing at the
previous cluster is visible instead of silent.

The dialog names the profile and version it is about to deploy, pairs the target cluster and stack name on one row, and lets you search clusters by name with each cluster's state shown beside it. Stack names are checked against the naming rules as you type, and the footer says what is still standing between you and a deploy.

[Stack Profiles →](/concepts/stack-profiles)

## Cluster wizards that start on kubeadm and Cilium

Every self-managed create wizard - Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE and Morpheus - opened its Kubernetes step on K3s, so a cluster created with the defaults got the lightweight distribution and Flannel unless you noticed the dropdown. Vanilla upstream Kubernetes was one option down, and Cilium with it.

The wizards now preselect **kubeadm** - upstream Kubernetes bootstrapped with kubeadm and containerd, Cilium (eBPF networking, L7 policies, Hubble observability) as the CNI, and a stacked etcd - and list it first. K3s is still one click away and, when you pick it, the CNI selector behaves exactly as before. The CLI `--distribution` flag and the API keep `k3s` as their default when nothing is passed, so scripted creates are unchanged.

[Kubernetes distribution →](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time)

## See every place a stack profile is deployed

A stack profile could tell you *that* deployments were behind - the update counter has been
there for a while - but not *where*. The list of clusters running a profile lived in a small
panel buried on the overview, with no links, no state, and no way in for a profile that had
never been used.

Profiles now carry a **Deployments** tab: every stack your organisation created from the
profile, with the cluster and stack as links (a never-committed draft links to the draft so
you can finish it), the stack's live state, the profile version it runs, the non-secret
inputs it was instantiated with, and when it was deployed. Rows running an older version
keep the one-click **Update** that pre-fills the update draft with last time's values, and
the overview's stat card now summarises the fleet - how many deployments, on how many
clusters, and whether anything is behind - and jumps straight to the tab.

[See where a profile is deployed →](/concepts/stack-profiles#see-where-a-profile-is-deployed)

## A runnable path to your own Ankra domain

Registering your own domain for Ankra's generated hostnames worked; moving an existing organisation onto it did not. The switch is refused while cluster domains or DNS records still live under the old root - correct, and fail-closed - but the refusal was a single sentence with no list, the portal replaced it with a generic "the request was rejected by the server", and nothing enumerated the cluster domains that were blocking it. Worse, the one command that could tell you a cluster's domain, `ankra cluster domain <cluster>`, was a create: checking a cluster added a blocker to the very migration you were running.

The refusal now names its blockers. The portal lists every cluster domain and DNS record still under the old root beside the **Custom Ankra domain** field, with a link to remove them; the API returns the same list as structured `blocking_cluster_zones` and `blocking_dns_records` members; and `ankra org domain set` prints it along with the command that clears each kind.

`ankra cluster domain <cluster>` is now a read. It reports the cluster's domain, or state `none` when it has none, and creates nothing - enabling a domain is the explicit `--enable`. `ankra org dns zones` lists every cluster domain in the organisation with its state, so you can see what a switch has to clear before attempting one. And the organisation's root domain itself is finally scriptable: `ankra org domain get|set` reads and writes the same setting the portal saves, with `set --default` returning you to `ankra.cc`.

[The preview URL →](/concepts/applications#the-preview-url)

## Your own domain for Ankra previews

Every public hostname Ankra mints - your organisation's delegated DNS zone, each cluster's subzone under it, and the demo and PR preview URLs built on top - hung off a single platform apex: `ankra.cc`. Serving previews under anything else meant bringing your own domain, wildcard DNS, and TLS secret as a demo base domain.

Organisation admins can now register **their own domain** for all of it, dedicated to their organisation alone. Point the domain's NS records at Ankra's nameservers (the ones serving `ankra.cc`), enter it in the **Custom Ankra domain** field under **AI** → **Settings** → **Workspaces**, and every zone and preview URL minted from then on hangs off it - Ankra manages the DNS the same way it does on the platform domain. The save verifies the nameservers up front and refuses a domain another organisation already holds, so a typo or an unhosted domain can never tear down a working zone. Zones you already have keep the domain they were provisioned under; after a switch, Ankra tears down the organisation zone and re-creates it under the new domain automatically.

The switch fails closed on purpose: while cluster DNS zones or manual DNS records still live under the old domain, the save is refused with a message naming exactly what to remove first - nothing is torn down behind your back. To make that removal possible, clusters can now opt **out** of their generated domain as well as in: `ankra cluster domain <cluster> --remove` (or `DELETE /api/v1/clusters/{cluster_id}/dns-zone`) hands the zone back for teardown, and the plain command re-enables it under the organisation's current domain.

[The preview URL →](/concepts/applications#the-preview-url)

## Teams channels you pick like Slack, and alert routing you can script

Slack has had it for a while: install the app, pick a channel, done. A Teams destination still meant leaving Ankra for Power Automate, building a flow, and pasting a signed URL back. The bot was right there in the AI gateway, answering chat and posting notifications - it just was not wired to alerts.

Now it is. Once the Ankra AI bot is in a team, the destination form swaps the URL field for a **channel picker** listing every team the bot has been added to, and the bot posts the Adaptive Card itself - no flow, no URL, and the same picker on edit. Add the bot to a team and its channels appear; remove it and they leave.

The other half of the same complaint was that alert routing lived only in the browser: no CLI, no API token access, nothing you could keep in Git. Destinations and notification routes now answer to a personal access token, and the CLI grows **`ankra alerts destinations`** (`list`, `get`, `create`, `update`, `delete`, `test`, `test-url`, `channels`) and **`ankra alerts routes`** (`list`, `create`, `update`, `delete`, `test`), all honouring `-o json` and `-o yaml`. Updates send only the flags you pass, so a route you touch keeps everything else as it was.

[Connecting Microsoft Teams →](/platform/ai-connections#connecting-microsoft-teams) · [Managing destinations from the CLI →](/guides/webhooks#managing-destinations-and-routes-from-the-cli)

## A Microsoft Teams bot you can install, and Teams alert cards that keep their buttons

The Microsoft Teams connection card asked for a claim code "the bot shows when it is first added" - but offered no way to add the bot. Ankra AI is not in the Teams app store, the card carried no app package, and the docs said only "add the Ankra bot". The connect flow dead-ended on its first step.

The card now walks through the whole path: **Download the Teams app package** hands you the app manifest and icons as a `.zip`, built on demand with the deployment's own bot identity, ready to upload in Teams (**Apps** → **Manage your apps** → **Upload an app**) or for a Teams admin to publish to your organisation's catalog. Add **Ankra AI** to a team, paste the claim code it posts, and the tenant is bound.

The webhook path into Teams got the same treatment. The built-in Teams payload template was a legacy **MessageCard** - a format Microsoft retired with O365 Connectors. Delivered through a Power Automate (Workflows) webhook, the flow reports success while Teams silently drops every button, so cards arrived with no **View Alert**, no **Acknowledge**, and a broken logo from a host that no longer resolves. The preset is now a severity-tinted **Adaptive Card** whose buttons actually render, alongside a new `{{severity_style}}` variable (Adaptive Cards cannot consume a hex colour), and pasting a `logic.azure.com` Workflows URL now auto-selects the Teams preset.

Three quieter fixes ride along: `{{severity_color}}` is substituted on real deliveries (it previously resolved only for the **Test** button, so production cards shipped the literal placeholder), an alert with an empty name falls back to its rule name instead of rendering a bare "Alert:", and test deliveries no longer strip the `attachments` envelope that Teams cards live in. The template-variable list also stopped advertising a one-click snooze link that never existed.

[Connecting Microsoft Teams →](/platform/ai-connections#connecting-microsoft-teams)

## A force mode that reclaims leaked cloud volumes and load balancers

Stopping or terminating a cloud cluster released its servers, network, and gateway, but never the storage volumes its workloads had provisioned through the CSI driver, and a load balancer could survive teardown too. The disks sat detached in the account and kept billing: on one of our own UpCloud accounts, 76 orphaned volumes were 83% of the monthly spend before anyone noticed. OVH and DigitalOcean leaked the same way, and Hetzner had the opposite problem: it always deleted the volumes, so a stopped cluster restarted with empty storage.

Stop and deprovision now take a force mode on every affected provider. `ankra cluster <provider> stop --force` and `ankra cluster deprovision --force` (or `?force=true` on the API) delete the cluster's CSI volumes and load balancers along with the rest of its infrastructure, on UpCloud, Hetzner, OVH, and DigitalOcean; on Scaleway, `--force` overrides a `retain` retention policy. Ankra records which volume IDs belong to the cluster before tearing anything down, so the sweep deletes exactly those disks and nothing else in the account, and a cluster that was stopped earlier without force can still be cleaned up by a forced terminate afterwards.

Without the flag a plain stop keeps your data so the cluster can come back, and a plain deprovision leaves the volumes for you to reclaim later. On Hetzner that is a deliberate change: it used to delete the volumes on every stop. A forced stop destroys the data on those volumes, and the CLI says so before it asks you to confirm.

[UpCloud clusters →](/guides/upcloud-clusters#stopping-and-starting-a-cluster)

## AI settings on every application

Which Ankra AI lanes ran on a repository was an organisation-wide decision, taken in a grid of repository rules on the Integrations page. Silencing the pull request review on one noisy repository, or pointing one repository's review at a larger model, meant leaving the application you were looking at and finding its repository among every other repository the Ankra GitHub App can see.

Every application now has an **Ankra AI** panel under **Settings**, with one card per lane Ankra AI can run on its repository: the pull request review, a branch code review, an Actions review, the organisation skills review, and the demo URL that comments a live preview on every pull request. Each card carries the lane's own model, branch scope, ignored paths, what it does when it finds something, and a daily run and input budget - and is labelled **Inherited** or **Overridden**, so it is always clear whether you are reading your organisation's default or this repository's own decision.

Overriding is per lane and reversible. A lane you do not touch is not written at all, so an organisation admin goes on steering every application that has not opted out; **Reset to organisation default** returns one lane, and **Follow organisation for everything** drops the application's override completely. Nothing here is a second store: every write lands in the same per-repository rows the AI gateway already resolves when it gates an event, so the panel and the Integrations page cannot drift apart.

Two lanes are visible but not running yet - the branch **Code review** and the **Actions review** cards describe what they will do with their switches disabled, rather than offering a toggle that silently does nothing. On the pull request review, **Propose a fix** is likewise stored and not acted on yet, and the card says so. One limit worth knowing: the settings are keyed by repository, so two applications connected to the same repository share one set of lanes.

[Application AI settings →](/platform/application-ai)

## Demo routing you can declare, and a registry you can change your mind about

A monorepo demo deploys every component, picks the frontend-shaped one to own the demo URL, and publishes the API-shaped one under `/api`. Good guesses - but only guesses, and the lanes with no human in the loop had no way to correct them: an automatic pull-request preview and an AI-launched demo both take the heuristic or nothing. An application whose component names read differently got a preview URL serving a UI whose API calls all 404'd, with a working API sitting unrouted in the same namespace.

Demo routing is now something you declare once. Name the component that owns `/` and the path prefixes the others are published under, and every lane follows it - the launch dialog, the CLI, the automatic PR previews, and the AI tools alike. A declaration is authoritative, so the `/api` guess stops running and a component you leave out stays reachable in-cluster only instead of picking up a path it never asked for. Per-launch overrides still win, and clearing the declaration returns everything to the heuristics.

The AI's `deploy_pr_demo` also stopped under-reporting what it did: its answer now names the entry component and lists every workload it provisioned with that workload's own image, container port and published path, rather than a single image describing whichever component happened to own the URL.

Alongside it, **the image registry an application publishes to is no longer fixed at create time**. An organisation that runs its own registry could declare it when onboarding an application and never again - so an application already connected to Ankra kept being reported as never built while it published healthily to a registry Ankra simply could not see. Settings now carries an **Image registry** panel, and the CLI grows `ankra application registry get`, `set` and `clear`. All three report the host and project the declaration resolves to and the image repository each component is expected to publish to, so you can check the coordinates against where your builds actually push before wondering why readiness disagrees.

Finally, a demo migration command now runs with your image's working directory on `PYTHONPATH`. Python resolves imports against the *script's* directory rather than the working directory, so a migration entrypoint that is a script - `python scripts/bootstrap_database.py` - could not import the application package sitting beside it and died at import.

[Preview demos →](/concepts/applications#preview-demos)

## An UpCloud create wizard that can find the right plan

Since the Ankra-managed UpCloud wizard started reading UpCloud's live catalogue, its plan pickers rendered all 174 plans as flat walls of tiles - three of them on one page, one each for the bastion, the control plane, and the workers - with no search, no filters, ordering that put `12xCPU` before `1xCPU`, and roughly forty discontinued series mixed in as if they were current. The 15 datacenter zones stacked as another full page of radio rows.

Each picker is now the same plan browser the other provider wizards use. It opens on a one-line summary of the plan already selected; below it sit a search that spans every category, family tabs (Starter, Premium, Cloud Native, GPU, GPU Spot), vCPU quick filters, and a sortable table for the long tail. Discontinued series live behind a **Current plans / Legacy** toggle instead of dominating the page, and plans order smallest-first.

Zones are grouped by region - Europe, North America, Asia-Pacific - as compact cards, and Helsinki #2 carries a badge for being the only zone stocking GPU plans today. Pick a GPU plan while another zone is selected and the wizard warns that the create is likely to fail at server creation, instead of letting you find out ten minutes in. The cost estimate also stopped pricing plans it has no published figure for at \$0 - it shows a dash and notes the total covers priced items only.

## An AI chat that acts on your defaults

Agent-mode chat used to interrogate you: which credential, which zone, what name, which sizing, in what order - round after round of multiple-choice before any work happened, for choices that all had sensible defaults. Agent mode now acts on those defaults and states each assumption in one line ("Using namespace `monitoring` - say the word to change it"), reserving questions for decisions that are genuinely yours: destructive changes, real money, or an ambiguous goal. When it does ask, it asks once - every needed decision batched into a single question block.

The same overhaul grounds the answers better. AI Insights the assistant cites now carry a freshness marker, so a diagnosis no scan has confirmed recently gets re-verified against live state instead of being repeated as fact. Chart-configuration lookups always return readable, navigable data - when a chart's options run long, the assistant gets a trimmed view with named paths it can drill into, never cut-off text. And the assistant can look up your organisation's preview domain from any conversation, so the public URL it proposes for a new service is on a domain that will actually resolve.

[AI Assistant →](/platform/ai-assistant)

## Additive deploys that can run themselves

With the chat's autonomy setting on **Auto**, a stack deploy whose change set removes nothing - new add-ons, new manifests, configuration changes to what is already there - now executes immediately with a receipt carrying its full bill of materials, instead of stopping at a confirmation card. The bill of materials is generated and validated before anything runs; if validation fails, or the same deploy would remove or replace a deployed add-on or manifest, the confirmation card comes back exactly as before. Cluster create, scale, upgrade, stop, and delete are pinned to always ask, whatever the setting - cost stays a human decision - and writes into protected system namespaces such as `kube-system` remain refused outright.

Autonomy is off unless you turn it on. Every conversation starts on **Manual** - every write confirmed, exactly as before - the setting is per conversation, and it appears once AI autonomy is enabled for your organisation. It is also not the **Auto** in the model picker, which only routes between models. Every auto-approved action lands in the conversation as a receipt and in the audit log with its autonomy attribution, so what ran, and why it was allowed to, is always reconstructable.

> [!WARNING]
>
> On **Auto**, a validated additive stack deploy applies to your cluster without a human click in between. Switch it on for conversations where you want that speed; stay on Manual where every change should be gated.

[AI Assistant →](/platform/ai-assistant#autonomy-manual-or-auto)

## Chats that follow the cluster they created

Ask the AI to build a cluster and the conversation now follows it: when the create you approved goes through, a conversation that wasn't already scoped to a cluster is scoped to the new one - so once provisioning finishes, designing stacks, deploying workloads, and reading live state carry on right there, with no more "no cluster selected" from the conversation that did the selecting. Long provisioning runs also stopped crying wolf: the live tracker now gives a cluster build the time it actually takes - 40 minutes, up from 15 - and when it does hand off, it says the build is still in progress rather than calling it a failure. And a failed action no longer strands the conversation mid-flight: the portal now waits for the session to finish its turn before delivering the follow-up that explains what happened, instead of dropping it.

[AI Assistant →](/platform/ai-assistant)

## Drafts that are never replaced in silence

Designing a new stack while another draft was in progress used to overwrite the previous draft without a word - finished work, gone. A replaced draft is now retired with a full audit trail instead of silently overwritten, and the chat tells you exactly what happened and which draft it replaced, with guidance to deploy or discard a finished draft before starting the next one. Namespaces behave too: the namespace you ask for is the namespace you get, per-chart overrides are supported, and moving a deployed add-on between namespaces from chat now works - the AI can supply the migration strategy the engine requires instead of dead-ending.

[AI Assistant →](/platform/ai-assistant)

## Stack profiles you can run before you deploy

A stack profile could only be tried by instantiating it onto a real cluster. Reviewing a new version, checking a public profile before adopting it, or showing a colleague what a stack actually deploys all meant putting it somewhere real first.

A profile now has a **Demos** tab of its own. Launch one and Ankra installs the profile's add-ons and manifests into a throwaway, quota-bounded namespace on your organisation's staging cluster - the same lane branch demos have always used - on a timer that deletes it when it runs out.

The details view reads the namespace live: how far the stack got, every object it installed with its manifest, the namespace's Kubernetes events, and a log tail from any pod. A chart that fails to install reports its own reason ("no matching PVC storage class"), not a generic failure. A profile demo deploys no application of its own, so there is no image or routing step to sit and wait on - the stack finishing is what makes it ready.

One demo runs per profile: launching again replaces it rather than stacking a second copy on the staging cluster, so relaunch is how you pick up a new version or changed parameters.

The two demo lists are now tied together. An application whose demo settings designate a stack profile shows that profile in its **Demos** tab, along with the profile's own live demos and a link straight into each - the stack is often already running, and launching a whole application demo just to look at it wastes staging capacity. The profile's tab lists the applications designating it, from the other side.

Everything is available to the CLI too, under `/api/v1/org/stack-profiles/{profile_id}/demos`.

## Availability zones for OVH clusters

An OVH cluster in a 3-AZ region such as `EU-WEST-PAR` put every node in the same availability zone, control plane included, and there was no way to ask for anything else. Nothing in the create path could carry a zone, so OVH chose one and used it for the whole cluster.

You can now spread a cluster across the zones of a 3-AZ region, and pin a node group to one zone:

```bash theme={null}
ankra cluster ovh regions --credential-id <ovh-credential-id> --with-zones

ankra cluster ovh create --name my-cluster --region EU-WEST-PAR \
  --availability-zones eu-west-par-a,eu-west-par-b,eu-west-par-c \
  --control-plane-count 3

ankra cluster ovh node-group add <cluster-id> --name database-par-a \
  --instance-type r3-128 --availability-zone eu-west-par-a
```

Control planes and etcd spread per role, workers per node group, and every day-2 path - node group add, node group scale, worker scale, control plane growth - balances new instances around where the existing ones already are. Spreading needs at least 3 control planes, because fewer cannot hold etcd quorum through the loss of a zone; the create is refused rather than promising fault tolerance it cannot deliver.

Every OVH node now also carries the standard `topology.kubernetes.io/zone` and `/region` labels, taken from the zone OVH reports for the live instance rather than the one that was requested. That makes them correct on clusters created before any of this existed too - Ankra records the zone the next time it reads the instance, and `ankra cluster reconcile <cluster-id>` applies the labels without waiting for a change to trigger a sync.

> [!WARNING]
>
> OVH High Speed block storage is zonal: a volume is replicated within one zone and cannot attach from another. A single database pod with one PersistentVolume is not zone-fault-tolerant however the nodes are spread. Zone tolerance needs replication at the application layer, one replica and one volume per zone. The default StorageClass on OVH clusters is now `csi-cinder-sc-topology`, which binds `WaitForFirstConsumer` so a volume is not bound before its pod is scheduled.
>
> Placing that volume in the pod's own zone is a separate mechanism, and it is not live: the Cinder CSI provisioner's Topology gate is off on OVH, because OVH Block Storage rejects the compute zone names the gate forwards. Volumes are created in Cinder's default zone with no zone affinity on the PersistentVolume, on every class. Keep each stateful replica on a node group pinned to one zone until that changes - see [zone tolerance needs more than node spread](/guides/ovh-clusters#zone-tolerance-needs-more-than-node-spread).

New OVH clusters also stop installing k3s's bundled local-path provisioner, which marked itself the default StorageClass alongside the cinder one. Two defaults left the class an unqualified PersistentVolumeClaim resolves to undefined, and resolving to local-path put the volume on a single node's disk with no replication. Existing clusters keep local-path untouched, since removing a StorageClass would orphan any volume already bound to it - name the class you want explicitly there rather than relying on the default.

[Availability zones →](/guides/ovh-clusters#availability-zones)

## A publish flow that explains itself

Publishing to a catalog was three different screens depending on what you were publishing, and each of them failed late. Publishing an application was four unlabelled text boxes; if the version was already taken, or the application was not publishable at all, you found out after submitting.

Every publish flow is now the same shape: check, review, confirm. Before anything is submitted you see what will be published, where it lands, and - the useful part - **why it cannot be published, if it cannot**. Publishing an application now starts from Ankra's readiness check, which has always existed but never had anywhere to appear: a missing image registry declaration is reported up front, with a **Fix automatically** button where Ankra can resolve it for you.

A version that is already published is refused inline, before anything is snapshotted, instead of coming back as a conflict after submitting.

[Publishing applications as add-ons →](/platform/application-addons) · [Publishing add-ons →](/platform/addon-publishing)

## Version history for published applications

A published application listed its versions as a flat row of numbers. It now has a history: each version carries a **changelog** you write at publish time, who published it, and a **Compare** against the version before it.

Comparing shows which manifest files were added, removed or modified with their contents side by side, and - separately - which **deploy options** changed. That distinction matters: options are the add-on's install-time contract, so changing one is a breaking change for anyone who already installed it. A version that starts or stops referencing an environment `Secret` is called out for the same reason.

Existing versions keep working unchanged; those published before changelogs simply have none.

[Version history →](/platform/application-addons#version-history)

## Catalog publishing now checks who is asking

Proposing an add-on to the global Ankra Catalog puts your organisation's name on a pull request against a public repository, and once merged the entry is visible to every organisation. It now requires the **Manage Helm registries** permission, held by organisation admins and owners. Members and operators can still open the flow and review exactly what would be proposed - they just cannot submit it, and the flow says so on the first step rather than failing at the end.

Ankra also screens the rendered manifest before it can be proposed, refusing credentials embedded in a URL and recognisable provider tokens, naming the field so it can be corrected. A pull request is effectively permanent: a credential that reaches a public repository is in its history even if the branch is later closed.

[Publishing add-ons →](/platform/addon-publishing#who-can-publish)

## Applications can publish to a registry you already run

An Application's container images went to your organisation's private Ankra registry, and there was no way to say otherwise. If you already operate a registry - often the same Harbor whose OCI charts Ankra indexes for you - your images existed, they were simply not where Ankra looked. Publish readiness reported "no image has been pushed yet" indefinitely while the application ran healthily from the registry it actually uses, and the deploy gate stayed shut behind an artifact that was never going to appear.

An Application can now declare the registry it publishes to, pointing at a registry credential Ankra already holds:

```json theme={null}
"image_registry": {
  "url": "oci://artifact.example.com/commerce-images",
  "credential_name": "example-harbor-pull",
  "pull_secret_name": "harbor-registry",
  "username_secret_name": "HARBOR_USERNAME",
  "password_secret_name": "HARBOR_PASSWORD"
}
```

Everything downstream follows it: the generated workflow pushes there and logs in with the secret names you gave, publish readiness verifies the tag **in that registry** with the credential you named, the deploy gate and image listings probe it, container scanning reads its tags, generated Deployments reference the pull Secret you named, and Ankra creates that Secret in the deploy namespace from the same credential. One credential serves chart pull, image pull, and readiness.

On a monorepo, a component may declare its own registry - apps that live in different projects with their own robots and retention rules are addressed individually.

**Ankra does not mint robots for a registry you operate.** Setup names the two Actions secrets the workflow reads and leaves them to you, rather than writing a credential Ankra happens to hold over a push robot you administer. Readiness reports whether they exist; `manage_actions_secrets: true` opts back in.

[Using your own registry →](/concepts/applications#using-your-own-registry)

## Pull request builds no longer publish images

The generated workflow ran on `pull_request` with `push: true`, so a build from unmerged code published an image - into a registry whose retention and tag-immutability rules are governed elsewhere, tagged as though it were a real build.

Pull request runs now build and scan the source without pushing. The image scan follows the push, so it runs on branch builds, where there is an artifact to pull back and scan.

## GitOps status now shows the repository it actually read

`ankra cluster gitops status` and the cluster's GitOps settings reported the repository Ankra has **stored** for a cluster. A sync now records the repository, branch and provider it actually read, and the status answer carries it as `observed_source` alongside a `source_mismatch` flag. If the two ever disagree, you can see it rather than having to infer it by comparing commits across repositories.

Underneath, the cause of that disagreement is gone. A cluster could end up carrying more than one GitOps repository record, and different parts of the platform picked different ones - so a cluster could sync from one repository while reporting another. Applying a cluster definition now leaves exactly one active record, and the sync loop and the status view resolve it the same way by construction.

Repointing a cluster through `spec.git_repository` works as documented, including onto a **non-default branch**: one repository with a branch per environment is a supported layout.

> [!WARNING]
>
> Repointing prunes what the new source does not define, PersistentVolumeClaims included. Diff the two sources over the cluster's directory before you apply.

[GitOps →](/concepts/gitops) · [ImportCluster reference →](/reference/importcluster)

## A credential check that counts every cluster

Before replacing or deleting a GitHub credential, `get_github_credential_usages` tells you what depends on it. It was only counting **imported** clusters, so any cluster Ankra provisioned - on DigitalOcean, Hetzner, OVH, UpCloud, GKE, EKS, AKS and the rest - was missing from the answer. Acting on that count, you could revoke a credential that a live GitOps sync was riding.

Every cluster is now counted, whoever provisioned it. The response also separates `usage_count` (clusters) from `application_count` (Applications built from the credential's repositories) and adds `dependent_count` for the total, and a credential name shared by more than one credential now returns the full superset instead of an empty answer.

## Repository pickers that follow the credential you chose

In a cluster's **Settings → GitOps**, changing the credential left the repository selection pointing at the previous credential's repository, and **Sync Repositories** refreshed the credential you were replacing rather than the one you had just picked. Moving a cluster to a repository under a different GitHub organisation could not be completed.

Choosing a different credential now clears the repository so you pick one the new credential can actually see, and syncing follows your current selection.

## Prerelease chart versions now validate

`ankra cluster validate` could reject a `chart_version` that was deployed and running - typically a CI-published prerelease such as `0.1.6-ci-ankra-pipeline`.

Prereleases were never excluded from indexing. The real cause was tag pagination: Ankra stopped reading an OCI repository's tags after the first page unless the registry sent a `Link: rel="next"` header, which not every registry does. Charts with many tags therefore lost their newest versions from the index, and a pin `validate` was asked about could never resolve. Ankra now pages through every tag, and reports a truncated listing instead of indexing a partial one.

The error also stops pointing at the wrong thing: it now says the version is not **indexed**, and suggests re-syncing the registry.

## A playground for every organisation

The **playground** - a real, writable Kubernetes environment Ankra provisions for you - is now available to every organisation. There is nothing to enable and nothing to install: click **Start playground** in the create-cluster dialog, and a couple of minutes later you have a cluster with the Ankra agent already connected.

It is a genuine cluster, not a simulation. Each playground is a [vcluster](https://www.vcluster.com/) with its own API server, isolated per organisation, running on Ankra's infrastructure. Deploy stacks through the normal pipeline, browse live resources, stream logs, open a terminal, and ask the AI to build things - all before you connect a cluster of your own. One per organisation, expiring after a few days of inactivity, with a heads-up before it goes.

Organisations created before this change may still see a `sandbox-demo` cluster. It keeps working, but its deploys are simulated rather than run on real infrastructure - start a playground for the real thing.

From the terminal:

```bash theme={null}
ankra cluster playground create
ankra cluster playground status <cluster_id>
```

[Playground →](/guides/cluster-sandbox)

## An agents page that shows who needs you

The **AI Agents** overview now tells you where your fleet stands without opening every agent. Each row carries a status chip for the agent's latest run - **Needs your input**, **Blocked**, **Failed**, **Working**, **Goal met**, or **Never run** - plus the run's outcome summary, and a call to action that matches the state: **Respond** jumps straight into the chat conversation a parked agent is waiting in, **Review** opens a blocked or failed run's transcript, **View live** follows a run in flight, and **Run now** dispatches an agent that has never run.

Agents waiting on a person sort to the top, a summary strip counts and filters them, and finished one-off missions fold away under **Completed missions** so old dispatches stop burying the live ones. The sidebar's **AI Agents** item now badges the number of agents waiting on your input - an unanswered agent question is no longer something you discover by accident.

[AI Agents →](/platform/ai-agents)

## A new default AI model

Ankra AI now runs on **Kimi K3** by default, with **GLM 5.2** as the Think tier. Both are served through Ankra's managed access - there is nothing to configure, and existing conversations carry on unchanged.

| Tier | Model | Context |
| - | - | - |
| **Expert** (default) | Kimi K3 | 1M tokens |
| **Think** | GLM 5.2 | 1M tokens |
| **Quick** | Claude Haiku 4.5 | 200k tokens |

Both new tiers carry a **1M-token context window**, up from 200k, so long troubleshooting sessions and large manifests fit without compaction. Expert accepts images and reasons before it answers; Think reasons at high effort on text. **Auto** still picks per question, and sends anything with an attachment to Expert.

Reasoning is now visible on these models the same way it always was on Claude - you see the thinking as it streams, not just the answer.

None of this is a limit. Under **AI** → **Settings** → **Models** you can still edit any tier, point it at your own model, or switch the whole organisation onto your own Anthropic, OpenRouter, or self-hosted OpenAI-compatible key - which serves every tier from your provider instead.

[AI Provider →](/platform/ai-provider)

## Monorepo demos deploy every app

A demo of a monorepo used to run exactly one of its components - so a two-app repository demoed its API where the frontend belonged, and the preview URL answered with a bare JSON 404. Demos now deploy **every component of the application by default**, each as its own pod in the demo namespace, and the demo only reports ready once all of them accept connections.

The **web entry** - the frontend-shaped component - owns the demo URL, and the API component is published under `/api` on the same host, routed straight to its own service, so the browser reaches both halves without the app needing environment-specific proxy configuration. Components also reach each other in-namespace by name (`http://crm-api:8090`), and demo env values can reference `${{ ankra.demo_component.<name>.url }}` placeholders that resolve at deploy time.

The launch dialog now shows each component's build status and tag side by side, lets you include or exclude components, and lets you move the entry. The demo detail page groups the bill of materials per component and lists each component's public path next to the preview URL. Automatic PR previews and the AI's `deploy_pr_demo` tool deploy every component the same way - and PR previews of monorepos, which previously always reported "build missing", now resolve their images correctly.

[Applications → Monorepo demos →](/concepts/applications#monorepo-demos-every-component-one-url)

## Demos that run any codebase

Launching a demo of a real application used to fail in three quiet ways: the readiness probe watched a port the app never listened on, a database-backed app crashed with no database, and a fresh database had no schema. All three are now handled end to end.

**Ports resolve themselves - twice.** The launch resolves the container port from what the repository actually declares (recorded component ports, the runtime Dockerfile's `EXPOSE`, the generated Deployment manifest, the analysed target port), and the launch dialog no longer overrides that resolution with a default. And when the artifacts themselves are wrong, the platform reads the running container's own startup banner - `Accepting connections at http://localhost:8001` - and repoints the demo at the announced port on the fly, once, recording the correction so the next launch is right from the start. A demo that still times out now tells you exactly what happened: *"Nothing accepted connections on port 3000. The container's logs say it listens on port 8001."*

**Databases arrive configured.** Analysing a repository now detects a database dependency - a Postgres client, an ORM config, a composed database - and seeds the demo configuration: throwaway database on, the connection variables the code actually reads wired to `${{ ankra.demo_database.* }}`, and the repository's migration command. Demos run migrations as an init container inside your own image, after the database accepts connections, so a fresh demo database provisions its schema before the first request. Schemas needing Postgres extensions declare them (`database_extensions: ["vector"]`) and the database creates them at initdb.

**And the CLI can drive all of it.** `ankra application demo detail` shows the provisioning steps and failure detail, `demo logs` fetches a bounded log tail, `demo config get/set` edits the saved defaults - environment, database, migration command, extensions - and `demo fix` dispatches the pre-setup agent, which now also repairs failed migrations and wrong ports.

[Applications → Preview demos →](/concepts/applications#preview-demos)

## Create applications on a branch that actually exists

The **Create application** form no longer asks you to type a branch name into a free-text field and hope. Once you pick a repository, the branch field becomes a searchable list of the repository's real branches with its default branch preselected - and **Enter a different branch** stays one click away for a branch you have not pushed yet. If your organisation has a single GitHub App installed, it is selected for you, and repository search now ranks an exact name first instead of last.

The form also spells out what **Create** will do before you commit to it: an AI agent analyses the repository and generates a Dockerfile, CI/CD pipeline, and Kubernetes manifests where they are missing, opens a setup pull request for you to review and merge, and publishes container images to your organisation's private registry.

[Applications →](/concepts/applications)

## Publish your add-ons to the whole platform

An add-on your organisation curated can now be proposed to the global Ankra Catalog - the add-on catalog every organisation sees. **Publish to Ankra Catalog** on the add-on's page shows exactly what would be proposed: the rendered `kind: Addon` manifest, a diff against the currently published version when one exists, the target repository, and a version-history link into the catalog's Git log. Confirming opens a pull request against the public [ankraio/ankra-global-resources](https://github.com/ankraio/ankra-global-resources) repository on your behalf - review and merge is the approval gate, so nothing ships silently.

A **Publish history** section then tracks each request through its life: pull request open, merged and awaiting sync, live in the catalog, or closed - with the pull request linked at every step. Once merged, the platform sync ingests the manifest and the add-on appears for **all organisations**; your own organisation's copy keeps shadowing the global one, so publishing never changes what you see. The catalog repository itself gained the new `Addon` manifest kind alongside its Helm registries, and removing a manifest retires the global add-on again.

[Publishing Add-ons →](/platform/addon-publishing)

## Every manual cluster action, on the record

Cluster **Settings** grew an **Audit** tab: a chronological trail of every manual action performed on that cluster - who did it, what it was, and when. Starting, stopping, upgrading, or terminating a cluster, scaling workers or the control plane, creating, editing, or deleting node groups, restarting a node, resizing the bastion, deploying, updating, redeploying, retrying, or deleting stacks, and agent-side Helm upgrades and rollbacks all now write attributed entries - the acting member's email, the resource touched, the timestamp, and expandable structured details such as the previous and requested counts of a scale.

The tab is the per-cluster view of the organisation [Audit Log](/guides/audit-log) and shares its permission gate: audit read, held by owners and admins by default and grantable to custom roles. Entries are append-only, so the answer to "who scaled this cluster last Tuesday?" is one click away instead of an archaeology exercise. And when a stack edit results in a GitOps commit, the entry links straight to it - the platform action and the repository change it produced, side by side.

[Cluster Settings → Audit →](/platform/cluster-settings#audit)

## The cluster trail and the organisation trail now join up

The organisation [Audit Log](/guides/audit-log) and a cluster's **Audit** tab always read the same record, but you could not travel between them. Now every organisation entry names the cluster it belongs to, and that name links straight into the cluster's own tab; organisation-level events such as sign-ins and invitations show no cluster, and a cluster you have since deleted keeps its name marked deleted, because the record outlives the cluster. A **cluster** filter joins the existing user, action, and date filters, and it lives in the page URL, so "everything anyone did to this cluster" is a link you can share.

From the other side, the cluster tab gained **View in organisation audit log** - the full trail with that cluster preselected - plus **Export CSV** and **Export JSON** for the cluster's own entries. Exports run through the organisation export narrowed to the cluster, so a per-cluster download and the filtered organisation view can never disagree, and every exported row now carries the cluster next to the actor and action.

[Audit Log →](/guides/audit-log)

## Stop and start clusters on a schedule

Every self-managed cluster - Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE, and HPE Morpheus - can now park itself. A new **Power schedules** card in cluster **Settings** → **General** holds up to 20 schedules per cluster, each one a stop or a start that fires either once at a chosen date and time or repeatedly on a 5-field cron expression in the timezone you pick. The classic pair - a `0 19 * * 1-5` stop and a `0 7 * * 1-5` start - shuts a development cluster down on weekday evenings and has it back before the team arrives, so it only accrues compute cost while someone is using it.

Schedules are careful about cluster state: a stop is skipped if the cluster is already stopped, a start only fires when it is stopped, and if the cluster is busy with another operation the schedule retries every 5 minutes for up to 24 hours before recording a failure. Each schedule shows its next run and last outcome, and a toggle pauses it without deleting it.

[Power Schedules →](/platform/cluster-power-schedules)

## Credentials that show what you have left

Open a cloud credential and the detail page now reads capacity straight from the provider - and it works for every cloud provider Ankra supports. A Proxmox VE credential shows the cluster behind it: every node with used and total CPU and memory, storage pools with shared pools counted once, and how many guests are running with the vCPUs and memory allocated to them. An UpCloud credential shows the account's real resource limits - cores, memory, storage, IPs, networks, load balancers - as usage bars, next to remaining credits. OVHcloud shows its true per-region project quotas the same way: vCPUs, instances, memory, and volume storage per region, each with how much of the quota is spent. Azure shows the subscription's virtual machines and AKS clusters with regional vCPU and VM quota bars, and DigitalOcean shows droplet and floating IP limits. HPE Morpheus shows each cloud on the appliance with used and total memory and storage. Hetzner and Scaleway expose no limits over their APIs, so their views are live usage reports: servers with combined vCPUs, memory, and storage, plus the networking resources around them.

The numbers come from the provider at view time, so they include everything in the account, also what was created outside Ankra. Capacity questions like "will another three workers fit?" get answered on the credential page instead of in the provider console.

[Credentials →](/platform/credentials#capacity-and-usage)

## A calmer credentials page

The credentials surface got a visual and structural cleanup. The list page now has a single quiet toolbar - search, provider filter, sort, and paging in one row - and flatter cards that keep to the essentials: provider, type, health, and when the credential was last updated. The credential detail page, which had grown into one long scroll of identity, capacity, connection details, rotation, and usage all at once, is now a compact identity header with tabs: **Overview** for connection details and the verify check, **Capacity** for the provider report, **Used by** for the clusters and operations on the credential, and **Rotation** for in-place secret rotation. Each tab loads its own data, so opening a credential no longer fires every provider query at once, and the layout now matches the GitHub credential cockpit, so every credential detail page reads the same way.

[Credentials →](/platform/credentials#view-credentials)

## The Ankra CLI adds Proxmox, Morpheus, and control over agent runs

[Ankra CLI v0.9.0](/integrations/ankra-cli-changelog) is out, and it is the largest CLI release so far:

* **Proxmox VE and HPE Morpheus clusters** - `ankra cluster proxmox` and `ankra cluster morpheus` cover the full lifecycle, node groups, control plane, SSH keys, autoscaling, and upgrades, plus discovery of what each platform offers and their own credential commands.
* **Managed Kubernetes parity** - provider-native stop and start, `node-pool update` for in-place node count and autoscaling changes, autoscaling bounds at create time, and Scaleway Kapsule as a new provider.
* **See and stop what your AI agents are doing** - `ankra agents` lists dispatched agent runs, shows one in full, reads the session transcript of what the agent actually said and did, and cancels a live run.
* **Agent-mode chat asks before it writes** - every mutating tool halts the turn and proposes the write. The stream now shows each proposal with its risk and parameters, an interactive session prompts to run or discard it, and `ankra chat actions confirm | reject | list` drives the same decision from a script. (One exception has since joined: a conversation switched to the new **Auto** autonomy setting executes validated additive stack deploys with a receipt instead of halting - see [Additive deploys that can run themselves](#additive-deploys-that-can-run-themselves) above.)
* **Node restarts and bastion resize** - restart any provisioned node as a tracked operation across Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, and Proxmox, and resize the bastion in place.
* **Secrets encrypted in a single commit** - `ankra cluster encrypt manifest --set` applies the new value in memory before encrypting, so the plaintext never reaches git history.

The release also fixes a batch of commands that were decoding response shapes the API never sent, and therefore showed nothing: manifest and member listings, chat health, and stack history all return real data again, and `ankra cluster encrypt -f` and `cluster clone` no longer strip fields and comments from your cluster YAML.

[CLI Changelog →](/integrations/ankra-cli-changelog) | [Ankra CLI →](/integrations/ankra-cli)

## Ask the AI to build you a Proxmox cluster

Cluster provisioning in chat now covers Proxmox VE. Ask the assistant for a new cluster on your Proxmox credential and it drives the real flow: it reads the credential, lists your host nodes with their CPU and memory alongside the px-\* instance presets, and - once a node is picked - that node's storage pools, network bridges (SDN vnets included), and clone-source templates, then proposes the create for your confirmation like every other provisioning action. Credentials that reach Proxmox through an SSH jumphost work too - the chat reads ride the same tunnel the rest of the platform uses.

Hetzner, OVH, UpCloud, and Scaleway were already there; Proxmox VE joins them, so the platform chat and the [MCP tool surface](/platform/mcp-tools) now agree on what can be built.

[Ankra AI Assistant →](/platform/ai-assistant)

## Demos that fix their own configuration

An application image that validates its environment on boot used to make a hopeless demo: deployed bare, it crash-loops, and the preview never comes up. Now, when a demo fails with a startup crash, Ankra dispatches a **pre-setup agent** automatically. It reads the crashed container's logs, works out which variables the application demands, and generates the demo configuration: database URLs become references to the demo's own throwaway Postgres, secrets get fresh random values, and mode flags get the value without external side effects. It saves the result as the application's demo defaults - every future demo inherits them - and redeploys the failed demo to prove it boots.

The agent's run is visible on the AI agents page like any other mission, it never weakens the application's own validation, and it runs at most once per demo per day. You can also trigger the same fix on demand, or ask the AI assistant to repair a failed demo in chat - the same diagnostics, configuration, and redeploy tools back both. Two supporting fixes ship alongside: demo redeploys switch to a Recreate rollout, so a configuration change can never wedge against the namespace resource quota, and the throwaway demo database now runs a pgvector-capable Postgres, so migrations using `CREATE EXTENSION vector` work.

[Preview demos →](/concepts/applications#automatic-pre-setup-when-a-demo-crashes)

## A full page for every demo

Inspecting a demo used to mean a dialog stacked over the Demos tab - cramped, unlinkable, and gone the moment it closed. Every demo now has its own page, opened from a demo row's status pill or **Details** button. A header carries the demo's identity - branch or pull request, status, full-stack and database badges, namespace, image tag, and the time left - with **Open preview** and **Stop demo** alongside. Below it, the view reads live from the staging cluster and refreshes itself: the provisioning timeline, the namespace's bill of materials with each resource's manifest a click away, the Kubernetes events that explain a stall, and on-demand pod logs. Side cards cover how to reach the demo - the preview URL or the exact port-forward command - the demo's facts, and the staging cluster it runs on.

Because it is a page, it has a URL: share a provisioning demo with a teammate and they land on the same live view, breadcrumbs and all.

[Preview demos →](/concepts/applications#preview-demos)

## Monorepos onboard as applications, one component per app

An application used to mean one deployable app per repository: a single image, a single build workflow, a single container port. Point Ankra at a monorepo and the generated pipeline built each app correctly and pushed each image to its own place - but everything that read the result looked somewhere none of them published to, so a repository whose builds were green reported "No built images were found for this application yet." and the demos tab had nothing to launch.

Applications now model a repository's **components**. An ordinary repository has one, covering the root; a monorepo has one per app, each with its own Dockerfile under its directory, its own manifests, its own workflow carrying a `paths:` filter so touching one app does not rebuild the others, and its own image at `<your-registry-project>/<repository>/<component>`. Build state, published images, publish readiness, deploys, demos, and container scanning are all reported per component, so an application whose API component built and whose frontend did not says exactly that instead of collapsing the two into one wrong answer.

Ankra works out the components from what the repository already declares first - a repository it has onboarded before keeps the component names its live workflows use, so re-running analysis never renames an app and orphans the images it has published - then from what the analysis proposes, then from the repository's structure. A Dockerfile at the repository root always means a single app. Nothing needs migrating: an application with no recorded components still resolves to exactly the coordinates it always used, and re-running analysis records the components it finds.

The launch dialog gained a **Component** picker for monorepos, with the container port following your pick. That was the sharpest edge of the old behaviour: a component inherited whichever port appeared first among the repository's generated files, so an API component on 8090 could be probed on port 3000 of a frontend and the demo sat in *provisioning* until it timed out.

[Monorepos →](/concepts/applications#monorepos)

## Application setups that rescue themselves

Adding an application kicks off an AI setup that analyses the repository and generates the Dockerfile, Kubernetes manifests, and CI/CD pipeline. Until now that screen could over-promise: before any agent had actually picked the task up it already said "AI Agent assigned to task", and if the setup stalled or failed there was no agent anywhere in the product to look at. The first step now reads **Waiting for an AI agent to pick up the task** until real progress arrives, so the screen tells you what is actually happening.

More importantly, stuck setups no longer depend on you noticing them. A setup that sits silent for fifteen minutes, or fails its analysis, now dispatches a **rescue mission** automatically: a one-shot agent that appears on the AI Agents page with a full transcript, diagnoses what went wrong, retries the setup when that is the fix, and reports exactly where things are stuck when it is not. The setup screen links straight to the AI Agents page from its stall warning and its failure state, and dispatch is bounded to one rescue per application per day.

Alert delivery got the same discipline behind the scenes: a notification whose webhook can never deliver - the webhook was deleted, or never had a URL - now records its failure and stops retrying instead of piling up as pending work, and stale undelivered notifications are swept automatically. One organisation's undeliverable-webhook backlog was what starved new application setups in the first place.

[Applications →](/concepts/applications)

## Every chart version shows its license

Every chart version's overview in the chart browser now carries a **License** field with the license's SPDX identifier - `Apache-2.0`, `MIT`, `AGPL-3.0-only`, and so on. Ankra reads the chart's `artifacthub.io/license` annotation from `Chart.yaml`, and falls back to detecting the license from the `LICENSE` or `COPYING` file inside the chart package when the annotation is missing.

Copyleft licenses - the AGPL and GPL family - are visually highlighted, so a chart whose license carries obligations for your own code stands out before it lands in a stack.

[Helm Charts →](/platform/addon-catalog)

## Gateway resizes that wait for the cloud

Resizing a cluster's gateway could be reported as failed even though it was proceeding normally: the platform timed out while the cloud provider was still completing the resize. Resize operations now wait for the provider to finish, so a resize that succeeds on the provider side succeeds in Ankra too.

## Registry creation tells you what is wrong

Creating a Helm registry with a malformed spec used to answer with a bare 500 and no hint at the cause. The API now validates the spec first and answers with a clear 422 naming exactly what is wrong. The CLI side got friendlier too: registry creation accepts both flat and YAML spec files, plus `--name` and `--url` flags for the simple case where a file is overkill. The 422's example now shows both accepted shapes - the raw API body and the pre-wrap file that `ankra helm registries create -f` expects - so copying the example works from either caller.

[Registries →](/guides/registries)

## Cluster validation that names the real problem

Validating a cluster definition whose add-on could not be resolved used to give one undifferentiated error. Validation now distinguishes the three cases: the registry is not connected in your organisation, the chart does not exist in that registry, or the chart exists but the pinned version does not. `chart_version` itself is validated too, so a typo in a version pin is caught at validation time instead of at deploy time.

Version pins compare the way Helm resolves them: `1.20.0` matches a chart published as `v1.20.0` and vice versa, so a pinned production config validates no matter which spelling of the version your chart's publisher uses.

`ankra cluster validate` now also runs the per-resource field checks that apply enforces - add-on namespace rules, group names, empty manifest bodies - so a rule that would reject your file at deploy time is caught at validation time, in CI, before anything touches a cluster. And the namespace rule itself got saner: add-on namespaces now accept everything Kubernetes accepts (1-63 characters, lowercase letters, digits and dashes), so short names like `ory`, `ops`, or `dev` are valid - the old 4-character minimum is gone.

[ImportCluster YAML Schema →](/reference/importcluster#validation)

## Secret detection that reads the value, not just the key

The plaintext-secret scan used to flag anything whose key looked secret-like, so `timeout: 30s`, port numbers, and references to already-encrypted values all raised warnings. Detection is now value-shape aware: durations, ports, booleans, and references no longer count, while values that actually look like credentials still do. High-confidence findings can also gate CI - enable `strict_secrets` and a definition carrying a likely plaintext secret fails instead of warning.

[SOPS Secrets →](/guides/sops)

## CLI listings built for scripting

List commands across the CLI now page properly: pagination flags control the window, `--all` fetches everything, and a listing with more results than it shows says so instead of silently truncating. JSON output uses a consistent envelope across commands, so scripts can parse every listing the same way. And `ankra cluster encrypt` grew batch ergonomics: `--key` is repeatable and `--all-data` encrypts every data field in one pass.

[Ankra CLI →](/integrations/ankra-cli)

## See what GitOps is actually syncing

`ankra cluster gitops status` shows the cluster's live GitOps source: the connected repository, the branch Ankra reads from, the credential in use, and the last synced commit with its sync state. When a cluster is not picking up changes, the first question - is it even looking at the right branch? - is one command away.

[GitOps →](/concepts/gitops)

## Preview a chart's manifests before anything deploys

`ankra charts template` renders an add-on's chart with your values server-side, from the same mirrored package Ankra deploys, and prints the resulting Kubernetes manifests - or the exact rendering error a deploy would have hit. Wrong secret key names, surprising Service ports, and values that leak into a ConfigMap all surface on your laptop instead of against a production cluster. `ankra charts values` prints a chart version's default values document, the baseline you diff your overrides against. Neither command needs direct registry access on your side.

[Stacks and add-ons →](/concepts/stacks)

## Declare Helm registries in the cluster file

The ImportCluster file can now carry a top-level `spec.helm_registries` block. Registries declared there are connected automatically before any add-on deploys - same name and URL is an idempotent no-op, private registries reference an existing credential by name so secrets stay out of Git - which makes a GitOps repository genuinely self-contained: clone, apply, and the declared state is reachable on a fresh organisation with no side-channel setup commands.

[ImportCluster reference →](/reference/importcluster)

**July 2026**

# More Clouds, Vulnerability Scanning, and Team Roles

## Whoever creates a cluster can reach it with kubectl

Creating or importing a cluster now grants you cluster-scoped `cluster-admin` Kubernetes access to it, so `ankra cluster kubeconfig add` works as soon as the cluster is up instead of answering "You do not have access to this cluster" until an admin granted you access by hand. The grant is an ordinary Cluster Access grant: it shows up in the cluster's **Access** view and in `ankra cluster access list`, reconciles into native RBAC, and can be revoked. Clusters created before this change have had the same grant seeded for their creator, so kubeconfig access there starts working without any operator action.

[Cluster Access →](/guides/cluster-access)

## Branch and PR demos detect your application's port

Launching a demo no longer assumes your application listens on port 8080. Every demo lane - the Launch demo dialog, AI-deployed PR demos, and the automatic pull-request previews - now reads the port from your application's generated Dockerfile (`EXPOSE`) and deploys with it, so a Next.js app on 3000 or a Flask app on 5000 comes up ready instead of sitting in "provisioning" forever behind a readiness probe on the wrong port. The launch dialog pre-fills the detected port, and the advanced override still wins when you need something different.

## Security Center overview and findings, modernised

The Security Center's **Overview** and **Findings** tabs now share the visual language the Compliance tab introduced. The overview leads with a fleet security scorecard: a posture ring showing the share of scanned clusters with no actionable critical or high findings, a verdict at a glance, and tiles for critical, high, fixable-severe, and scan coverage. Findings swaps its second tab bar and boxed filter panel for pill filter chips with live counts pulled from your fleet's data.

Ankra AI is now one click away from both tabs: **Fix top findings with AI** on the overview hands the top remediation candidates to the AI with a fleet-wide remediation ask, and every finding's detail sheet gains **Ask Ankra AI**, grounded in the finding and the cluster it was observed on.

[Security Center →](/guides/cluster-security)

## The Security Center overview shows which application is generating the risk

The overview no longer stops at fleet totals. A new **Risk breakdown** row splits your observed occurrences three ways: a **Severity mix** with a bar per band, a **Review state** split across open, acknowledged, and accepted risk, and a **Fix readiness** number telling you what share of your critical and high occurrences actually have a published fix to move to. The **Observed fleet trend** chart grew up too - gridlines, a filled area, the observed range on the axis, a change chip, and a tooltip on every snapshot.

Most usefully, **Application hotspots** now ranks the workloads generating the most actionable risk across your whole fleet, weighted so criticals outrank a pile of lows. Each row names the workload, the namespace and cluster it runs in, the add-on it was attributed to, how many of its findings already have a fix, and links straight into that cluster's findings filtered to it. Alongside it, **Risk by cluster** ranks your clusters by actionable occurrences, so "where is the heat" and "who owns it" are both answerable without leaving the overview.

The overview also lays itself out based on the space it actually has rather than the size of your screen, so reading it beside the docked AI panel no longer squeezes the scorecard tiles into unreadable slivers.

[Security Center →](/security/overview)

## Ankra AI now runs on Claude Opus 5

The platform's highest-capability AI tier moved from Claude Opus 4.8 to Claude Opus 5. Everything that escalates to the Expert model - plan mode, image analysis, high-risk and multi-resource changes, complex architectural questions, deploy analysis, and CI/CD pipeline generation - now runs on Opus 5, at the same price and with the same 1M-token context window. Organisations that customised their model catalog keep their pinned models; the built-in Expert entry upgrades automatically.

## Application images now build to your private Ankra registry

Application CI/CD no longer publishes to GitHub Container Registry. When Applications is enabled, Ankra provisions a private project for your organisation in its own registry, together with the GitHub Actions credentials and the Kubernetes pull secret each cluster needs. The generated pipeline builds your source, scans the image, and pushes it to that private registry; the generated manifests already reference the image and its pull secret, so a merged pull request flows straight through to a running workload. The Ankra GitHub App now requests the **Secrets** permission to install that registry login, replacing the old GHCR make-public flow.

[Applications →](/concepts/applications)

## AI Insights gets out of the way when your cluster is healthy

The cluster AI Insights page no longer fills the screen with empty charts and zeroed counters when there is nothing wrong. A healthy cluster now shows a single compact "All quiet" summary confirming that monitoring is active, with one-click access to the resolved-fault history and to alert creation. The full analytics dashboard returns automatically the moment new activity appears - and the Faults tab no longer suggests your filters are hiding results when the cluster is simply healthy.

## Fleet overview: every Ankra-created cluster on the globe, plus a new fleet world

The dashboard's fleet globe now places every cluster Ankra created for you - self-managed (Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway) and managed Kubernetes (DOKS, UKS, GKE, AKS, EKS, OVHcloud MKS, Kapsule) alike. When a cluster's nodes don't carry cloud topology labels (common on k3s and fresh clusters), the platform falls back to the region you picked at create time, so "not on the globe" is now reserved for genuinely unlocatable clusters. Proxmox and Morpheus clusters keep resolving through agent GeoIP.

Next to the globe, the fleet overview gains a **fleet world**: an isometric 3D view where every cluster is a tower - height tracks node count, colour and glow track live status - so the whole fleet is readable at a glance, including clusters with no geolocation. Click a tower to jump into the cluster. The section layout was also rebalanced so the globe, fleet world, vital signs, utilisation, and security posture fill the page consistently.

## DigitalOcean clusters: reliable DNS and LoadBalancers that just work

DigitalOcean's default DNS resolvers are flaky enough to intermittently break name resolution on nodes and inside pods. Ankra-provisioned DigitalOcean clusters now pin node DNS to Cloudflare (`1.1.1.1` / `1.0.0.1`) with a self-healing setup that re-applies within a minute if anything reverts - on new clusters at provision time, and on existing clusters automatically through the platform's drift detection.

LoadBalancers on private-node DigitalOcean clusters also work out of the box now: the DigitalOcean cloud controller ships at v0.1.68+ (private-IP-only droplet support), is wired with the cluster's VPC UUID automatically (no more 422 "target droplets don't belong to the same VPC"), and the bundled Traefik ingress carries the `REGIONAL` load-balancer type its Service needs on private-only topologies. Existing clusters converge without any operator action.

## Chat turns survive disconnects

An AI chat answer no longer depends on your browser staying connected. Every interactive turn is now written to a durable server-side event log as it streams, and the turn keeps running even if your tab closes, your network blips, or the platform restarts mid-deploy - tool calls finish, the answer completes, and nothing is lost. A new resume endpoint (`GET /chat/conversations/{conversation_id}/events`) replays the missed frames from where you left off, with live tailing and `Last-Event-ID` support. Provider hiccups were already covered by automatic failover; now the conversation itself is just as durable.

## Proxmox host-spread clusters now provision across nodes

Control planes and workers placed on different Proxmox hosts previously stalled at the first cross-host node - the private SDN network is node-local, so the bastion had no path to a VM on another host. When a Proxmox VE credential carries Tailscale/Headscale settings, every VM now joins the tailnet at create time (through the Proxmox guest agent, before it has any other network path), and Ankra uses that tailnet address for SSH, kubeadm join, etcd peering, and haproxy upstreams. Enabling this requires the credential's Proxmox API token to hold `VM.GuestAgent.Unrestricted`, in addition to the `VM.GuestAgent.Audit` privilege address discovery already needs.

[Proxmox VE credentials →](/platform/credentials/proxmox#tailscale-and-headscale-optional)

## Stack Profiles now show who you can trust

Saving a stack as a profile now carries its existing description into a cleaner, modern save flow. Categories are searchable and reusable, tags are suggested as interactive chips, and you can choose whether the profile stays private to your organisation, becomes public, or is shared with specific organisation slugs.

Profile cards and details now show the publisher's organisation name, logo, and verified status. Verified Ankra profiles appear first, so official profiles are easy to identify before you use them. Organisation admins can upload or replace their publisher logo from organisation settings.

[Stack Profiles →](/concepts/stack-profiles)

## Profile capture understands every secret path you can declare

Saving or publishing a stack profile no longer fails when a secret sits inside a YAML list - think fluent-bit's `config.pipeline.outputs[0].http_passwd` - or when an encrypted path is declared by its SOPS leaf key alone (`api-key`), the same shorthand `ankra cluster encrypt` uses. Both spellings now redact cleanly into required secret parameters. Values that are runtime environment references like `${OPENSEARCH_PASSWORD}` are no longer mistaken for plaintext secrets, so stacks that already inject credentials from Kubernetes Secrets capture without forcing a bogus secret parameter.

[Stack Profiles →](/concepts/stack-profiles)

## Breadcrumbs everywhere you are

Every page in the portal now carries a breadcrumb trail derived live from where you are - `Home / Clusters / prod-eu / Stacks / loki` instead of guessing your way back with the browser button. Dynamic segments show real names, not identifiers: the cluster crumb reads the cluster's name, operations show their display name, stack profiles and AI agents theirs. Each crumb that corresponds to a real page is clickable (the cluster crumb jumps to its overview), structural URL noise is hidden, and the trail stays out of the way on phones where the back button already does the job.

## Organisation menu goes straight to your organisation

**Organisation** in the profile menu (and `/organisation`) now lands directly on your current organisation's overview instead of a list. Switching moved closer to hand: a **Switch organisation** submenu in the profile menu lists all your organisations with your current one marked - one click to switch, plus shortcuts to pending invites, the full organisation list, and creating a new organisation. The full list with per-organisation switching lives on **All organisations**.

[Organisations →](/concepts/organisations)

## Your AI team, preloaded

Every organisation now starts with a five-agent **AI team** - AI Team Lead, Developer, Database Admin, SRE, and DevOps - waiting under **AI → Agents**. Each one is chattable directly: open an agent and the conversation carries its persona, so the SRE talks evidence and the Database Admin checks backups first. Creating your own agent is now an **AI-guided interview** - pick a role, shuffle a name, choose focus areas and guardrails, and the wizard writes the persona for you (the classic form is one click away). Defaults are safe by construction: propose-only autonomy, hard budgets, and nothing runs until you ask.

[AI Agents →](/platform/ai-agents)

## Demos now run real applications - env vars, secrets, and a throwaway database

Demos used to run the container image bare, so anything needing configuration crash-looped on boot. Now every application carries **demo environment defaults** (the gear on the Demos tab) that all lanes inherit - manual launches, `deploy_pr_demo`, and automatic PR previews - with **per-launch overrides** in the launch dialog. Values marked secret ride Vault-backed secret slots and reach the demo as a Kubernetes Secret; plaintext never persists. Need a database? Toggle **Attach a throwaway Postgres** and an ephemeral instance spins up inside the demo namespace with a random per-demo password, wiped with the demo - your env values reference `${{ ankra.demo_database.* }}` placeholders, so any codebase's configuration naming just works.

[Preview demos →](/concepts/applications#environment-variables-and-a-throwaway-database)

## Application demos get a shareable URL

Deploy a throwaway demo of an application's pull request or branch build and Ankra now hands back a **public preview URL** automatically - no manual ingress or DNS wiring. When your organisation has a demo base domain configured, the demo is served under it; otherwise, if the staging cluster has an active Ankra DNS zone, it gets a `*.ankra.cc` host that resolves on that cluster. Without either, the demo still deploys and stays reachable in-cluster. The same URL is returned everywhere you deploy a demo - the portal Demos tab, `ankra application demo deploy`, the `deploy_pr_demo` AI/MCP tool, and the automatic preview posted on a connected application's pull requests.

[Preview demos →](/concepts/applications#preview-demos)

## A home for Ankra

Pick a **home channel** and Ankra starts the conversation on its own. When something important happens - a failed deployment, an agent going offline, a new severe CVE - and no routing rule already handles it, Ankra posts to your home Slack channel. Set it under **Organisation Settings → AI → Workspaces** ("Ankra's home"); only critical and warning events reach it, and it never double-notifies what a routing rule already sent.

[Home channel →](/guides/webhooks#home-channel)

## Managed Kubernetes and three more clouds

Ankra now provisions and operates **provider-managed Kubernetes** - DOKS, UKS, GKE, OVHcloud MKS, AKS, and EKS - with node pools, autoscaling (all but UKS), upgrades, and discovery/import of existing clusters. Self-managed provisioning also gained **DigitalOcean**, **Proxmox VE**, and **Morpheus** alongside Hetzner, OVH, and UpCloud.

[Managed Kubernetes →](/guides/managed-kubernetes) · [DigitalOcean →](/guides/digitalocean-clusters) · [Proxmox VE →](/guides/proxmox-clusters) · [Morpheus →](/guides/morpheus-clusters)

## Proxmox VE zero-config bootstrap

Saving a Proxmox VE credential now sets up everything a cluster needs on an empty host: VM storage, the management bridge, a private NAT network (`ankra`, 10.20.0.0/16) with DHCP built on Proxmox SDN, and an Ubuntu 24.04 cloud-init template. Cluster VMs on the private network get their addresses from Proxmox IPAM automatically - no guest agent required in the image - and reach the internet through the host's public interface.

[Proxmox VE →](/guides/proxmox-clusters)

## Tailscale for Proxmox VMs

Attach a Tailscale/Headscale login server and a reusable auth key to a Proxmox VE credential, and every VM Ankra provisions with it installs Tailscale and joins your tailnet on first boot - each VM getting its own tailnet address, reachable across Proxmox hosts and from your own networks. You can add, change, or remove it on an existing credential without recreating it.

[Proxmox VE →](/platform/credentials/proxmox)

## Cluster vulnerability scanning with Trivy

Install the Trivy Operator add-on and Ankra reads its vulnerability reports into a dedicated **Security** console: severity breakdowns, a blast-radius-ranked priority queue, remediation campaigns, and a phased burn-down plan. The AI assistant can summarise and prioritise CVEs with the same data.

[Cluster Security →](/guides/cluster-security)

## Cluster compliance is now actionable

Selecting a cluster from **Security → Compliance** now opens a full cluster Security page instead of a narrow drawer. The Compliance tab shows failed and passed CIS, NSA/CISA, and Pod Security Standards checks, configuration-audit hotspots, affected counts, remediation guidance, and filters for the exact result you need.

Every failed check has **Fix with AI**. The cluster-scoped agent receives the benchmark and remediation context, can inspect the affected Kubernetes resources, apply safe fixes with the usual confirmation guardrails, and verify the result.

[Cluster compliance →](/guides/cluster-security#cluster-security-view)

## Team roles, cluster groups, and scoped access

Access is now governed by **roles** you assign at a scope - the whole organisation, a single cluster, or a **cluster group** (static or label-selected). A role can bundle Kubernetes access that Ankra provisions on every cluster in scope, and every change is captured in an organisation audit log.

[Roles & Access →](/guides/roles-and-access)

## Pipeline agents

Build CI-native infrastructure agents from plain pipeline jobs and the Ankra CLI - PR review, deploy watching, and scheduled health checks - with no framework or orchestration layer.

[Build pipeline agents →](/guides/pipeline-agents)

## Proxmox automatic setup supports DHCP and provider-managed interfaces

The "Set up storage and network automatically" bootstrap now works on dedicated servers where the management interface is configured via DHCP or marked `manual` (the provider assigns the IP outside Proxmox's network config, common on Scaleway and similar bare-metal hosts). Previously only statically addressed interfaces were accepted.

[Proxmox VE credentials →](/platform/credentials/proxmox)

## Restart a node or resize the bastion, from the UI, CLI, or chat

The **Nodes** tab now has a **Restart** action for every control plane node, worker, and bastion/gateway (Hetzner, OVH, UpCloud, DigitalOcean, Proxmox), and a **Resize** action for the bastion/gateway (those five plus HPE Morpheus). Both run as tracked operations, and the node table now shows each node's live status straight from the cloud provider's API so a crashed or externally-stopped VM is visible before you act on it. The same actions are available from `ankra cluster <provider> nodes restart` / `bastion resize`, and by asking the Ankra AI assistant - in the portal, Slack, or Teams - to restart a node or the bastion by name.

[Nodes Settings →](/platform/cluster-nodes) · [Restarting a Node →](/guides/operate-ankra-managed-clusters#restart-a-node)

## Managed networking stack on Proxmox VE and HPE Morpheus

Proxmox VE and HPE Morpheus clusters now ship the same Ankra-managed networking stack as every other self-managed provider: Traefik and cert-manager are installed as Ankra stacks after bootstrap (visible and manageable in the platform) instead of relying on the k3s-bundled Traefik. The **Include Networking Stack** option in the create wizard is on by default; ingress is exposed through the built-in k3s service load balancer on node IPs, since these providers have no cloud load-balancer API. Storage still comes from add-ons such as Longhorn - install one from the add-on catalog for persistent volumes.

Both providers also reached full surface parity: `ankra cluster proxmox` and `ankra cluster morpheus` CLI commands (create plus catalogs for hosts, storages, bridges, templates, and plans, with stop/start and the generic scale, upgrade, node-group, and SSH-key verbs), and the Ankra AI assistant can now create Proxmox VE and HPE Morpheus clusters in chat with the same guided, confirmation-gated flow as the other providers.

## Lifecycle parity across self-managed clouds

The canonical self-managed provider set is now **Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE, and HPE Morpheus**. All seven can be stopped and started from the portal, CLI, API, and Ankra's AI or any MCP client. The new `ankra cluster scaleway stop|start` commands close the remaining CLI gap for Scaleway.

## Stack draft editor reliability

Three draft-editor bugs are fixed: drafts no longer disappear after a few minutes of editing (live edits now keep the draft's idle timer fresh, so the cleanup job only removes genuinely abandoned drafts), saving no longer fails with a spurious "modified by another request" conflict (a background sync task stopped invalidating the editor's save token), and renaming a stack inside the editor no longer detaches the draft from its deployed stack - the draft stays linked under the stack's current name and the rename is applied when you deploy.

## Managed Kubernetes catches up on day-2

Managed clusters closed three long-standing gaps. **AKS clusters can now be stopped and started** from the portal, CLI (`ankra cluster managed stop|start`), API, and Ankra's AI or any MCP client - Azure deallocates the compute while every setting is preserved, and Ankra advertises the capability per provider so each surface only offers it where it works. **Node pool machine sizes can finally be changed**: since no provider allows in-place size changes, Ankra performs a blue/green replacement - a new pool with the new size is created and brought to ready before the old one is deleted, with labels, taints, and autoscaling carried over. And the **CLI reached managed parity**: node pools take autoscaling bounds at create and via the new `node-pool update` command, and pool counts and autoscaling can be changed without touching the portal.

[Managed Kubernetes reference →](/reference/managed-kubernetes)

## The AI Assistant runs your clusters' day-2 operations

The AI Assistant (and every MCP client) can now do far more than create clusters. Seventeen new tools cover the full day-2 surface for Ankra-provisioned clusters - **scale workers and node groups, add, update, and delete node groups, change the control plane, stop, start, upgrade, and even deprovision a cluster** (with a type-the-name-to-confirm guardrail) - plus a **managed Kubernetes family**: create and operate **EKS, AKS, GKE, DOKS, UKS, OVHcloud MKS, and Scaleway Kapsule** clusters and their node pools from chat. DigitalOcean cluster creation from chat is also live. Every mutating tool goes through the same confirmation card and drift-checked approval flow as before.

[MCP Tool Reference →](/platform/mcp-tools)

## Start a stopped Hetzner cluster

Hetzner clusters can now be **started** again after a stop, like every other self-managed provider - previously only stop was available, and bringing a cluster back meant adding a fresh node group. Stopping releases the Hetzner compute while keeping the cluster's configuration, stacks, and credentials; starting re-provisions the saved topology and reconciles the cluster back online. Also fixed: managed **GKE**, **DigitalOcean (DOKS)**, and **OVHcloud MKS** clusters now correctly advertise node-pool autoscaling support in the create wizard.

The portal now derives **Stop** and **Start** from one canonical self-managed provider set, so Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE, and HPE Morpheus stay in sync. Scaleway also gains `ankra cluster scaleway stop|start`, closing the remaining CLI lifecycle gap.

[Stopping and Starting →](/guides/hetzner-clusters#stopping-and-starting-a-cluster)

## The full platform lifecycle over MCP and chat

The Ankra MCP server and the AI assistant now cover the core lifecycle of **stacks, add-ons, applications, and credentials** - around 35 new tools. From Cursor, Claude, in-product chat, or chat over Slack, Teams, and SCM comments (all backed by the same tool registry), you can list, inspect, create, update, redeploy, clone, and delete stacks; read and update add-on settings and values; run the application lifecycle end to end including deploys and workflow runs; and manage credentials - list and inspect them (secrets always redacted), delete unused ones, and plan and apply a GitHub credential rotation. Creating credentials stays deliberately off-limits to the AI: it would mean handing it the secret itself, which the platform refuses. Reads need `mcp:read`; mutations need `mcp:write` and stay confirmation-gated in chat. A new reference page lists every tool with its scope.

Alongside, the CLI gained `ankra credentials proxmox` and `ankra credentials morpheus` command groups (list and create, including SSH keys), and `ankra application delete` and `ankra application make-public` now ask for confirmation before acting.

[MCP Tool Reference →](/platform/mcp-tools) · [MCP Server →](/platform/mcp-server)

## The sandbox demo is now fully editable

The seeded "sandbox-demo" cluster is no longer read-only. You can now add, configure, move, clone, and delete stacks, add-ons, and manifests, work with drafts, and hit Deploy - the full stack-editing experience, before importing a cluster of your own. Deploys in the sandbox are simulated: they complete instantly and mark resources green without running anything on real infrastructure. Cluster-level operations that need a live agent (archive, agent tokens, add-on sync) remain unavailable there.

[Playground & sandbox →](/guides/cluster-sandbox)

## Custom DNS records under your organisation's ankra.cc subdomain

Organisation admins can now manage their own **CNAME, A, and TXT records** under their organisation's delegated `ankra.cc` subdomain - handy for aliasing an add-on's auto-generated hostname to something memorable. The **DNS records** console (under **Organisation Settings**) shows your zone and its status, a searchable, type-filterable records table, and lets you add, **edit in place**, and delete records with a chosen **TTL**. New and edited records provision asynchronously and show their state (pending, active, or failed, with the reason) in the list.

[DNS Records →](/platform/organisation-settings#dns-records)

## Approving a plan on the AI board now starts the work

Fixed: approving an agent's plan on an AI board ticket left the ticket waiting indefinitely - the assigned agent was never re-dispatched, and nothing happened until someone manually moved the ticket to "Executing". A human approval now releases the ticket to **Executing** (and "Request changes" sends it back to **Planning**), and the dispatcher picks it up on the next cycle instead of waiting out its re-dispatch backoff. Assigning a ticket to an agent right after approving its plan now behaves the same way.

## Reply to a board ticket and the agent replies back

The AI board is now conversational. Commenting on a ticket assigned to an AI agent - from the ticket page, or by replying in its mirrored Slack or Microsoft Teams thread - re-dispatches the agent, which reads your comment and answers on the timeline. This works even while the ticket sits in **Awaiting review** or **Awaiting approval** (exactly where questions about a plan come up - previously a comment there was never seen), and the agent is instructed to respond and revise only, never to start executing before the plan is approved. Slack and Teams replies now also appear in the agent's work brief. Closing or cancelling a ticket now cancels any agent runs still working it, so nothing keeps burning tokens on dead work.

## Inspect and cancel AI agent runs - from MCP, the CLI, and the API

Every dispatched agent run is now visible and controllable outside the portal. Three new MCP tools - `list_agent_runs`, `get_agent_run` (optionally with the session transcript tail), and `cancel_agent_run` (organisation admins only) - let the AI assistant and any MCP client watch and stop the AI team's work. The same surface ships in the CLI as the new **`ankra agents`** family (`runs`, `run`, `transcript`, `cancel`) and as PAT-authenticated API routes under `/api/v1/org/ai-agent-runs`. Cancelling a run flips its session and the platform interrupts the in-flight turn within seconds, without pausing the agent itself - and run transcripts are now readable by any organisation member through the run, not just the agent's creator.

[MCP Tool Reference →](/platform/mcp-tools)

## Archived clusters are off the fleet map

Fixed: archiving a cluster removed it from the cluster list but left its pin on the Dashboard's world map and, when it had no resolvable region, in the "not on the globe" tray. Archived clusters are now excluded from the map entirely - the same treatment they already get in the health summary - so the globe shows only the fleet you still run.

[Dashboard →](/platform/dashboard)

**June 2026**

# A Go-Native Agent, Fleet Dashboard, Cloud Cost, kubectl Access, Stack Profiles, Applications, Support, and a Provider-Agnostic CLI

June was a big month across the whole platform: a rebuilt cluster agent, a new fleet dashboard with cost visibility, scoped cluster access, reusable stack templates, application delivery, in-product support, and a CLI that caught up with the web UI.

## A faster, leaner cluster agent, rebuilt in Go

The [Ankra Agent](/concepts/cluster-agent) has been rebuilt as a single, statically compiled Go binary and is now the production agent on the new `2.0.x` version track.

It is a drop-in replacement: the same Helm chart, values, install command, NATS connectivity, and behaviour as before - resource streaming, log streaming, Helm management, add-on deployment, and `kubectl` proxying all work exactly the same. Nothing changes in how you install or operate it.

What you get for free:

* **A smaller footprint.** The default memory limit drops from `1536Mi` to `512Mi` and the request from `512Mi` to `256Mi`, alongside lower CPU usage and faster startup.
* **Automatic rollout.** Existing clusters are upgraded to the new agent automatically by the platform, a few clusters at a time - no action required. You can still upgrade on demand from **Cluster Settings → Upgrade Agent**.
* **Identical operations.** Same outbound-only connectivity, same `/livez`, `/readyz`, and `/metrics` endpoints on port `8080`, and the same `extra_env` tuning knobs.

See the [Ankra Agent](/concepts/cluster-agent) docs for the full configuration reference.

## A fleet dashboard with a world map

The organisation [Dashboard](/platform/dashboard) now opens on a world map of every cluster, alongside health and cost rollups. Clusters are placed by cloud region, or by the agent's public egress IP when [public IP reporting](/concepts/cluster-agent) is enabled.

## Cloud cost estimates

[Cloud Cost](/platform/cloud-cost) estimates per-cluster and fleet-wide spend from your live node and volume inventory plus cloud pricing - broken down by compute, storage, network, and per-namespace allocation. Connect an [AWS or GCP credential](/platform/credentials) to get started.

## Scoped kubectl access through Ankra

Grant teammates SSO-backed, scoped Kubernetes access with [Cluster Access](/guides/cluster-access), then reach the cluster with your own `kubectl` through Ankra's [API proxy](/guides/kubeconfig) - short-lived credentials, no inbound network access, works with private clusters.

## Reusable Stack Profiles

Capture a working stack as a versioned, parameterised template with [Stack Profiles](/concepts/stack-profiles), then instantiate it on any cluster - with diffing, update tracking, and IaC export.

## Applications: from repo to running workload

[Applications](/concepts/applications) connect an app's Git repository, generate the Dockerfile, Helm chart, and CI/CD via a pull request, then build and deploy the result as a stack.

## In-product support

Raise and track [support tickets](/platform/support) without leaving Ankra - with AI triage, attachments, and threaded replies - and keep an eye on everything that needs you in your new [Activity & Inbox](/platform/activity-inbox).

## More reliable apply for large manifest stacks

Applying a stack with many manifests at once - and reconciling stacks on clusters with lots of Custom Resource Definitions - is now far more reliable. Manifests are given more time to apply before they're considered stalled, and the agent no longer re-runs expensive API discovery on every single apply, so a large stack reconciles cleanly instead of failing partway through with a timeout.

The change applies automatically: existing stacks pick it up on their next deploy with no action required. Any per-manifest timeout you set previously is honoured as long as it's at least the new, more generous default, and custom timeouts above the default are kept as-is.

[Manifests →](/concepts/stacks#manifests)

## The Ankra CLI caught up with the platform

Most of what you can do to a cluster in the web UI is now scriptable from the [Ankra CLI](/integrations/ankra-cli):

* **Provider-agnostic cluster verbs** - `ankra cluster upgrade | scale | node-group | deprovision | k3s-versions` detect Hetzner, OVH, or UpCloud automatically from the cluster.
* **Cluster access and kubectl** - grant scoped RBAC with `ankra cluster access` and write short-lived, SSO-backed `ankra-*` kubeconfig contexts with `ankra cluster kubeconfig add`.
* **Cluster metrics** - run PromQL against a cluster's Prometheus with `ankra cluster metrics query` and `query-range`.
* **Full OVH management** - stop/start, SSH access info, control-plane and node-group changes, region discovery, and node labels/taints.
* **Config safety** - gate changes before they go live with `ankra cluster validate` (structure, chart existence, plaintext-secret detection) and stage them with `ankra cluster draft`.
* **Live operations** - follow a deploy or reconcile with `ankra get operations --watch` and `ankra get jobs`.
* **Self-update** - `ankra upgrade` updates or rolls back the CLI in place with checksum verification.

See the [CLI Changelog](/integrations/ankra-cli-changelog) for the full, versioned detail.

## Removed: Add-on Subscriptions

Add-on subscriptions have been retired. Add-ons are now managed directly on the cluster or stack that uses them - through your GitOps repository, `ankra cluster apply`, or the cluster editor - which keeps a single, declarative source of truth for what runs where, rather than a separate subscription that has to be kept in sync.

The legacy add-on subscription endpoints now return `410 Gone`. If you relied on subscriptions, move those add-ons into the relevant stack definition; existing deployed add-ons are unaffected.

**May 2026**

# Editable Stopped-Cluster Topology, Self-Healing Hetzner Updates, Live Operations, and a Big CLI Wave

May focused on cloud-cluster reliability - editable topology while stopped, self-healing Hetzner updates, cleaner offline reconciliation, and a live-updating operations page - alongside a large batch of CLI commands for variables, secrets, dependencies, and in-place upgrades.

## Edit cluster topology while stopped

Stopped cloud clusters (Hetzner, OVH, UpCloud) now expose the full Nodes settings tab. While the cluster stays offline you can:

* Switch the control plane between **1** and **3** controllers (only 1 or 3 - etcd needs an odd number of voting members to form quorum).
* Change the **controller instance type**. Because the cluster is recreated fresh on next start, downgrades are safe here - there is no live disk resize.
* Add and remove **node groups**, scale them, change their worker instance type, and edit labels and taints.

Changes are saved against the stopped topology and applied the next time you start the cluster from the General settings tab. Topology edits now also serialize against each other and against start/stop, so two operators clicking at the same time can't end up with a half-applied change.

[Cluster Settings →](/platform/cluster-nodes)

## Hetzner: Resilient Cluster Updates

Hetzner cluster update jobs are now self-healing. The reconciler persists install-time addresses (`bind-address`, `advertise-address`, `node-ip`) into `/etc/rancher/k3s/config.yaml` so k3s always restarts bound to the correct private IP, and version bumps now swap the k3s binary in place instead of re-running the upstream installer - which previously rewrote the systemd unit and wiped `K3S_URL` / `K3S_TOKEN` on joined nodes. Clusters that had drifted into authentication-error loops after an upgrade recover on the next reconcile.

## Offline Cloud Clusters: Cleaner Reconciliation

When a Hetzner, OVH, or UpCloud cluster is in the **stopped** state (after Delete Kubernetes), the reconciler now only acts on provider-owned resources - servers, networks, SSH keys, the k8s control plane. Addons, manifests, and other in-cluster resources are held until the cluster is back online, so you no longer see repeated failures for resources that have no API server to talk to.

[Hetzner Cluster Lifecycle →](/guides/hetzner-clusters#cluster-lifecycle)

## Operations Page: Live Updates

The cluster **Operations** page now refreshes itself in the background. Newly-triggered operations appear without a manual reload, and the status, duration, and finish time of in-flight operations update as they progress. The page polls faster while something is actively running and slows down once everything is idle, so you get near-real-time feedback while a deploy is happening without hammering the backend when nothing is going on.

## The Ankra CLI: variables, secrets, dependencies, and in-place upgrades

A large batch of stack-management commands landed in the [Ankra CLI](/integrations/ankra-cli) this month:

* **Variables at every scope** - `ankra org variables`, `ankra cluster variables`, and `ankra cluster stacks variables` give full CRUD over the values substituted into manifests and addon values (resolution is stack > cluster > organisation).
* **Live-cluster SOPS** - `ankra cluster encrypt` / `decrypt` run directly against a running cluster's manifests and addon values, with no local `cluster.yaml` needed.
* **Dependencies, reads, and deletes** - edit deployment-ordering parents (`--add-parent` / `--remove-parent` / `--set-parent`), print current addon values and manifest YAML, and delete a manifest from its stack.
* **Surgical upgrades** - `ankra cluster addons upgrade` and `manifests upgrade` change a single Helm value or manifest field in place with helm-style `--set` (field selectors like `containers[name=app]`), `--from-file`, and `--dry-run`.
* **Any organisation** - a global `--org` flag (and `ANKRA_ORG`) runs a command against any organisation you belong to without switching your selection.
* **Curated AI skills** - `ankra skills install` drops Ankra's Agent Skills into Cursor or Claude Code (`--editor claude-code`), embedded in the binary so it works offline.

See the [CLI Changelog](/integrations/ankra-cli-changelog) for the full, versioned detail.

**April 2026**

# Cluster Lifecycle: Delete Kubernetes & Scale Back Up, Multi-Stack Cloning

## Delete Kubernetes & Scale Back Up

Cloud provider clusters (Hetzner, OVH, UpCloud) now support a **Delete Kubernetes** action that destroys all cloud infrastructure - servers, networks, SSH keys - while keeping the cluster registered in Ankra. The cluster moves to a stopped state and you stop incurring infrastructure charges.

When you're ready to bring the cluster back, simply **add a node group**. Ankra automatically restores the full control plane infrastructure (bastion, network, SSH keys, control plane servers), installs Kubernetes, creates your new worker nodes, and begins reconciling stacks and addons. The restored cluster gets entirely fresh infrastructure with new servers and IPs.

Previously existing worker node groups are not restored - the node group you add is the only worker pool. Add additional node groups as needed after the cluster is online.

The **Terminate Cluster** action permanently deletes all infrastructure and removes the cluster from Ankra entirely. This is irreversible.

Both actions are available in cluster **Settings → Danger Zone**.

[Hetzner Cluster Lifecycle →](/guides/hetzner-clusters#cluster-lifecycle) | [Cluster Settings →](/platform/cluster-settings#danger-zone)

## Clone Multiple Stacks to Another Cluster

You can now select multiple stacks and clone them all to another cluster in a single operation. On the **Stacks** page, click any stack card's avatar to start selecting, or click the **Clone Stacks** button next to the search bar to select all. A floating action bar appears showing the selection count with a **Clone to Cluster** button.

The clone dialog shows a live progress bar as each stack is cloned sequentially. Name conflicts are auto-resolved with suffixes. After completion, click **Go to Target Cluster** to review the drafts. Cross-organisation cloning is fully supported.

This is useful for replicating an entire cluster's stack configuration to a new environment, promoting multiple stacks from staging to production, or setting up disaster recovery clusters.

[Clone Stacks Guide →](/guides/clone-stack#clone-multiple-stacks-at-once)

**March 2026**

# Automatic Hetzner Cloud Integration, Ingress & GitOps, Node Groups, UpCloud & OVH Cloud, AI Insights Overhaul, Kubernetes Node Cordon & Drain, Light Mode, Billing & Platform Performance

## Kubernetes Node Cordon, Uncordon & Drain

The **Kubernetes → Nodes** view now supports full node lifecycle management for workload migration scenarios. Cordon, uncordon, and drain nodes from both the node detail page and the node list with multi-select bulk actions.

**Cordon & Uncordon**: Mark nodes as unschedulable or restore scheduling. Available as a single-node action in the node detail header or as a bulk action by selecting multiple nodes in the list. Cordoned nodes display a "SchedulingDisabled" label.

**Drain**: Cordon a node and evict all running pods in one operation - equivalent to `kubectl drain --ignore-daemonsets --delete-emptydir-data`. Real-time progress tracking shows each phase: cordoning, fetching pods, and evicting pods. Available for single nodes and in bulk.

**Workload Migration**: Use cordon and drain together to safely move workloads between node groups. Cordon old nodes to stop new scheduling, drain them to evict existing pods, and let Kubernetes reschedule onto your new node group.

[Kubernetes Nodes →](/platform/kubernetes-nodes)

Hetzner clusters now automatically deploy the Cloud Controller Manager and CSI driver during provisioning - no manual setup. An optional ingress stack adds ingress-nginx, cert-manager, and Let's Encrypt. GitOps integration pushes cluster state to GitHub. Node groups bring per-group instance types, scaling, labels, and taints. UpCloud and OVH Cloud support across the platform. AI Insights gets a dedicated detail page with analytics dashboard, adaptive scanning, and platform-aware remediation. The Command Palette now navigates directly to every Kubernetes resource type, and the Log Viewer is rebuilt for large clusters.

## Hetzner: Automatic CCM & CSI Provisioning

Hetzner clusters now automatically deploy a complete **hcloud stack** during provisioning: a dedicated `hcloud` namespace, API token secret, the [hcloud-cloud-controller-manager](https://github.com/hetznercloud/hcloud-cloud-controller-manager) (3 replicas, PDB), and the [hcloud-csi](https://github.com/hetznercloud/csi-driver) driver (3 replicas, PDB, `hcloud-volumes` default StorageClass). Previously this required manual setup via the AI Assistant or Stack Builder. Now it's fully automated using the same Hetzner API credential used to create the cluster.

## Hetzner: Optional Ingress Stack

Enable `include_ingress` during cluster creation to deploy ingress-nginx with a Hetzner Load Balancer, cert-manager, and a pre-configured `letsencrypt-prod` ClusterIssuer for automatic TLS. Toggle in the UI wizard or pass `"include_ingress": true` in the API.

## Hetzner: GitOps Integration

Push cluster stack state to a GitHub repository on creation. Provide `gitops_credential_name`, `gitops_repository`, and `gitops_branch` to enable version-controlled infrastructure for Hetzner clusters.

## Node Groups Per-Group Instance Types, Labels & Taints

A new **Nodes** tab in cluster settings lets you manage node groups for Hetzner, OVH, and UpCloud clusters. Each node group has its own instance type, node count, Kubernetes labels, and taints giving you fine-grained control over your worker fleet.

**Full Lifecycle Management**: Add, scale (0–100 nodes), upgrade instance type, edit labels/taints, and delete node groups from the UI, CLI, or API. Node groups can be defined at cluster creation time in the wizard or API.

**Instance Type Upgrades**: Upgrade any group to a larger instance type. Each node is powered off, resized, and powered back on. Downgrades are not possible due to Hetzner disk resize limitations. To use a smaller type, create a new node group and delete the old one. The UI shows a confirmation dialog warning that upgrades are irreversible.

**Labels & Taints**: Attach Kubernetes node labels and taints to node groups. Labels and taints are applied to all nodes in the group and can be edited at any time. Useful for workload scheduling with nodeSelectors, affinities, and tolerations.

**No Online Requirement**: Node group operations work regardless of cluster state. No need to wait for the cluster to be online.

**CLI Support**: New `ankra cluster {hetzner|ovh|upcloud} node-group` commands for list, add, scale, upgrade, and delete.

[Hetzner Node Groups →](/guides/operate-ankra-managed-clusters#node-groups) | [Cluster Settings →](/platform/cluster-nodes)

## Hetzner: Multi-SSH-Key Support & Access Settings

Attach multiple SSH key credentials to Hetzner clusters at creation or post-creation. A new **Access** tab in cluster settings provides copy-pasteable SSH jump and kubectl port-forward commands, a network topology view, and SSH key management.

[Hetzner Clusters Guide →](/guides/hetzner-clusters)

## UpCloud Clusters

Provision and manage Kubernetes clusters on UpCloud with managed SDN Routers and NAT Gateways for private networking.

**Full Lifecycle Management**: Create, scale, upgrade, and deprovision UpCloud clusters through the UI, CLI, or API. Clusters deploy with a router, private network, NAT gateway, bastion server, and k3s distribution.

**Zone Support**: Deploy to any UpCloud zone including Helsinki (Finland), Frankfurt (Germany), Chicago (United States), Amsterdam (Netherlands), London (United Kingdom), Singapore, Sydney (Australia), and Warsaw (Poland).

**Worker Scaling**: Scale worker nodes between 1 and 10. Scaling up provisions new instances and installs Kubernetes. Scaling down removes workers from the highest index.

**Kubernetes Upgrades**: Upgrade k3s versions across all nodes with one command. Control planes are upgraded first, then workers.

**DAG-Based Deprovisioning**: Cluster deletion creates a tracked operation with individual delete jobs that run in dependency order. Multiple server deletions run in parallel, reducing deprovision time.

[UpCloud Clusters Guide →](/guides/upcloud-clusters)

## UpCloud API Credentials

Securely store UpCloud API credentials (API token) with automatic validation against the UpCloud API.

**Credential Validation**: Credentials are validated on creation by calling the UpCloud API. Clear error messages for invalid tokens (401) and permission issues.

**SSH Key Support**: Create and manage SSH key credentials for UpCloud cluster provisioning. Generate new keypairs or bring your own public key.

[Credentials Guide →](/platform/credentials/upcloud)

## OVH Cloud Clusters

Provision fully managed Kubernetes clusters on OVH Cloud with configurable control planes, workers, and networking.

**Full Lifecycle Management**: Create, scale, upgrade, and deprovision OVH clusters through the UI, CLI, or API. Clusters deploy with a private network, gateway for SSH access, and k3s distribution.

**Region Support**: Deploy to any OVH Cloud region including Gravelines (France), Strasbourg (France), Beauharnois (Canada), Warsaw (Poland), Frankfurt (Germany), London (UK), Singapore, and Sydney.

**Worker Scaling**: Scale worker nodes between 1 and 10. Scaling up provisions new instances and installs Kubernetes. Scaling down removes workers from the highest index.

**Kubernetes Upgrades**: Upgrade k3s versions across all nodes with one command. Control planes are upgraded first, then workers.

[OVH Clusters Guide →](/guides/ovh-clusters)

## OVH API Credentials

Securely store OVH Cloud API credentials (application key, application secret, consumer key, and project ID) with automatic validation against the OVH API.

**Credential Validation**: Credentials are validated on creation by calling the OVH API. Clear error messages for permission issues (403) and invalid credentials (401).

**SSH Key Support**: Create and manage SSH key credentials for OVH cluster provisioning. Generate new keypairs or bring your own public key.

[Credentials Guide →](/platform/credentials/ovh)

## AI Insights Overhaul

A major upgrade to Proactive AI Insights with a dedicated detail page, analytics dashboard, advanced filtering, adaptive scanning, and platform-aware remediation.

**Insight Detail Page**: Each insight now has a full-page view with four tabs Overview (root cause analysis with summary, severity, confidence score, affected resources, and conversation starters for AI chat), Remediation (copy-pasteable commands and platform-aware actions), Health (snapshot and anomaly data at time of detection), and History (previous resolutions with effectiveness tracking). Navigate to related Kubernetes resources directly from the affected resources list.

**Analytics Dashboard**: New analytics tab with configurable time ranges (7, 30, or 90 days). Tracks mean time to resolution (MTTR), shows severity trends by day, breaks down issues by namespace and category, and indicates whether cluster health is improving, degrading, or stable.

**Dashboard View**: A new dashboard tab on the insights page with a severity donut chart, mini trend chart, and category breakdown at a glance.

**Advanced Filtering**: Filter insights by namespace, category, and date range. Three view modes cards, compact list, and grouped (by category or namespace). Root cause summary shown inline on insight cards.

**Related Insights**: Insights sharing the same namespace or category are linked on the detail page, helping you spot patterns across related issues.

**Adaptive Scanning**: The maintenance scheduler now adapts scan frequency based on cluster health clusters with critical issues are scanned every 60 seconds, clusters with active issues every 3 minutes, and healthy clusters every 10 minutes.

**Platform-Aware Remediation**: AI analysis now suggests platform-native actions (stack changes, add-on configuration, resource navigation) alongside kubectl commands. Remediation commands and platform actions are stored per-insight and displayed on the detail page.

**Resolution Tracking**: Resolving an insight now captures resolution type, resolution context, and a health snapshot at resolution time. When an issue recurs, previous resolutions include effectiveness data so you can see if a past fix held.

**RAG Learning Loop**: Marking an insight as "helpful" indexes its root cause analysis and recommendations for RAG, improving future AI analysis quality.

**Keyboard Shortcuts**: Navigate and manage insights entirely from the keyboard `j`/`k` to navigate, `Enter` to open detail, `p` to quick peek, `a` to acknowledge, `r` to resolve, `d` to dismiss, `c` to ask AI, `/` to search, `1`–`4` to switch tabs, `v` to cycle view mode, and `?` for help.

[AI Insights Docs →](/platform/ai-insights)

## CLI v0.2.0

Helm management, Kubernetes resource access, direct cluster selection, and client hardening.

* `ankra cluster helm releases` / `ankra cluster helm uninstall` - Manage Helm releases in the cluster
* `ankra helm registries` / `ankra helm credentials` - Manage Helm registries and credentials
* `ankra cluster pods` / `ankra cluster resources` / `ankra cluster logs` - Access Kubernetes resources and stream pod logs
* `ankra cluster select <name>` - Select a cluster directly by name without the interactive picker
* `ankra cluster info [name]` - Show cluster details (defaults to selected cluster; replaces `cluster get`)
* HTTP client timeouts, response body limits, URL encoding, config file permission hardening

[CLI Changelog →](/integrations/ankra-cli-changelog) | [Ankra CLI →](/integrations/ankra-cli)

## CLI v0.1.129

Node group management commands and new UpCloud/OVH commands for cluster and credential management.

* `ankra cluster <provider> node-group` - List, add, scale, upgrade, and delete node groups for Hetzner, OVH, and UpCloud
* `ankra credentials upcloud` / `ankra cluster upcloud` - UpCloud credential and cluster management
* `ankra credentials ovh` / `ankra cluster ovh` - OVH credential and cluster management

[CLI Changelog →](/integrations/ankra-cli-changelog) | [Ankra CLI →](/integrations/ankra-cli)

## Node Group API Endpoints

Available for all three cloud providers (Hetzner, OVH, UpCloud):

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/{provider}/{id}/node-groups` | GET | List node groups |
| `/api/v1/clusters/{provider}/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/{provider}/{id}/node-groups/{name}/scale` | PUT | Scale a node group |
| `/api/v1/clusters/{provider}/{id}/node-groups/{name}/instance-type` | PUT | Upgrade instance type |
| `/api/v1/clusters/{provider}/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/{provider}/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/{provider}/{id}/node-groups/{name}` | DELETE | Delete a node group |

[Hetzner Node Groups →](/guides/operate-ankra-managed-clusters#node-groups)

## UpCloud API Endpoints

Full REST API coverage for UpCloud clusters and credentials:

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/upcloud` | POST | Create an UpCloud cluster |
| `/api/v1/clusters/upcloud/{id}` | DELETE | Deprovision a cluster |
| `/api/v1/clusters/upcloud/{id}/worker-count` | GET | Get worker count |
| `/api/v1/clusters/upcloud/{id}/scale-workers` | POST | Scale workers |
| `/api/v1/clusters/upcloud/{id}/k8s-version` | GET | Get Kubernetes version |
| `/api/v1/clusters/upcloud/{id}/upgrade-k8s-version` | POST | Upgrade Kubernetes version |
| `/api/v1/credentials/upcloud` | GET | List UpCloud credentials |
| `/api/v1/credentials/upcloud` | POST | Create an UpCloud credential |
| `/api/v1/credentials/upcloud/ssh-keys` | GET | List SSH key credentials |
| `/api/v1/credentials/upcloud/ssh-key` | POST | Create an SSH key credential |

[API Reference →](/api-reference/introduction)

## OVH API Endpoints

Full REST API coverage for OVH clusters and credentials:

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/ovh` | POST | Create an OVH cluster |
| `/api/v1/clusters/ovh/{id}` | DELETE | Deprovision a cluster |
| `/api/v1/clusters/ovh/{id}/worker-count` | GET | Get worker count |
| `/api/v1/clusters/ovh/{id}/scale-workers` | POST | Scale workers |
| `/api/v1/clusters/ovh/{id}/k8s-version` | GET | Get Kubernetes version |
| `/api/v1/clusters/ovh/{id}/upgrade-k8s-version` | POST | Upgrade Kubernetes version |
| `/api/v1/credentials/ovh` | GET | List OVH credentials |
| `/api/v1/credentials/ovh` | POST | Create an OVH credential |
| `/api/v1/credentials/ovh/ssh-keys` | GET | List SSH key credentials |
| `/api/v1/credentials/ovh/ssh-key` | POST | Create an SSH key credential |

[API Reference →](/api-reference/introduction)

## Command Palette Direct Links to All Kubernetes Resources

The Command Palette (`⌘+K` / `Ctrl+K`) now navigates directly to every Kubernetes resource type in your cluster not just Ankra pages. Type any resource kind and jump straight to it.

**33 Kubernetes resource types** organized by category: Workloads (Pods, Deployments, StatefulSets, DaemonSets, ReplicaSets, Jobs, CronJobs, PodDisruptionBudgets, HorizontalPodAutoscalers), Networking (Services, Ingresses, Ingress Classes, Endpoints, NetworkPolicies, CSI resources), Configuration (ConfigMaps, Secrets, Namespaces, Events), Storage (PersistentVolumes, PVCs, Storage Classes, VolumeAttachments), RBAC (Roles, RoleBindings, ClusterRoles, ClusterRoleBindings, ServiceAccounts, LimitRanges), and more (CRDs, Helm Releases, Nodes).

**New cluster pages**: Logs, Metrics, Resources, General Settings, and GitOps Settings are now accessible from the palette.

**New actions**: Base64 Encode/Decode utilities, Keyboard Shortcuts reference, Documentation link, and Switch Organisation.

[Command Palette →](/platform/command-palette)

## Log Viewer Redesign

Rebuilt the Log Viewer for large clusters and high-volume streams.

**Scalable Pod Loading**: Pods are fetched on-demand per namespace when you select a workload, replacing the previous 500-pod cap that caused "0 pods" for large clusters.

**Accurate Matching**: Pod-to-workload matching now uses Kubernetes label selectors instead of name prefix heuristics.

**Scroll Stability**: Scrolling up to investigate older logs now holds your position even under high-throughput streams. Auto-follow only re-engages on explicit user action.

**Live Filtering**: Search and log level filters apply to incoming lines in real-time, not just existing logs.

**Performance**: Batched rendering (150ms flush interval) with virtualized display handles tens of thousands of log lines without UI freezes.

[Log Viewer Docs →](/platform/logs)

## Light Mode

Full theme customization with Light, Dark, and System modes - the platform is now suitable for bright or dark developer caves. Set your preference from **Profile → Appearance** or use the sidebar theme toggle to cycle modes instantly. Your choice syncs across all devices.

[User Profile →](/platform/user-profile)

## Billing & Subscription Management

Stripe integration with vCPU-based metering, automated invoice generation, and subscription auto-provisioning for new organisations. The billing pipeline covers plan management, usage tracking, invoice history, and Stripe webhook handling. A billing analytics dashboard provides visibility into resource consumption and cost trends.

## Distributed Tracing

OpenTelemetry tracing across the API, maintenance scheduler, and work scheduler services. Request-level observability with trace propagation, structured logging integration, and circuit breaker improvements provide end-to-end visibility into platform operations.

## Registry Performance & Reliability

Registry listing, detail views, and sync operations significantly optimised. Cache invalidation after frontend changes, Harbor edge case handling, and backoff logic for failing registries improve reliability across all registry types.

## Database & Platform Performance

Database index audit with unused index removal via pg\_stat\_statements, improved connection pool management, and reduced database pressure under load. Listing performance improvements across clusters, stacks, and AI insights result in faster page loads throughout the platform.

## Helm Charts Version Tracking

New charts version comparison and a clusters tab showing which clusters run which chart versions, making it easier to track Helm chart drift across your fleet.

**February 2026**

# Hetzner Cloud Provisioning, AI Goes Agentic, Full Observability & Secrets at Scale

Hetzner Cloud provisioning lands across the platform, AI goes agentic with 58 tools, full observability arrives with log streaming and pod terminals, and secrets management scales up with SOPS and variables.

## Hetzner Cloud Provision Clusters from Ankra

Ankra now provisions and manages Hetzner Cloud clusters end-to-end. Create k3s clusters across five Hetzner locations (Falkenstein, Nuremberg, Helsinki, Ashburn, Hillsboro), scale workers, and upgrade Kubernetes all from the dashboard, CLI, or API. The full provisioning pipeline handles networking, SSH keys, bastion servers, control planes, workers, k3s installation, and Ankra Agent setup automatically. Deprovision in one click when you're done.

[Hetzner Clusters Guide →](/guides/hetzner-clusters)

## Hetzner Cluster Provisioning in the Dashboard

A guided wizard walks you through creating a Hetzner cluster select credentials, pick a location, choose server types (cost-optimized, regular, or dedicated vCPU), set control plane and worker counts, and launch. A live provisioning progress view tracks every step from network creation to Ankra Agent installation. Once running, scale workers and upgrade k3s versions directly from cluster settings.

## Hetzner CLI Commands

Full Hetzner lifecycle from your terminal. `ankra cluster hetzner create` provisions a cluster with configurable network ranges, server types, and k3s versions. Scale workers with `ankra cluster hetzner scale`, upgrade Kubernetes with `ankra cluster hetzner upgrade`, and tear everything down with `ankra cluster hetzner deprovision`. Manage Hetzner API tokens and SSH keys via `ankra credentials hetzner` including automatic keypair generation.

[CLI Reference →](/integrations/ankra-cli)

## Hetzner REST API

Every Hetzner operation is available via the REST API with Bearer token authentication. Create and deprovision clusters, scale workers, upgrade k3s, and manage Hetzner credentials and SSH keys programmatically. Integrate Hetzner cluster provisioning into your CI/CD pipelines or custom tooling.

[API Reference →](/api-reference/introduction)

## Sandbox Cluster Try Ankra Instantly

No Kubernetes cluster? No problem. Spin up a sandbox cluster in one click and explore the full Ankra experience: pre-populated nodes, workloads, services, stacks, and live-looking metrics. It's read-only, always online, and requires zero setup. The fastest way to see what Ankra can do.

[Sandbox Docs →](/guides/cluster-sandbox)

## AI Agentic Mode & 58 Tools

The AI Assistant is now a fully autonomous agent. It reads your cluster state, chains up to 10 tool calls per response, and proposes infrastructure changes with a built-in confirmation system. 58 tools span Kubernetes read/write, stack management, and addon lifecycle.

[Learn more →](/platform/ai-assistant)

## AI Incident Reports & Root Cause Analysis

When an alert triggers, Ankra automatically generates a detailed AI incident report with root cause analysis, severity assessment, affected resources, and actionable recommendations. Reports are delivered to Slack, Teams, PagerDuty, Discord, and Opsgenie alongside alert notifications.

[Configure Alerts →](/guides/alerts) | [AI Incidents →](/platform/ai-incidents)

## Alerting Built Into All Ankra Resources

Alerts now monitor every resource type clusters, stacks, addons, manifests, and GitHub repositories. Define custom rules with AND/OR logic, set severity levels, and get notified via six built-in integrations plus generic webhooks.

[Configure Alerts →](/guides/alerts)

## Log Explorer

Stream logs in real-time from up to 20 pods simultaneously with full-text and regex search, auto-detected log levels, adjustable display settings, and export to clipboard or file.

[Learn more →](/platform/logs)

## Terminal to Any Pod

Open an interactive terminal directly into any running pod container from the dashboard. Choose your shell, select the target container, and debug issues without leaving the browser.

## Stack Cloning

Clone any stack between clusters with automatic name conflict resolution, SOPS-encrypted value handling, and parent relationship preservation. Available in the dashboard and via the CLI.

[Clone Stack Guide →](/guides/clone-stack) | [Clone Cluster Guide →](/guides/clone-cluster)

## SOPS Integration with ArgoCD

End-to-end secret encryption using SOPS with AGE keys, fully integrated with ArgoCD. Encrypt specific YAML keys while keeping the rest readable. Automatic decryption during GitOps sync no manual steps.

[SOPS Guide →](/guides/sops)

## Variables: Org, Cluster & Stack Levels

Define reusable variables at three levels with automatic precedence resolution. Use `${{ ankra.variable_name }}` in manifests and Helm values. Mark variables as secrets for masked display in the UI.

[Variables Guide →](/concepts/variables)

## Metrics Revamp

Redesigned metrics with area charts for CPU and memory by node, network RX/TX rate charts, disk I/O, pod restarts by namespace, summary cards, and AI-powered health insights surfaced in dashboard widgets.

[Cluster Metrics →](/platform/cluster-metrics) | [Prometheus Integration →](/integrations/prometheus)

## Multi-Select Delete for Kubernetes Resources

Bulk select and delete Kubernetes resources across 20+ resource types with checkbox selection, confirmation dialog, sequential deletion with progress tracking, and per-item error reporting.

## CLI v0.1.125 & API Updates

New SOPS encryption commands replace the old `ankra cluster sops` command. Granular encrypt/decrypt for manifests and addon values. Full REST API with Bearer token auth, alerts API with AI analysis endpoints, and interactive OpenAPI docs.

[Ankra CLI →](/integrations/ankra-cli) | [API Reference →](/api-reference/introduction)

**December 2025**

# Dashboard V2

A completely redesigned dashboard with real-time health monitoring, AI insights, and guided onboarding.

## Health Overview Grid

Visual cluster cards sorted by health status with critical issues surfaced first.

**Status Indicators**: Color-coded health status (healthy, warning, critical, offline) with animated pulse for critical issues.

**Resource Breakdown**: Running, pending, and failed resource counts with visual progress bars.

**Quick Actions**: Create stacks directly from cluster cards. GitOps connection and agent update indicators visible at a glance.

## Operations & Alerts

**Alerts Summary**: Real-time alert statistics with severity breakdown and quick navigation to alert management.

**Operations Activity**: Timeline of recent operations across all clusters with status, progress, and timestamps.

## GitOps & AI Insights

**GitOps Sync Status**: Repository connection overview showing connected vs disconnected clusters with direct links to configuration.

**AI Insights**: Summary of recent AI-powered analyses including incident investigations and cluster health assessments.

## Stacks & Registries

**Stacks Overview**: Stack deployment statistics per cluster with status indicators.

**Helm Repositories**: Connected registry summary with sync status and navigation to registry management.

**Recently Accessed**: Quick access to your most recently viewed resources across all clusters.

## Onboarding Experience

**Guided Setup**: Step-by-step checklist for new users with video tutorials and documentation links.

**Progress Tracking**: Floating progress widget showing completion percentage. Dismissible once core setup is complete.

**Quick Actions Bar**: Common actions accessible from the dashboard including import cluster and command palette shortcuts.

## Stack Builder Improvements

**Node Position Management**: Improved automatic layout calculations and smoother drag-and-drop interactions.

**Performance**: Faster stack loading with reduced API calls and improved caching.

**Bug Fixes**: Fixed manifest rename inconsistencies and improved Bill of Materials calculations.

## Performance & Stability

**Backend Optimizations**: Optimized database queries and reduced API response times.

**WebSocket Support**: Real-time updates via WebSocket for faster event propagation.

**Resource Limits**: Increased API limits for clusters with larger resource counts.

## AI Assistant

**Mobile View**: Improved responsive layout and touch interactions for mobile devices.

## Agent Updates

**ArgoCD SSL Handling**: Fixed SSL verification issues and improved certificate handling.

**Label Selector**: Enhanced resource filtering and ArgoCD relationship handling.

**November 2025**

# AI Takes Center Stage

This month we've revamped our documentation to put the AI Assistant front and center, added comprehensive guides for building production stacks, and expanded integrations.

## Stack Builder

The visual Stack Builder is now a first-class citizen with comprehensive documentation.

**ReactFlow Canvas**: Drag-and-drop interface powered by ReactFlow for composing add-ons and manifests into deployable stacks.

**Visual Dependency Management**: Connect components on the canvas to define deployment order. Arrows show the flow source deploys before target.

**Draft Stacks**: Work-in-progress configurations with auto-save, validation, and preview before publishing.

**Node Operations**: Click any component to edit values, view deployment status, or configure namespaces. Safe node deletion prevents dangling edges.

**Stack Cloning**: Clone any Stack to quickly create variations. Deploy the same Stack across dev, staging, and production with environment-specific tweaks.

**AI-Powered Assistance**: Describe what you need and the AI recommends add-ons, suggests configurations, and provides guidance on dependencies.

**CLI Integration**: Manage Stacks from the terminal with the Ankra CLI:

* `ankra get stacks` List all stacks in the active cluster
* `ankra get stacks <name>` View stack details with manifests and addons
* `ankra clone <source> <dest>` Clone stacks between clusters
* `ankra applyf stack.yaml` Apply stack configurations

Perfect for CI/CD pipelines and automation.

[Explore Stack Builder →](/concepts/stacks)

## Insight Metrics

Real-time cluster metrics powered by Prometheus integration.

**Resource Usage Cards**: At-a-glance CPU and memory utilization across your cluster with current values and totals.

**Time Series Charts**: Interactive graphs for CPU by node, memory by node, disk I/O, and network traffic (RX/TX).

**Pod Restarts**: Bar chart showing restart counts by namespace to quickly identify unstable workloads.

**Configurable Time Ranges**: View metrics from 15 minutes to 7 days with automatic refresh intervals.

**Node-Level Drill-Down**: Click any series to isolate and focus on specific nodes.

## Helm Charts & Registries

Completely revamped Helm chart discovery and registry management.

**Chart Explorer**: Browse, search, and filter Helm charts from all connected registries. View chart metadata, versions, and dependencies.

**HTTP & OCI Registries**: Full support for both HTTP-based Helm repositories and OCI registries (GHCR, GAR, ECR, ACR, Docker Hub, Harbor).

**Auto-Sync**: Registries sync automatically to keep chart catalogs up to date. Configure sync intervals per registry.

**Credential Management**: Securely store and manage registry credentials with support for tokens, basic auth, and cloud provider authentication.

[Explore Helm Charts →](/platform/addon-catalog) | [Registry Setup →](/integrations/helm-registries)

## Alerting

New alerting system to stay on top of cluster issues.

**Slack Webhooks**: Send alerts directly to Slack channels via incoming webhooks. Configure per-cluster or organisation-wide.

**Alert Rules**: Define custom alert conditions based on cluster events, resource states, and thresholds.

**Event-Driven Notifications**: Get notified on deployments, failures, scaling events, and health changes.

[Configure Alerts →](/guides/alerts)

## AI Assistant Enhancements

The AI Assistant is now the centerpiece of the Ankra experience.

**Page-Aware Context**: The AI automatically knows what you're looking at. Open a pod and it already has the logs, manifest, events, and related resources. No copy-pasting or explaining.

**Incident Triangulation**: Root cause analysis across multiple data sources:

* Container logs with error detection
* Prometheus metrics and anomalies
* Kubernetes manifests and configurations
* Stack deployment history and changes
* Resource relationships and dependencies

**Stack Building**: Describe infrastructure in natural language and the AI helps you build it:

* *"I need a monitoring stack with Prometheus and Grafana"*
* AI recommends add-ons, suggests values, and explains dependencies
* You add the components to your Stack based on the recommendations
* Review and deploy with one click

**Unified Context Layers**: The AI combines all context for comprehensive understanding:

| Layer | What AI Sees |
| - | - |
| Logs | Container stdout/stderr, error patterns |
| Metrics | CPU, memory, network, custom metrics |
| Manifests | Current and desired state, diffs |
| Events | Kubernetes events, warnings, errors |
| History | Deployment timeline, who changed what |

**New Shortcut**: Press `⌘+J` (Mac) or `Ctrl+J` (Windows/Linux) from anywhere.

**Claude Opus 4.5**: The AI Assistant now runs on Claude Opus 4.5 Anthropic's most capable model by default. No configuration needed.

[Learn more →](/platform/ai-assistant)

## New Guides

**Build a Monitoring Stack**: Step-by-step guide to deploy kube-prometheus-stack with Loki for logs. [Read the guide](/guides/monitoring-stack)

**Cloudflare Tunnel**: Expose services without public IPs or open firewall ports. [Read the guide](/guides/cloudflare-tunnel)

## New Integrations

**Prometheus**: Connect your Prometheus instance as a metrics data source. Powers Insight Metrics and AI analysis. [Learn more](/integrations/prometheus)

**Helm Registries**: Expanded documentation for HTTP and OCI registries with provider-specific setup. [Learn more](/integrations/helm-registries)

## New Documentation

**Kubernetes Resources**: Complete pages for Workloads, Networking, Storage, Configuration, and RBAC.

**Command Palette Guide**: Full reference for `⌘+K` navigation, shortcuts, and commands. [Learn more](/platform/command-palette)

## Documentation Improvements

**Restructured Navigation**: Reorganized into logical groups with AI Assistant prominently featured in Get Started.

**Consistent Formatting**: Standardized formatting across all pages.

**June 2025**

# Supercharging Stack Builder & Workflows!

Safety, speed, visibility & brand-new integrations-everything you need to build, manage, and share infra.

## Stack Builder

**Safe Node Deletion**: Prevent new nodes linking to those being removed-no dangling edges or race conditions.

**Drag-and-Drop Layout**: Manually reposition nodes, then snap them back into a tidy grid with "Reorder."

**Reconcile Quick-Jump**: Click a resource's badge to dive directly into the underlying operation.

**Unsaved-Changes Prompt**: Real-time draft indicators highlight pending edits-and you'll be warned before leaving.

## Agent & Import Flow

**Upgrade Available**: Get notified when a new agent version is available-no more missing out on improvements.

**Pending-Upgrade Fix**: Agents no longer stall in "pending-upgrade"-rollbacks are a thing of the past.

## AI & Automation

**In-Context AI Chat**: AI Assistant now lives on every page-get guidance right where you work. It's like having a personal DevOps expert at your fingertips.

**Chat History**: View past conversations in the AI Assistant sidebar-no more lost context.

**Anthropic Models**: Use some of the most advanced AI models available today. Choose between: Claude 3.5 Haiku, Claude 3.7 Sonnet, Claude Sonnet 4 and Claude Opus 4.

## Resource & CRD Management

**CRD Explorer**: Browse all CRDs in-app, with filters to zero in on exactly what you need.

**IaC Source View**: Click "View Source" on any generated resource to inspect the GitHub-hosted files.

## Search & Shareability

**Shareable URLs**: Bookmark or share any filtered list-teammates see exactly what you see.

**Enter-Key Power-Up**: Press Enter in ⌘+K to immediately run searches or actions.

## Integrations & Ecosystem

**Terraform Provider (Alpha)**: Define clusters, stacks, and add-ons as code-live on Terraform & OpenTofu. [Read Docs](https://docs.ankra.ai/integrations/terraform)

**Monitoring Stack Walk-Through**: Step-by-step video guide with GitOps examples. [Watch Video](https://www.youtube.com/watch?v=__EQEh0GZAY\&t=4s)

**GitOps Enhancements**: Bidirectional syncing & auto-cleanup of stale files. [Learn More](https://docs.ankra.ai/essentials/cluster-gitops-multiple)

**Ankra CLI**: Scriptable imports, builds, and add-on management right in your terminal. [Get the CLI](https://docs.ankra.ai/integrations/ankra-cli)

## Usability & Productivity

**Sidebar State Saver**: Hide or show the sidebar without losing your custom panel layout.

**Download & Copy**: One-click download or copy of cluster add-on configs for backups and sharing.

**Improved Error Messages**: Actionable hints (e.g. invalid URL format) instead of cryptic failures.

**OCI-Backed Add-on Sources**: Support for OCI Helm charts now live-private & credential-based OCI coming next month.

**May 2025**

# Stack Builder, Supercharging Infrastructure!

The new Stack Builder update is packed with features to speed up your workflows and make infrastructure building easier than ever. Here's what's live:

## Stack Builder: Go from 0 to 100 in 2.3s

**Unified Stacks**: Build with manifests and add‑ons side by side. Apply your organisation's custom configs and get add‑ons working out of the box.

**Cluster Manifest List & View**: Instantly browse and inspect all manifests in your cluster.

**Edge Management**: Delete and manage edges in your stack. Nodes now require at least one incoming edge for safety.

**Live Node Status**: See the status of each node directly from the builder review. Watch it go from planned to live from within the interactive builder.

**Cluster Stack Deletion**: Instantly remove entire stacks when you need to reset.

## Repository & GitOps Integration

**Repo Sync**: Keep your infrastructure and code always in sync.

**Create GitHub Repo**: Launch new repositories directly from Ankra, ready for GitOps.

**GitHub Credential Banner**: Get notified if your integration needs attention. Every cluster needs a GitHub repo for full GitOps integration and to build your first stack.

## AI & Automation

**AI Stack Recommendations**: Get AI-powered recommendations for building infrastructure stacks.

**AI Assistant**: When you select an add‑on or manifest, the assistant guides you through creating and understanding manifests.

## Team Collaboration

**Multi‑Org & Multi‑User**: Easily invite your team and collaborate across multiple organisations.

## Add‑on Experience

**Stack Add‑on Cards**: Visual add‑on cards for fast browsing.

**Add‑on Listing Toggle**: Switch between only subscribed add‑ons and all available for easier management.

## Usability & Productivity

**LocalStorage Drafts**: Your changes are auto‑saved as you work.

**Background Stack Refresh**: See instant, real‑time updates to your stacks.

**Parent Validation**: Prevents duplicate names and parent mismatches automatically.

**Live Documentation**: Comprehensive documentation is now available across the platform.

**March–April 2025**

# Enhanced import cluster flow with automated drafts, agent improvements, and expanded Kubernetes resource insights

## Upgraded Import Cluster Flow

**Cluster Drafts Saved Automatically**: Drafts persist in your browser session so you never lose your work if you navigate away. Resume drafts by clicking the island at the top center of any page.

**Real‑Time Stack Building**: When you have a draft, click the floating Add button in the top "island" panel to watch your full YAML manifest assemble live. Once you're done looking around the add‑ons and profiles, click the import icon to return to the draft and submit it for completion to get the command and import your cluster.

## Import Cluster Agent Enhancements

**Seamless Local‑to‑Cloud Parity**: Use the `helm install ankra-agent` command from the import cluster on your laptop or on your Kubernetes clusters.

**Expanded Resource Insights**: Live access to Kubernetes resources.

**ARM & macOS Native Support**: Prebuilt binaries for Apple Silicon (M1/M2) and generic ARM64 servers. Easy helm install from the import cluster: `helm install ankra-agent`.

## Roadmap Preview: Kubernetes‑Native Integrations

Upcoming support for streaming capabilities that will allow real‑time exploration of the Kubernetes environment:

* Expand ArgoCD integration to simplify troubleshooting
* Log streaming of pods
* Creation of Kubernetes resources with add‑ons

## Cluster Add‑on Management

**Add Multiple Add‑ons**: When you click add‑ons of an existing cluster, you can now add a stack of add‑ons in a single form. Just keep selecting add‑ons from the options.

## Bug Fixes & Improvements

**General Fixes**: Resolved an issue where multi‑line strings were not being preserved.

**Quality of Life Improvements**: General improvements in the UI for a better user experience.


# Add-on Settings
Source: https://docs.ankra.ai/concepts/addon-settings

Configure sync policies, retry behaviour, health checks, and ignore rules for your add-ons.

Once an add-on is deployed, you decide how Ankra keeps it that way: whether drift is corrected automatically, what is pruned, how failures are retried, and which fields to ignore. This page lists every one of those settings and what it does. They apply to standalone add-ons and to add-ons inside Stacks.

## Overview

On the native engine, the default for new clusters, the Ankra agent applies these settings with Helm. A cluster still on ArgoCD uses the same fields for the add-on's ArgoCD Application. The [Deployment Engines](/concepts/deployment-engines#feature-parity) parity table shows how each engine honours them. You can change the settings from:

* **Stack Builder** - click any add-on and open the **Settings** tab
* **Standalone Add-ons** - open the add-on and click **Settings**

Changes made in the Stack Builder are applied when you save the stack. Changes to standalone add-ons are applied immediately.

***

## Settings Profiles

Profiles are pre-configured bundles of settings optimized for common scenarios. Select a profile to quickly apply recommended values, or choose **Custom** to configure each setting individually.

| Profile | Automated Sync | Auto Prune | Self Heal | Health Check | Revision Limit | Best For |
| - | :-: | :-: | :-: | :-: | :-: | - |
| **Default** | On | On | On | Off | 10 | Most add-ons |
| **Development** | On | On | On | Off | 5 | Fast iteration, dev/staging clusters |
| **Production Critical** | Off | Off | Off | On | 20 | Critical workloads requiring manual control |
| **Stateful** | On | Off | On | Off | 10 | Databases, message queues, stateful apps |

Changing any individual setting automatically switches the profile to **Custom**.

***

## Sync Policy

The sync policy determines how Ankra responds to changes in the desired state and to drift in your cluster.

### Automated Sync

When enabled, your add-on is synced automatically whenever its desired state changes. When disabled, you must trigger syncs manually.

### Auto Prune

When enabled alongside Automated Sync, Kubernetes resources that are no longer part of the add-on's desired state are deleted automatically. This keeps your cluster clean but means removing a resource from your stack will delete it from the cluster.

> [!WARNING]
>
> Auto Prune can delete resources that were removed from your Git repository. Make sure you intend to remove them before enabling this option.

### Self Heal

When enabled alongside Automated Sync, manual changes made directly to the cluster are reverted automatically. If someone modifies a resource with `kubectl`, the drift is detected and the resource is restored to match the desired state.

***

## Sync Options

Sync options are flags that control specific behaviours during synchronization, named after their ArgoCD equivalents. You can select multiple options.

> [!NOTE]
>
> Sync options apply only to add-ons on clusters that still use the [ArgoCD engine](/concepts/deployment-engines). The native engine, the default, does not read them: it always creates the target namespace, and it handles drift with the settings on this page that it does honour - Auto Prune, Self Heal, the sync window, Ignore Differences, the retry policy, the revision history limit and rollback on failure.

| Option | Description |
| - | - |
| **Create Namespace** | Automatically create the target namespace if it does not exist |
| **Server-Side Apply** | Use Kubernetes server-side apply instead of client-side. Recommended for large resources and CRDs |
| **Apply Out-of-Sync Only** | Only apply resources that are out of sync, skipping unchanged resources. Reduces sync time |
| **Respect Ignore Differences** | Honor ignore difference rules during sync. Automatically enabled when ignore rules are present |
| **Prune Propagation: Foreground** | Wait for dependent resources to be deleted before removing the parent |
| **Prune Propagation: Background** | Delete the parent immediately and let Kubernetes garbage-collect dependents |
| **Prune Propagation: Orphan** | Remove the parent but leave dependent resources in place |
| **Prune Last** | Prune resources only after all other sync operations complete |
| **Replace** | Use `kubectl replace` instead of `kubectl apply`. Useful when apply fails due to field conflicts |
| **Fail on Shared Resource** | Fail the sync if a resource is already managed by another ArgoCD Application |

> [!TIP]
>
> **Server-Side Apply** and **Create Namespace** are enabled by default in most profiles. Server-Side Apply is recommended because it handles large objects and field conflicts better than client-side apply.

***

## Health & Revisions

### Strict Health Check

When enabled, Ankra requires **all** resources created by the add-on to report a healthy status before considering the deployment successful. This is useful for production-critical add-ons where partial deployments are unacceptable.

When disabled (default), the sync is considered successful as soon as resources are applied, regardless of their health status.

### Revision History Limit

Controls how many previous revisions are retained (1-100; Helm's `--history-max` on the native engine). Higher values consume more storage but make it easier to audit changes and understand deployment history. The default is **10**.

***

## Retry Policy

The retry policy controls automatic retry behaviour when a sync operation fails.

| Field | Description | Default |
| - | - | - |
| **Retry Limit** | Maximum number of retry attempts (0-100) | 5 |
| **Backoff Factor** | Multiplier applied to delay between retries (1-10) | 2 |
| **Initial Delay** | Wait time before the first retry (e.g. `5s`, `1m`) | 5s |
| **Max Delay** | Maximum wait time between retries (e.g. `3m`, `10m`) | 3m |

Retries use exponential backoff: each retry waits longer than the previous one, up to the max delay. For example, with the defaults, retries happen at approximately 5s, 10s, 20s, 40s, and 80s (capped at 3m).

***

## Sync Window

Sync windows restrict when your add-on may be synchronized. This is useful for enforcing change-management policies, such as only allowing deployments during business hours or maintenance windows.

| Field | Description | Example |
| - | - | - |
| **Schedule** | Cron expression defining when the window opens | `0 22 * * *` (daily at 10 PM) |
| **Duration** | How long the window stays open | `1h`, `30m`, `2h` |
| **Timezone** | Timezone for the cron schedule | `UTC`, `Europe/Berlin`, `US/Eastern` |

When a sync window is active, the add-on is only synced during the defined window. Outside the window, changes accumulate and are applied when the next window opens.

***

## Ignore Differences

Ignore Differences lets you skip specific fields when comparing the desired state with the live state (cluster). This prevents false drift reports caused by fields that are mutated at runtime by Kubernetes controllers, webhooks, or operators.

### Why Ignore Differences?

Ankra continuously compares the desired state with the live cluster state and reports drift when they differ. However, some fields are legitimately modified after deployment:

* **Webhook controllers** inject `caBundle` values into webhook configurations
* **Kubernetes** assigns `clusterIP` to Services automatically
* **Operators** update status fields and annotations on custom resources
* **Controllers** like `kube-controller-manager` set default values on resources

Without ignore rules, these runtime mutations cause constant OutOfSync status, triggering unnecessary syncs (with auto-sync) or masking real configuration drift.

### Resource Selectors

Each ignore rule can be scoped to specific resources using optional selectors:

| Field | Description | Example |
| - | - | - |
| **Kind** | Kubernetes resource kind | `ValidatingWebhookConfiguration` |
| **Group** | API group of the resource | `admissionregistration.k8s.io` |
| **Name** | Specific resource name | `istio-validator-istio-system` |
| **Namespace** | Namespace of the resource | `istio-system` |

All selectors are optional. Omitting a selector means the rule matches all values for that field. For example, a rule with only `Kind: Service` and no name or namespace applies to every Service in the add-on.

### Matching Methods

Each rule must include at least one of the following methods to specify which fields to ignore.

#### JSON Pointers

JSON Pointers ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) are path-based references into a JSON document. They use `/` as a separator and numeric indices for arrays.

**Syntax:** `/path/to/field` or `/path/0/arrayElement`

**Examples:**

| Pointer | What it targets |
| - | - |
| `/spec/clusterIP` | The `clusterIP` field on a Service |
| `/webhooks/0/clientConfig/caBundle` | The `caBundle` of the first webhook |
| `/metadata/annotations/kubectl.kubernetes.io~1last-applied-configuration` | An annotation (note: `/` in keys is escaped as `~1`) |
| `/status` | The entire status subresource |

> [!TIP]
>
> Use JSON Pointers when you need to target a specific array index or a straightforward field path. They are simple and well-suited for most use cases.

#### JQ Path Expressions

JQ path expressions use the [jq](https://jqlang.github.io/jq/) query language syntax to target fields. They are more flexible than JSON Pointers and support wildcards and array iteration.

**Syntax:** `.path.to.field` or `.path[0].arrayElement`

**Examples:**

| Expression | What it targets |
| - | - |
| `.spec.clusterIP` | The `clusterIP` field on a Service |
| `.webhooks[0].clientConfig.caBundle` | The `caBundle` of the first webhook |
| `.webhooks[].clientConfig.caBundle` | The `caBundle` of **all** webhooks (wildcard) |
| `.metadata.annotations["kubectl.kubernetes.io/last-applied-configuration"]` | An annotation with special characters in the key |
| `.status` | The entire status subresource |

> [!TIP]
>
> Use JQ Path Expressions when you need wildcards (e.g. `.webhooks[]` to match all array elements) or when targeting fields with special characters in their keys.

#### Managed Fields Managers

Instead of targeting specific fields, you can ignore all fields managed by a particular controller or process. Kubernetes tracks which controller "owns" each field through its [Server-Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/) mechanism.

**Examples:**

| Manager | What it covers |
| - | - |
| `kube-controller-manager` | Fields set by the Kubernetes controller manager (e.g. default values, status updates) |
| `clusterrole-aggregation-controller` | Aggregated rules on ClusterRoles |
| `cert-manager-cainjector` | CA bundle fields injected by cert-manager |

> [!WARNING]
>
> Managed Fields Managers is the broadest matching method. It ignores **all** fields owned by that manager, which may include fields you want tracked. Use it only when you trust the controller's mutations entirely.

### Common Examples

> [accordion] Webhook caBundle (ValidatingWebhookConfiguration)
>
> Webhook controllers like cert-manager inject a `caBundle` into webhook configurations after deployment. This is one of the most common causes of false OutOfSync status.
>
> | Field | Value |
> | - | - |
> | **Kind** | `ValidatingWebhookConfiguration` |
> | **Group** | `admissionregistration.k8s.io` |
> | **JSON Pointer** | `/webhooks/0/clientConfig/caBundle` |
>
> Or to cover all webhooks in the configuration using JQ:
>
> | Field | Value |
> | - | - |
> | **Kind** | `ValidatingWebhookConfiguration` |
> | **Group** | `admissionregistration.k8s.io` |
> | **JQ Path Expression** | `.webhooks[].clientConfig.caBundle` |
>
> This also applies to `MutatingWebhookConfiguration` resources.

> [accordion] Service clusterIP and clusterIPs
>
> Kubernetes assigns `clusterIP` and `clusterIPs` automatically when a Service is created. These values are not in your Helm chart but will appear in the live resource.
>
> | Field | Value |
> | - | - |
> | **Kind** | `Service` |
> | **JSON Pointers** | `/spec/clusterIP`, `/spec/clusterIPs` |

> [accordion] Aggregated ClusterRole Rules
>
> When using ClusterRole aggregation, the `kube-controller-manager` merges rules from multiple ClusterRoles. The aggregated `rules` field will differ from what is defined in Git.
>
> | Field | Value |
> | - | - |
> | **Kind** | `ClusterRole` |
> | **Group** | `rbac.authorization.k8s.io` |
> | **Managed Fields Manager** | `clusterrole-aggregation-controller` |

> [accordion] Status Fields on Custom Resources
>
> Operators and controllers frequently update the `.status` subresource on CRDs. Since status is managed by controllers and not by your Helm chart, these changes cause false diffs.
>
> | Field | Value |
> | - | - |
> | **Kind** | Your CRD kind (e.g. `Certificate`, `IngressRoute`) |
> | **JQ Path Expression** | `.status` |

> [accordion] Annotation Mutations by Controllers
>
> Some controllers add or modify annotations on resources. For example, `kubectl.kubernetes.io/last-applied-configuration` is added by client-side apply.
>
> | Field | Value |
> | - | - |
> | **JSON Pointer** | `/metadata/annotations/kubectl.kubernetes.io~1last-applied-configuration` |
>
> Or with JQ (no escaping needed):
>
> | Field | Value |
> | - | - |
> | **JQ Path Expression** | `.metadata.annotations["kubectl.kubernetes.io/last-applied-configuration"]` |

> [accordion] StatefulSet VolumeClaimTemplates
>
> Kubernetes mutates `volumeClaimTemplates` on StatefulSets after creation, adding defaults like `storageClassName`, `volumeMode`, and `status`. These fields are not in your Helm chart but appear in the live resource.
>
> | Field | Value |
> | - | - |
> | **Kind** | `StatefulSet` |
> | **Group** | `apps` |
> | **JQ Path Expression** | `.spec.volumeClaimTemplates[]` |
>
> For more targeted ignoring, you can narrow to specific subfields:
>
> | Field | Value |
> | - | - |
> | **Kind** | `StatefulSet` |
> | **Group** | `apps` |
> | **JSON Pointers** | `/spec/volumeClaimTemplates/0/spec/volumeMode`, `/spec/volumeClaimTemplates/0/status` |

> [accordion] Fields Managed by kube-controller-manager
>
> The Kubernetes controller manager sets default values on many resources (e.g. default service account tokens, pod tolerations). Use a Managed Fields Manager rule to ignore all of them at once.
>
> | Field | Value |
> | - | - |
> | **Managed Fields Manager** | `kube-controller-manager` |
>
> This applies broadly, so only use it on resources where you want to ignore all controller-managed fields.

### Important Behaviors

> [!NOTE]
>
> **Rules need a diff specifier.** Each ignore rule must include at least one JSON Pointer, JQ Path Expression, or Managed Fields Manager. Rules with only resource selectors (Kind, Group, Name, Namespace) and no diff specifier are silently ignored.

> [!NOTE]
>
> **RespectIgnoreDifferences is automatic.** When you add ignore rules, the `RespectIgnoreDifferences=true` sync option is automatically enabled. You do not need to add it manually.

> [!NOTE]
>
> **Custom profile.** Adding or modifying ignore rules automatically switches your settings profile to **Custom**.

***

## Backup Override

An add-on's `backup` settings override the [backup policy of the stack it belongs to](/guides/backups#protect-a-stack), for the one member of a protected stack that has to be captured differently - a cache nobody wants copied to object storage every night, or a database that needs a longer tail than the rest.

**An add-on with no `backup` block follows its stack, and that is the right answer for almost every add-on.** The override is not a second place to turn protection on: a stack that is not protected captures nothing, whatever its add-ons say.

| Field | Meaning |
| - | - |
| `enabled` | Whether this add-on's data assets are captured under the stack's policy |
| `consistency` | How the capture is taken: `transactional`, `application`, `crash` or `logical`. **Leave it empty** unless you have a reason - empty keeps the engine's own answer, and an override claiming more than the engine delivers is a lie about the restore point |
| `schedule` | `hourly`, `daily`, `weekly` or a cron expression. Empty inherits the stack's |
| `retention.hourly` / `.daily` / `.weekly` / `.monthly` / `.yearly` | How many restore points of each period to keep for this add-on. Absent inherits the stack's |
| `retention.minimum_count` | Keep at least this many, however the tiers fall out |
| `retention.minimum_age` | A duration (`24h`, `720h`). Nothing younger is expired |

```bash theme={null}
ankra cluster addons settings get cnpg-cluster
ankra cluster addons settings set redis-cache --backup-enabled=false
ankra cluster addons settings set cnpg-cluster \
  --backup-enabled=true --backup-consistency=transactional \
  --backup-retention-monthly=12
```

> [!NOTE]
>
> **The Stateful profile turns it on.** Choosing **Stateful** for an add-on enables its backup override, because an add-on somebody chose stateful settings for is an add-on with data. As with every other setting, changing one by hand switches the profile to **Custom**.

***

## Related

> [card] [Backups and restore points](/guides/backups)
>
> Protect a stack, take restore points, and restore one.

> [card] [Add-ons](/concepts/addons)
>
> Learn about add-on architecture and deployment.

> [card] [Stacks](/concepts/stacks)
>
> Bundle add-ons into reusable stacks.

> [card] [GitOps](/concepts/gitops)
>
> Understand the GitOps workflow.

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt sensitive add-on values.


# Add-ons
Source: https://docs.ankra.ai/concepts/addons

Manage and deploy Helm add-ons that Ankra installs and keeps reconciled on your clusters.

> [!NOTE]
>
> Add-ons are Helm charts that Ankra deploys to your clusters and keeps reconciled. They provide a standardized way to extend your clusters with monitoring, networking, security, and custom applications.

## What is an Add-on?

An add-on is a packaged application or tool that extends the functionality of your Kubernetes cluster. Add-ons are distributed as Helm charts and can include anything from monitoring tools and ingress controllers to security solutions and custom integrations. An add-on could even be your own application, integrated into the Ankra ecosystem for easy deployment and management.

***

## Architecture Overview

Understanding how add-ons flow from configuration to deployment helps you manage them effectively.

### Deployment Pipeline

```mermaid theme={null}
flowchart LR
    Stack[Stack Builder or Git] --> Platform[Ankra platform]
    Platform --> Agent[Ankra agent]
    Agent --> Helm[helm upgrade --install]
    Helm --> K8s[Kubernetes Resources]
```

**How it works:**

1. **Stack Builder or Git**: You configure add-ons with values and dependencies in the Stack Builder, or in a connected [GitOps repository](/concepts/gitops)
2. **Ankra platform**: Stores the desired state of the stack and dispatches the deploy
3. **Ankra agent**: Receives the deploy inside your cluster
4. **Helm release**: The agent runs `helm upgrade --install` with your values; the step succeeds once the release is healthy
5. **Kubernetes Resources**: The rendered manifests are applied to your cluster

This is the **native** engine, the default for new clusters. Clusters created before it may still use the ArgoCD engine, where an ArgoCD installation in the cluster applies the chart instead; the stack you build is the same either way. See [Deployment Engines](/concepts/deployment-engines).

### Add-on Status

An add-on's status in the dashboard shows whether its latest deploy succeeded and whether the release has drifted from the desired state. The agent reports drift to the platform, and an add-on whose settings enable self-heal is reconciled back. See [Deployment Engines](/concepts/deployment-engines) for how each engine detects and heals drift.

***

## Resource Hierarchy

Each add-on creates a hierarchy of Kubernetes resources. Understanding this hierarchy helps with troubleshooting and resource management.

### Typical Add-on Resource Structure

```mermaid theme={null}
flowchart TD
    App[Helm release] --> NS[Namespace]
    App --> Deploy[Deployments]
    App --> SVC[Services]
    App --> CM[ConfigMaps]
    App --> Secret[Secrets]
    Deploy --> RS[ReplicaSets]
    RS --> Pod[Pods]
    SVC --> EP[Endpoints]
```

**Resource types commonly created by add-ons:**

| Category | Resources |
| - | - |
| **Workloads** | Deployments, StatefulSets, DaemonSets, Jobs |
| **Networking** | Services, Ingresses, NetworkPolicies |
| **Configuration** | ConfigMaps, Secrets |
| **Storage** | PersistentVolumeClaims |
| **RBAC** | ServiceAccounts, Roles, RoleBindings |
| **Custom** | CRDs and custom resources |

Navigate to any installed add-on and open its [Resource Map](#resource-map) to see this hierarchy live for your cluster.

***

## Continuous Delivery Flow

**1. Configuration Change**

You modify add-on values in the Stack Builder, or update values in your connected Git repository.

**2. Change detected**

A change made in the Stack Builder is deployed when you deploy the stack. A change pushed to Git is picked up through the repository's webhook (or periodic polling).

**3. Deploy**

The agent applies the difference with Helm on the native engine, or through ArgoCD on a cluster still using that engine.

**4. Health Check**

The deploy is not marked successful until the release's resources are healthy.

### Sync Settings

Each add-on's settings control how it is kept in sync:

| Setting | Behavior |
| - | - |
| **Automated sync** | Changes to the desired state deploy to the cluster automatically |
| **Self-Heal** | Manual changes made in the cluster are reverted to match the desired state |
| **Prune** | Resources removed from the desired state are deleted from the cluster |

Both engines support these; see [Add-on Settings](/concepts/addon-settings).

***

## Manage Add-on Sources

An add-on source in Ankra is either a Helm repository URL or an OCI (Open Container Initiative) registry URL. These sources contain the Helm charts you want to use for deploying add-ons to your clusters. Helm charts are a standard way to package Kubernetes applications, making it easy to manage dependencies and versioning for complex workloads.

By connecting both public and private Helm repositories or OCI registries, you can access a wide range of Kubernetes add-ons. This lets you integrate open-source tools, vendor solutions, or your own custom charts - all from a single interface. Managing sources centrally ensures your team always has access to the latest and most secure versions of your preferred add-ons.

Setup steps live in one place: see [Registries](/guides/registries) for connecting a source, and [Create a Registry](/guides/create-a-registry) for hosting your own charts on GHCR.

***

## Install Add-ons

Add-ons are installed through [Stacks](/concepts/stacks), next to the [manifests](/concepts/stacks#manifests) they depend on, so they deploy in the right order as one unit.

**1. Navigate to Stacks**

Go to the **Stacks** section in your cluster and click **+ Create** (or edit an existing stack).

**2. Add an Add-on**

In the Stack Builder, click **Add Add-on**. Browse or search for charts from your connected registries.

**3. Configure Values**

Select the chart version and configure the values. Pin an exact chart version in production to avoid unexpected upgrades. You can use the AI Assistant (`⌘+J`) to help customize the configuration.

**4. Deploy**

For a new stack, click **Create Stack** to save and deploy it, installing the add-on on your cluster.

***

## Encrypting Sensitive Values with SOPS

When an add-on's values carry a password, an API key or a webhook URL and the cluster is connected to Git, list those key names under **Encrypted Keys (SOPS)** in the add-on's configuration, for example `adminPassword`. Ankra encrypts their values with SOPS before it writes the values file to Git, keeps the keys readable for diffs, and decrypts them when it deploys. SOPS needs a one-time setup for the organisation - see [SOPS](/guides/sops).

***

## Operational Learnings with AGENTS.md

Every add-on can carry an **AGENTS.md** - a markdown document of operational learnings (upgrade gotchas, safe rollout order, values that must stay pinned) that teammates and Ankra's AI build up over time. Edit it from the **AGENTS.md** tab on the add-on in the Stack Builder; editing it never triggers a redeploy. See [Teach Your Agents with AGENTS.md](/platform/agents-md).

***

## Viewing Installed Add-ons

Once deployed, you can monitor and manage add-ons from the Add-ons page.

### Add-ons List

Navigate to your cluster → **Add-ons** to see all installed add-ons with:

* **Name and Version**: The Helm chart name and deployed version
* **Status**: Current sync and health status
* **Namespace**: Where the add-on is deployed
* **Last Updated**: When the add-on was last modified

### Add-on Details

Click any add-on to view detailed information:

| Tab | Description |
| - | - |
| **Overview** | Chart info, status, metadata, and deployment state |
| **Resource Map** | Visual hierarchy of all Kubernetes resources created by the add-on |
| **Values** | Current Helm values configuration |
| **Events** | Recent events related to the add-on's resources |

### Resource Map

The Resource Map provides a visual representation of all resources deployed by an add-on:

* **Hierarchical View**: See parent-child relationships (e.g., Deployment → ReplicaSet → Pod)
* **Quick Navigation**: Click any resource to view its details
* **Status Indicators**: Identify unhealthy or pending resources at a glance
* **Resource Types**: View all Kubernetes resource kinds in one place

> [!TIP]
>
> Use the Resource Map when troubleshooting to quickly identify which resources are failing and their dependencies.

***

## Updating Add-ons

### Changing Values

1. Navigate to your stack in the Stack Builder
2. Click the add-on you want to modify
3. Update the Helm values as needed
4. Save and deploy the stack

### Upgrading Chart Versions

1. Edit the stack containing the add-on
2. Click the add-on and select a new chart version
3. Review any breaking changes in the chart changelog
4. Save and deploy to upgrade

> [!WARNING]
>
> Major version upgrades may include breaking changes. Review the chart's release notes and test in a non-production environment first.

### Rollback

If an upgrade causes issues:

1. Edit the stack and revert to the previous chart version
2. Or use GitOps: revert the commit in your Git repository
3. Ankra deploys the previous state again - from the stack when you deploy it, or from Git on its next sync

Add-on settings and Helm values are also readable and updatable through Ankra's AI and MCP clients, alongside sync, rollback, and uninstall - so routine add-on operations can run straight from chat or your editor. See the [MCP Tool Reference](/platform/mcp-tools#add-ons).

***

## Explore the Add-ons API

Want to automate add-on management or integrate with your CI/CD workflows?
Check out the [API Reference](/api-reference/introduction) for endpoints to list, install, and manage add-ons programmatically.

***

## Related

> [card] [Stacks](/concepts/stacks)
>
> Build stacks with multiple add-ons.

> [card] [Add-on Catalog](/platform/addon-catalog)
>
> Browse available Helm charts.

> [card] [GitOps](/concepts/gitops)
>
> Understand the GitOps workflow.

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt sensitive add-on values.


# Applications
Source: https://docs.ankra.ai/concepts/applications

Point Ankra at an application's source repository and it generates the Dockerfile, Kubernetes manifests, and CI/CD to build and deploy it.

Applications take you from source code to a deployable workload. Connect an application's Git repository and Ankra analyzes it, generates the packaging it's missing, and opens a pull request in your repository, unless it finds nothing there it can build and keep running. Once merged, CI builds and publishes a container image that you can deploy to a cluster.

> [!NOTE]
>
> Applications connect to **GitHub** repositories and use a [GitHub credential](/integrations/github). By default the generated CI/CD pipeline pushes the container image to your organisation's private Ankra registry; if you already run your own registry, [declare it](#using-your-own-registry) and Ankra publishes to and reads from it instead.

> [!TIP]
>
> **No repository yet?** A [Claude Design](https://claude.ai/design) export can be imported straight into an application: Ankra converts the artboards into a static site, creates the GitHub repository, commits it with a Dockerfile and registers it, and the same setup pull request, build and deploy lane follows. See [From Claude Design to a live application](/guides/claude-design-to-ankra).

***

Watch a repository go from source to a live URL with one command.

[Ship any repo to production on Ankra - one command](https://www.youtube-nocookie.com/embed/F5G_lrsiF64?rel=0)

## How it works

```mermaid theme={null}
flowchart LR
    Repo[Your app repo] -->|connect| Ankra[Ankra]
    Ankra -->|"analyze + generate (PR)"| PR[Pull request]
    PR -->|merge| CICD[CI/CD pipeline]
    CICD -->|push image| Registry[Private Ankra registry]
    Registry -->|deploy| Cluster[Application on cluster]
```

**1. Connect a repository**

Provide a name and a GitHub credential, then pick the repository and a branch from the repository's own branch list - the default branch is preselected, and **Enter a different branch** lets you type one that does not exist yet.

**2. Analyze and generate**

Ankra inspects the repository, detects the language and framework, and generates the artifacts it needs: a Dockerfile, Kubernetes manifests, and a CI/CD workflow.

**3. Merge the pull request**

The pull request runs its own checks first: it builds the image, scans it and runs the security gate. It stays a draft, which GitHub will not merge, until they pass, and then Ankra marks it ready for review; if you run the [AI review](/platform/ai-code-review), it skips the draft until then unless **Review drafts** is on. Review and merge it. Merging activates the CI/CD pipeline in your repository. When they fail, Ankra fixes the pull request itself, and the [PR shepherd](#the-pr-shepherd) keeps it moving until you merge it - or merges it for you, if you opt in. Beside CI that Ankra adopted, with no CI at all, or on a private repository whose GitHub plan has no drafts, it opens ready for review.

**4. Build and publish**

CI builds and pushes the container image to the organisation's private Ankra registry. Ankra surfaces the image URL and scans the published image.

**5. Deploy**

Deploy the application onto a cluster. Ankra verifies that the image was published and tracks the rollout.

> [!NOTE]
>
> **When setup stops before the pull request.** In two cases Ankra opens no setup pull request and deploys nothing. The setup ends as failed, and the application's error message says why:
>
> * **Nothing in the repository keeps running.** When the analysis finds only a program that runs once and exits, or nothing that runs at all, the message starts "Ankra did not set this repository up as an always-on application" and ends "Add a program that keeps running and listens on a port, then run setup again."
> * **Nothing can be built.** When there is no Dockerfile in the repository, on an open setup branch or among the files Ankra generated, the failed `setup_stopped` task says what Ankra found and what it could not write. Add a Dockerfile and run setup again.
>
> Both messages carry the same sentence: "No setup pull request was opened and nothing was deployed." A repository that commits its own manifests under `.ankra/manifests/`, or whose own CI already publishes an image, still gets its setup pull request, with no build for anything that has no Dockerfile. So does a monorepo in which at least one component can be built.

### When your repository already has CI

If your repository already runs CI, Ankra reads it during analysis and works with it instead of adding a pipeline of its own. It reads GitHub Actions workflows, `.gitlab-ci.yml`, `bitbucket-pipelines.yml` and `.circleci/config.yml`, and notes for each one whether it runs tests, builds an image, pushes it (to which registry, tagged how), deploys, what triggers it and which runners it asks for.

| What your CI does | What Ankra does |
| - | - |
| Builds and pushes the image | Adopts it. The application deploys the image your CI pushes, and the setup pull request adds only what deploying needs, such as the manifests. No `.ankra/pipeline.yaml`, workflow or Dockerfile is added. |
| Pushes an image under a name only the run knows, such as a repository name held in a secret | Adopts it, and tells you what it still needs: point the application at that image with `ankra application registry set`, or choose Ankra Pipelines to publish instead. |
| Runs tests but publishes no image | Keeps your CI for the tests and proposes Ankra Pipelines to build and publish the image. |
| Nothing (no CI) | Proposes Ankra Pipelines. |

The analysis says which of these it chose and why, and the setup pull request carries the same reasoning under **Your existing CI**.

When the image your CI pushes lives in a private registry, add a registry credential for it and name it with `ankra application registry set --credential` so the cluster can pull the image.

Ankra also checks whether your CI actually starts. If the newest run of a workflow has waited in the queue for more than 20 minutes, the analysis reports it, names the runner labels the jobs ask for (for example a `depot-` or self-hosted label nothing is serving), and suggests switching `runs-on` to `ubuntu-latest`, connecting a runner for that label, or letting Ankra Pipelines run the build. Ankra never edits your workflow.

To build with Ankra Pipelines anyway, convert the application with `ankra application pipeline convert`. A repository that already commits `.ankra/pipeline.yaml` keeps building with it.

### When the setup pull request does not pass its checks

A repository can already carry problems Ankra did not put there - most often dependencies with known security issues, which the security gate refuses to publish. The setup pull request then fails its own checks, and you do not have to fix it yourself:

* **Ankra AI fixes it on the same pull request.** An agent reads the run, commits a fix to the setup branch (for vulnerable dependencies: newer releases, overrides, a regenerated lockfile) and watches the checks until they pass. It never opens a second pull request and never touches your default branch.
* **The pull request says what is happening.** Ankra's status comment explains in plain words what stopped the run and that Ankra AI is fixing it, and the application's **Go live** page shows the same. Merge once the checks are green.
* **You can turn it off.** Automatic build fixing is on for every application by default. Turn it off for one application, or pause Ankra's autonomous actions, and the pull request only gets the explanation and a **Fix with Ankra** link.

When you create the application from the portal yourself and hold pipeline management access, Ankra also approves the pipeline it generated in your name, so the first runs are not held for an approval. An application added with the CLI, an API token or the AI Assistant leaves that approval to an administrator.

### When a build on your branch fails

A failed build on the application's tracked branch dispatches the same agent. What it may do depends on the repository's **CI/CD** lane on the application's **AI** tab:

| Lane | What happens |
| - | - |
| **Ask** (the default) | The agent investigates and proposes a fix, without committing |
| **Agent** | The agent commits the fix and opens a pull request for you to review |

### When a pull request fails its checks

On Ankra Pipelines, a failed build, image gate or `run` step (your tests, for example) on any pull request from a branch of your repository, not only the setup pull request, is fixed on that pull request:

* **The fix lands on the pull request's own branch.** An agent commits it to the head branch and watches the run that commit starts. It opens no second pull request and changes only what the failure needs. For an image gate the agent is handed each vulnerable package with the releases that fix it, and moves it to at least the highest.
* **A conflict with the base branch is resolved the same way.** The status comment opens "This pull request conflicts with" and names the base. The agent merges the base into the head with a merge commit, resolving every file both sides changed, and the run of that merge commit is its check. Nothing is ever merged into your default branch.
* **When the AI allowance is used up**, on Ankra's own models with no key of your own, the status comment says the fix is queued and starts by itself when the allowance resets on the 1st of the month, or as soon as an organisation owner adds the organisation's own model key under **Organisation settings**, **AI provider**; if billing has paused AI, it names that instead.
* **Without AI, vulnerable Python packages are still upgraded.** When the image gate blocked the run and the fix has to wait, Ankra moves each package a lock file pins to a release that fixes it, checked against the packages' own requirements, commits that to the pull request on GitHub, and leaves the rest for the allowance.
* **The same switches hold it:** automatic build fixing turned off for the application, Ankra's autonomous actions paused, or an environment of the application set to **You run it**.

A pull request from a fork is never committed to: it gets the explanation and a **Fix with Ankra** link on the run page.

### The PR shepherd

Ankra watches the pull requests it opens in your repository - the setup pull request, and any [portability pull request](/use-cases/vercel-to-ankra) a Launch Plan opens - and drives each one to a state you can merge. You see it as an **Ankra PR shepherd** check on the pull request's latest commit. Its summary says where the pull request stands - waiting, ready, needs a person, or merged - and why, and it is updated as things change.

What the shepherd does on its own:

* **Your CI never starts.** When no CI check has started on the pull request after about 20 minutes - no runner picks the job up, or the Ankra agent on your CI cluster cannot run pipeline steps - Ankra starts a full Ankra pipeline run on the pull request's head, builds it on Ankra's builders and runs a proof of the application, so the pull request still gets an answer.
* **The pull request falls behind its base branch.** Ankra merges the base branch into its own branch with a merge commit - never a force-push or a rebase. It waits until the head has sat for about 6 hours, or does it straight away when merging is opted in (below).
* **The pull request conflicts with its base branch.** Ankra resolves the conflict only when every file in the pull request is one Ankra owns: the Dockerfile, `.dockerignore`, the `.ankra/` directory and the generated build workflow. Your own files are kept exactly as the base branch has them, and a conflict that touches them is left for you.
* **A check fails.** When the pull request only changes Ankra's own files, Ankra AI fixes it on the same branch, up to 3 times, then reports it for a person. A failure in a pull request that changes your files is reported, never "fixed".
* **The proof of the head never gives an answer.** Where your organisation has a staging cluster, a proof still queued 20 minutes after Ankra queued it, or one that ended not proven, is a dead end: once nothing else is pending, the check reads **Needs a person**, names the proof and its reason, and Ankra does not merge. The shepherd keeps looking every 15 minutes, so a proof that passes later turns it **Ready to merge**.

These are the shepherd's own actions. On Ankra Pipelines, a pull request from a branch of your repository is also fixed as [When a pull request fails its checks](#when-a-pull-request-fails-its-checks) describes, whichever files it changes.

#### Merging

Ankra merges a pull request only when all of these hold:

* merging is opted in for the application (below);
* every check on the head has finished green, and the proof of the application passed;
* GitHub reports the pull request mergeable. Branch protection is always honoured, never worked around.

Otherwise the check reports the pull request as ready for a person to merge. Ankra never merges a pull request whose own CI never ran - Ankra's pipeline run and proof make it ready for you, not merged - and it never merges a portability pull request, because that changes your code.

After a merge, the application deploys as usual. When your CI could not build the pull request, Ankra builds the merge commit on its own builders so the deploy has an image.

#### Opting in to merging

Merging is off by default. Two settings decide it:

* **The organisation's setting**, `auto_merge_setup_pull_requests` on `PUT /org/applications/settings` (or `ankra_application_settings` in [Terraform](/integrations/terraform)). Only organisation admins can change it.
* **The application's own setting**, which overrides the organisation's: on for this application, off for this application, or follow the organisation (the default). Read it with `GET /org/applications/{application_id}/auto-merge-setup-pull-requests` and change it with `PUT` and a body of `{"enabled": true}`, `{"enabled": false}`, or `{"enabled": null}` to follow the organisation again. Only organisation admins can change it. The answer carries the application's own value, the organisation's, and the `effective` one Ankra acts on.

An application set to on is merged even when the organisation's setting is off, and one set to off never is. If a setting cannot be read, Ankra does not merge.

***

## Building on Ankra's builders

The flow above puts the first image behind a merged pull request: until the generated workflow is on your default branch, your CI has nothing to run, and nothing to publish. Ankra can also build the image itself, on its own builders, with no workflow in the repository at all.

Ankra clones the commit, resolves a recipe for it, builds it, and pushes the image to the same registry the application publishes to. The recipe is the first of these that fits:

1. **The repository's own `Dockerfile`** — used as-is.
2. **A generated Dockerfile** — the one Ankra wrote for this application.
3. **Buildpacks** — when there is no Dockerfile to use.

No Actions minutes are spent, no runners need operating, and no registry credentials go anywhere near the repository.

```bash theme={null}
# Queue a build and follow it to a result
ankra application build start <application-id> --commit <full-sha> --ref main --wait

# Read what the builders did
ankra application build list <application-id>
ankra application build get <application-id> <build-id>
```

Reach for this when the repository's own CI cannot do the job — a private repository on a plan whose Actions never leave the queue, a first image needed before anyone merges the setup PR, or an unattended caller with no browser to click through.

> [!NOTE]
>
> `--commit` takes a **full** 40- or 64-character commit sha. The queue deduplicates on the string it is given, so an abbreviation would be a second key for the same commit and would build it twice. Asking twice for one commit joins a single build rather than racing two, and the answer's `already_requested` says when that happened.

### Following a build

A request is not yet a build. `start` answers with a **request id** immediately; the build itself is created when a builder claims the request. So there are two things to read:

```bash theme={null}
# The queued ask - pending until claimed, then it names its build
ankra application build request <application-id> <request-id>

# The build itself
ankra application build get <application-id> <build-id>
```

`ankra application build start --wait` walks both steps for you and exits non-zero if the build failed, which makes it usable as a pipeline gate. Watching the build list instead is a trap: a previous failed build of the same commit is still the newest one for that commit, so it would report an old failure as your build's result.

### Waiting for a builder

Ankra's builders are one pool that every organisation shares. Your organisation runs at most three builds on it at a time, so a burst of builds from one organisation - onboarding a repository with many components, say - cannot hold every builder while others wait. Requests beyond three stay `pending`, in the order they were made, and the next one starts as soon as one of your running builds finishes. A pending request is waiting its turn, not failing: it keeps its request id, and `--wait` keeps following it.

### What a failure means

A failed build carries an `error_class` that says whose failure it was:

| `error_class` | Whose | What to do |
| - | - | - |
| `build_failed` | Yours | The recipe did not build. Read `error_message`. |
| `clone_auth` | Yours | Ankra could not clone the repository — check the application's Git credential. |
| `recipe_missing` | Yours | No Dockerfile and no buildpack matched the repository. |
| `push_failed` | Ankra's | The image built but could not be pushed. |
| `timeout` | Ankra's | The build exceeded its budget. |
| `capacity` | Ankra's | No builder was running to take the build. |

The last three are platform-side and are already visible to Ankra without anyone reporting them.

> [!NOTE]
>
> This replaces the **image build**, not the whole generated pipeline. That workflow also runs a Semgrep scan, and packages a Helm chart for applications that publish one. If you plan to retire the workflow entirely, decide where those two go first.

***

## The application workspace

An application opens as a workspace: a context sidebar beside the main one, in the order the work happens, with one page per section at `/organisation/applications/<application-id>/<section>`. A link to an older `?tab=` address redirects to its section.

| Section | What it shows |
| - | - |
| **Overview** | Where the application is right now: the setup journey, the environments it is live in, and the latest run. **Add** beside the environments puts the application on another cluster; see [Add an environment on another cluster](/guides/application-environments#add-an-environment-on-another-cluster). |
| **Pipelines** | Run history as one lane per run, with skipped and cancelled runs grouped on their own. Stages fold into phases decided by each stage's kind, so a long pipeline reads as a handful of things you can name; a kind the grouping does not know yet sits under *Other steps*. A run opens as its own sheet - logs, the failed step and its exit code, the artifact and the commit - with the suggested fix separate from the rerun. |
| **Deployments** | One installation per row: the cluster and its environment label, the owning add-on or stack, the version it serves, health and the reported address. A version that differs between installations is shown as a difference, not called drift. A field the read does not carry reads *unknown*, never zero, and the installation sheet links to the owning add-on for namespace, pods, events and logs rather than pretending to show them. |
| **Previews** | What the CLI and API call demos. One card per preview with its branch or commit, component, image, expiry, access (browser URL, in-cluster only, URL not live, or not reachable yet) and the staging cluster, plus the launch dialog and the environment template. See [Preview demos](#preview-demos). |
| **Security** | Eight views over the application's scan reports, ranked by exploitability. See [Security scanning](#security-scanning). |
| **Environment** | The secret keys the application reads, each with three independent states: stored (*Set*, *No value*, *Value missing*), consumed (*Manifests* or *Not referenced*) and its deployment state. Only a stored key the manifests reference inherits the application-wide apply answer; a key nothing references reads *Stored only*, a key with no value *Nothing to apply*, a lost value *Cannot apply*. Values are never displayed - the API has no route that returns one. Ordinary, non-secret variables are not available for applications yet. |
| **Source & config** | The files Ankra wrote: the file tree, the editor, pending changes per file and in total, and the commit message with **Push to PR**. The editor says whether it is showing the setup branch or the generated set, and why the branch is not showing when it is not. |
| **Settings** | The repository, branch and component paths setup ran against (read-only), delivery per environment, the [image registry](#using-your-own-registry), publishing the application as an add-on, running setup again, and delete last. |

The sidebar carries two badges: **Security** shows the CISA-listed finding count once the KEV catalog has synced, and never before; **Environment** shows the declared keys still without a value.

The Applications list has two ways in: **All applications**, or **Needs attention** - a failed setup, an unmerged setup pull request, a failed deploy or a degraded one. Setup in progress, deploying, parked, resting, and a runtime Ankra could not read are not attention.

## What Ankra tracks

For each application you see:

* **State** and **analysis status** - where the application is in the connect/analyze/generate/build lifecycle, with an error message if something needs attention.
* **Repository** - owner, name, branch, and URL.
* **Components** - the repository's deployable apps. An ordinary repository has one; a monorepo has one per app.
* **Artifacts** - the private container image URL and the latest published build, per component.
* **Pull request** - a link to the generated PR.
* **Jobs** - the underlying platform jobs for the application, so you can follow analysis and generation as it runs.

### Monorepos

A repository that builds more than one deployable app is onboarded as a **monorepo**: Ankra records one component per app, and each component gets its own packaging and its own image.

| Per component | Where it lives |
| - | - |
| Dockerfile | `<component-directory>/Dockerfile` |
| Kubernetes manifests | `.ankra/manifests/<component>-*.yaml` |
| Build workflow | `.github/workflows/<component>-build-and-publish.yml`, with a `paths:` filter scoped to the component's directory so touching one app does not rebuild the others |
| Container image | `<your-registry-project>/<repository>/<component>` |

Ankra decides the components from, in order: the `components` block of the repository's [`.ankra/ankra.yaml`](/reference/application-descriptor#components), when it declares one; the per-component workflows the repository already carries (so re-running analysis never renames a component and orphans the images it has published), the apps the analysis proposed, then the repository's structure - two or more Dockerfiles in subdirectories and no Dockerfile at the root, or a workspace marker (`nx.json`, `turbo.json`, `lerna.json`, `pnpm-workspace.yaml`, `go.work`) plus two or more subdirectories with their own dependency manifest. **Without a declaration, a Dockerfile at the repository root always means a single app**, whatever else the repository contains.

The AI proposal and structural detection can add components to a monorepo but never leave it with fewer than it records: a run whose inference finds fewer keeps the recorded ones. Only a declaration, or two or more of Ankra's per-component build workflows for fewer components than the record, can shrink it, and a run that drops or renames a recorded component records the new set and reports the change as the failed task `record_components`. A repository whose layout inference misreads, such as an API built from `deploy/docker/Dockerfile` at the root beside a web app in `web/`, declares its components in [`.ankra/ankra.yaml`](/reference/application-descriptor#components), and the declaration is also how you remove one.

Build state, published images, deploys, demos, and container scanning are all reported per component, so an application whose API component built and whose frontend did not says exactly that.

### Using your own registry

An application publishes to your organisation's private Ankra registry unless you say otherwise. If you already operate a registry - the same Harbor whose OCI charts Ankra indexes, for instance - declare it on the application and Ankra publishes there, reads the published tags back from there, and pulls from there.

Declare it on an existing application from **Settings** → **Image registry**, from the CLI, or with `image_registry` when you create the application. The settings panel also reports the host and project the declaration resolved to and the image repository each component is expected to publish to, so you can compare them against where your builds actually push.

```bash theme={null}
# Show the effective registry and the expected repositories
ankra application registry get <application-id>

# Declare a registry you operate
ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce-images \
  --credential example-harbor-pull

# Go back to your organisation's own Ankra registry
ankra application registry clear <application-id>
```

The same declaration at create time:

```json theme={null}
{
  "name": "commerce",
  "app_repo_credential_name": "github",
  "app_repo_owner": "smartoptics-dwdm",
  "app_repo_name": "commerce",
  "image_registry": {
    "url": "oci://artifact.example.com/commerce-images",
    "credential_name": "example-harbor-pull",
    "pull_secret_name": "harbor-registry",
    "username_secret_name": "HARBOR_USERNAME",
    "password_secret_name": "HARBOR_PASSWORD"
  }
}
```

| Field | Meaning |
| - | - |
| `url` | The registry project images publish to, as `oci://<host>/<project>`. A deeper path becomes a prefix every component's repository nests under. |
| `credential_name` | An existing [registry credential](/integrations/helm-registries) of the organisation - the same credential resource your chart registries authenticate with. Ankra reads published tags and builds the cluster pull secret from it. |
| `api_url` | Optional. The registry's management API base; defaults to `https://<host>`, which is where a Harbor serves its own API. |
| `pull_secret_name` | Optional. The `kubernetes.io/dockerconfigjson` Secret the generated manifests reference through `imagePullSecrets`. Defaults to `ankra-registry-pull`. |
| `username_secret_name` / `password_secret_name` | Optional. The repository Actions secrets the build workflow logs in with. Default to `ANKRA_REGISTRY_USERNAME` / `ANKRA_REGISTRY_PASSWORD`. |
| `admin_credential_name` | Optional. A registry credential with project administrator rights on the project (or a robot granted the robot-account permissions). Setting it hands robot management on your registry to Ankra: it mints and revokes a push robot for the application with it, and rotates it when the credential is a Harbor user. See [Robot accounts](#robot-accounts). |
| `manage_actions_secrets` | Optional, default `false`. See below. |
| `component_repositories` | Optional. The repository inside the project for a component, keyed by component name - `{"backend": "commerce-backend"}` publishes the backend at `<project>/commerce-backend` - for a registry whose layout follows neither Ankra's nesting nor the flat component name. Unnamed components keep the derived path. CLI: `--component-repository backend=commerce-backend` (repeatable); portal: one field per component under **Settings** → **Image registry**. |
| `flat_repositories` | Optional, default `false`. Publish a monorepo's components straight under the project - `<project>/<component>` - instead of Ankra's `<project>/<app>/<component>`. Turn it on when the registry already holds the images that way, so publish readiness, the deploy gate and the generated workflows all address the repositories your pipeline already pushes to. Single-component applications are unaffected. |

**Ankra does not mint robots for a registry you operate unless you hand it the keys.** With a declared registry and no `admin_credential_name`, setup names the two Actions secrets the workflow reads and leaves them to you, rather than writing a credential Ankra happens to hold over a push robot you administer. Publish readiness reports whether those secrets exist and names them. Name an `admin_credential_name` to have Ankra mint a push robot for the application there ([Robot accounts](#robot-accounts)), or set `manage_actions_secrets: true` to have it write the declared credential into them instead.

> [!WARNING]
>
> `credential_name` is what makes a declaration usable rather than merely descriptive. Without one Ankra records where the images live but cannot read their tags or pull them, so publish readiness, the demo build check and the deploy gate all keep reporting the application as never built - while it publishes healthily to a registry Ankra simply cannot see.

> [!NOTE]
>
> An application is bound to the GitHub credential it was created with; its App installation must reach the repository for builds, deploys and Actions secrets. Move an application onto another credential of the organisation with `ankra application credential set <application-id> --credential <name>` (`GET`/`PUT /api/v1/org/applications/{application_id}/repository-credential`); the answer reports whether the new binding resolves to an installation.

> [!NOTE]
>
> On a monorepo, a component may declare its own `image_registry` to publish into a different project of the same registry - useful when each app has its own robot accounts and retention rules. A component's declaration wins over the application's; the application's applies to every component that declares none.

Publish readiness, the deploy gate, image tag listings, container scanning, and preview demos all resolve the declared registry, so an application whose images live outside Ankra reports what is actually published rather than staying blocked on an artifact that was never going to appear in Ankra's own project.

Running Harbor yourself? [Harbor as your application registry](/guides/harbor-registry) covers the operator's side: which credential does what, which Harbor releases let a robot administer robots and when the credential must be a Harbor user, how to check the minted robot from Harbor's own API, and how the pull secret reaches every cluster and namespace the application deploys to.

### Robot accounts

Every application gets a registry robot account of its own: a push+pull robot named `robot$<project>+app-<application-id>` on the project it publishes to, stored as the platform-managed registry credential `ankra-harbor-app-<application-id>` and written into the repository's Actions secrets as the login the build workflow uses. Nothing else shares that login, so a leaked repository secret is rotated or revoked for that one application, and a deleted application takes its robot with it.

* **On your organisation's Ankra registry** the robot is minted automatically when the application is set up, and again whenever the application is reconciled. Applications onboarded before robots existed get one the first time **Fix automatically** runs in the **Pipelines** section, or when you create it from **Settings** → **Image registry**.
* **On a registry you operate**, Ankra mints one only with a credential that may: set `admin_credential_name` to a registry credential with project administrator rights on the declared project (in Harbor, a project admin user, or a robot granted the robot-account permissions). Without it Ankra never touches your robots; publish readiness names the field.

The robot is shown - name, registry, when it was created and last rotated - under **Settings** → **Image registry**, where you can create, rotate or revoke it. Rotating refreshes the secret and rewrites the repository's Actions secrets; the previous secret stops working the moment the registry answers. Revoking deletes the robot from the registry and drops its credential, leaving the repository's secrets holding a login that no longer works.

```bash theme={null}
# Show the application's robot
ankra application registry robot get <application-id>

# Mint one (or confirm the existing one) and write its login into the repository
ankra application registry robot ensure <application-id>

# Rotate its secret after a leak
ankra application registry robot rotate <application-id>

# Revoke it
ankra application registry robot revoke <application-id> --yes

# Let Ankra manage robots on a registry you operate
ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce-images \
  --credential example-harbor-pull \
  --admin-credential example-harbor-admin
```

The same is available on the API at `/api/v1/org/applications/{application_id}/registry-robot` (`GET`, `POST` with `{"rotate": true|false}`, `DELETE`). The robot's credential appears in your organisation's registry credentials as managed by Ankra; it cannot be edited or deleted there, only through the application.

### Security scanning

Applications include code and container security insights, so vulnerabilities surface alongside the build rather than in a separate tool. The **Security** section reads the way the [Security Center](/guides/cluster-security) reads a fleet finding - risk first, ranked by exploitability - in eight views:

| View | What it shows |
| - | - |
| **Overview** | Risk score, vulnerabilities, known exploited, last scan and scanners reporting, then *First to review*: the CISA-listed finding when the catalog is synced, the highest-severity one otherwise. An unscanned image reads **Not assessed** on every tile, never `0 / 10`; a pipeline configured but not yet built reads **Waiting**; a report older than two hours is marked stale. |
| **CVEs & findings** | Every finding, ranked by [exploitability](/guides/cluster-security#exploitation-intelligence-cisa-kev-and-epss): CISA KEV listing first, then EPSS, then severity, then CVSS, with highest severity as the alternative order. A **Known exploited** filter narrows to CISA-listed findings, and a banner leads the table when any finding is listed. |
| **KEV** | One card per CISA-listed finding: date added, due date (overdue marked), ransomware use, EPSS, the fix, CISA's required action, and where it runs. |
| **SBOM** | The package inventory of the selected image version - package and PURL, version, type, licence and tier, the CVEs on that version and the workloads it runs in - and the versions list with one row per pushed tag, its bill of materials, its findings and the CycloneDX and CSV downloads. Only versions with a bill of materials are selectable; nothing borrows another image's inventory. |
| **Compliance** | Not available for applications yet; points at the organisation Security Center. |
| **Coverage** | Which scanner reported - Trivy, Semgrep, Checkov, bill of materials - and how fresh: fresh, stale after two hours, pending (configured, no build since), not configured, or unknown when the read failed. |
| **Code** and **Infrastructure** | The Semgrep and Checkov findings; a row opens with the file, lines, rule, category and the rule reference. Waiting for a first scan and zero findings are distinct states. |

Every finding row opens a sheet with severity, CVSS, EPSS (as `EPSS 94% · top 1%`), the CISA KEV entry - date added, due date, ransomware use and required action - the fix, and a link to the platform's own [advisory page](/guides/cluster-security#advisory-pages) for the CVE. Exploitability reads **Unknown** until the KEV catalog has synced; absent is never read as not exploited.

On a monorepo, the image tags and the scanned image reference follow the component you select; code and IaC findings cover the whole repository, because that is where those scanners run. Pair this with [AI Insights](/platform/ai-insights) for proactive analysis.

***

## Preview demos

Before you merge, you can spin up a **throwaway demo** of a pull request or branch build to see it running. In the portal these live in the application's **Previews** section, which calls each one a preview; the CLI and API keep the `demo` name. Each demo is deployed into its own isolated namespace (`ankra-demo-pr-<n>` or `ankra-demo-br-<branch>`) on the organisation's **staging cluster**, PodSecurity-hardened and quota-bounded, and is automatically torn down when its TTL expires - so it can never affect existing workloads.

**1. Configure a staging cluster**

An admin sets the organisation's staging cluster under **AI** → **Settings** → **Workspaces**. Optionally set a **demo base domain** (with an ingress class and TLS secret) there too - this is what gives demos a public URL.

**2. Deploy a demo**

Deploy a branch or PR demo from the application's **Previews** section, from the CLI, or by asking the AI assistant. The demo pulls the image tag the PR/branch build pushed.

**3. Open the preview**

When a public host is available, Ankra returns a **preview URL** you can open directly. Otherwise the demo stays reachable in-cluster (service DNS + a `kubectl port-forward` command).

Two guides cover the two ways a demo starts: [branch demos](/guides/branch-demos) walks the launch dialog field by field, and [PR preview environments](/guides/pr-preview-environments) covers the automatic per-pull-request flow.

### The preview URL

Ankra resolves the demo's public hostname automatically, and every surface (portal, CLI, MCP, and automatic PR previews) uses the same rule:

1. **An organisation demo base domain**, if configured, wins outright - the host is `<namespace>.<demo-base-domain>`, served with your configured ingress class and TLS secret.
2. **Otherwise, the staging cluster's own delegated DNS zone**, but only when that zone is active - giving `<namespace>.<cluster-id>.<org-id>.<ankra-domain>`, a hostname the `external-dns` running on that cluster can resolve. When the cluster also carries the Ankra networking stack, the demo's ingress requests a Let's Encrypt certificate from its `letsencrypt-prod` issuer automatically, so the preview URL is served over **https**.
3. **Otherwise the demo stays in-cluster-only** - no ingress is created, and you reach it with the returned service DNS name and `kubectl port-forward`.

> [!NOTE]
>
> A demo only gets a resolvable public URL when the organisation has a demo base domain configured **or** the staging cluster has an active Ankra DNS zone. Without either, the demo still deploys - it just stays in-cluster-only.

The Ankra domain in rule 2 is `ankra.cc` by default. An organisation can register **its own custom domain** - dedicated to that organisation alone - in the **Custom Ankra domain** field under **AI** → **Settings** → **Workspaces**, or from the CLI with `ankra org domain set <domain>`. The domain must be a bare domain the organisation owns, its NS records must already point at Ankra's nameservers (the ones serving `ankra.cc`), and no other organisation may hold it.

With a custom domain registered, the `external-dns` Ankra runs on each of the organisation's clusters is scoped to the **whole domain**, not just that cluster's delegated `<cluster-id>.<org-id>.<domain>` zone. An Ingress on any hostname under the domain - a top-level name like `app.example.com` included - is published automatically by the cluster serving it. On the shared `ankra.cc` root the scope stays the cluster's own delegated zone: names directly under `ankra.cc` are allocated by the platform, and one organisation's cluster must never be able to write another's.

Zones already provisioned keep the domain they were minted under, so the switch is refused while any cluster DNS zone or [DNS record](/platform/organisation-settings#dns-records) still lives under the old domain. The refusal names exactly what is blocking it - the portal lists the cluster domains and records beside the field, and `ankra org domain set` prints the same list - so the migration is a checklist rather than a guess:

**1. Inventory what is under the current root**

`ankra org dns zones` lists every cluster domain in the organisation with its state; `ankra org dns list` lists the DNS records. Both are reads. In the portal the same two lists live under **Organisation** → **Settings** → **DNS records**.

**2. Destroy any playground environment**

A playground publishes a wildcard DNS record in the organisation's zone, and that record is **reconciled** - the platform writes it again on its next pass over a ready environment, so deleting it in the next step will not clear it. Destroy the environment instead: `ankra cluster playground destroy <cluster_id>`. The refusal names any playground that is still holding a record.

**3. Remove each cluster domain**

`ankra cluster domain <cluster> --remove` (or `DELETE /api/v1/clusters/{cluster_id}/dns-zone`, or **Remove** on the cluster domain row in the portal) hands the zone to Ankra for teardown.

The removal is **held**: nothing re-creates the zone until you ask for it back in the last step - not the `external-dns` Ankra runs on that cluster, and not the discovery that mints zones for clusters that have none. `ankra cluster domain <cluster>` reports `Opted out: yes` for as long as the hold stands, so a domain that is gone is distinguishable from one that is between reconciler passes.

**4. Delete the DNS records**

`ankra org dns delete <record>`, or delete them from the DNS records table. These are the records you created; anything the platform publishes is listed separately in the refusal, with what to remove instead.

**5. Register the new domain**

`ankra org domain set example.com`, or save the **Custom Ankra domain** field. Ankra tears the organisation zone down and re-creates it under the new domain automatically.

**6. Re-enable the cluster domains**

`ankra cluster domain <cluster> --enable` withdraws the hold and re-creates each cluster's zone under the new root, and the cluster's external-dns picks up the new zone on its next cloud-provider stack pass. Every cluster you removed in step 3 needs this, the staging cluster included.

> [!NOTE]
>
> `ankra cluster domain <cluster>` on its own is a **read**: it reports the cluster's domain, or state `none` when it has none, and never creates a zone. Creating one is the explicit `--enable`. (Before CLI v0.13.0 the bare command created a zone, which meant checking a cluster's domain could add a blocker to this very migration.)

### What a root-domain switch does and does not touch

Two questions decide whether the switch is safe to attempt on a domain that is already in use. Both have short answers.

**Ankra touches only the records it creates in the domain you register.** Registering `example.com` adopts it as the organisation's zone apex, with each cluster's own `<cluster-id>.example.com` subzone under it, and the `external-dns` Ankra installs on every cluster is scoped to the whole domain so it can publish top-level names like `app.example.com`. Each controller runs with its own record ownership (`--txt-owner-id`), so it creates, updates and deletes only the records that exist because of an Ingress on its cluster: records you already publish at the apex or under any other name in `example.com` are never read, written or deleted - not by the switch, and not by anything Ankra runs afterwards.

**A switch never re-labels a zone.** Zone labels are derived from the organisation and cluster ids, so they are the same under any root: a cluster that was `axmndle4sl.<org>.ankra.cc` becomes `axmndle4sl.<org>.example.com`. The label is also what Ankra passes as `external-dns`'s `--txt-owner-id`, and what any GitOps path built from a cluster domain embeds - so the TXT ownership registry stays matched to its records across the switch, and the paths do not move. `--enable` re-creating a zone preserves the label for the same reason.

> [!WARNING]
>
> `external-dns` on each cluster runs with `--policy=sync` against its own subzone. That is safe here precisely because the label and the owner id survive the switch together: an owner id that changed under a `--policy=sync` controller would be the configuration that deletes records the controller no longer recognises as its own. Ankra does not change it, and nothing in the switch asks you to.

### Serving a zone in your own DNS account from every cluster

A custom Ankra domain has to be hosted in Ankra's own DNS account, because Ankra mints the per-cluster credentials for it. A zone you keep in **your own** DNS provider account is different: Ankra cannot mint anything there, so the `external-dns` it installs drops Ingress hostnames on that zone silently (the sync logs `All records are already up to date`, because from its point of view there is nothing in scope), and cert-manager's HTTP-01 challenge for such a hostname waits forever for a name that never resolves.

Declare the zone with a credential of your own instead, once, for the whole organisation:

```bash theme={null}
ankra org dns credentials create --name my-dns \
  --webhook-provider-url https://dns.example/api/external-dns/<token>   # stored in the platform's secret store; never echoed back
ankra org custom-dns-zones add --zone example.dev --credential my-dns
ankra org custom-dns-zones list
```

Every cluster in the organisation - the ones running now and every one created afterwards - then gets its own `external-dns` for `example.dev`, rendered and reconciled by Ankra in a dedicated `custom-dns` stack, within about two minutes of the declaration or of the cluster coming up. An Ingress on `chat.example.dev` publishes from whichever cluster serves it, and the certificate follows once the name resolves. Each cluster's controller is pinned to exactly that zone (`--domain-filter`) with its own record ownership, so it can never fight the controller Ankra runs for the cluster's Ankra domain, another cluster's controller, or records you publish in the zone yourself.

* The credential is the external-dns **webhook provider URL** including its token, for any provider that speaks the external-dns webhook protocol. It is written to the platform's secret store on create and no read surface returns it; re-creating it under the same name re-points every cluster at once, which is how a rotated token rolls out. Its name is what `list` shows.
* `ankra cluster custom-dns-zones add <cluster> --zone <zone> --credential <name>` declares the same thing for **one** cluster. A cluster's own declaration of a zone takes precedence over the organisation's on that cluster - the way to serve a zone with a different credential on one cluster - and `ankra cluster custom-dns-zones list <cluster>` shows where each zone a cluster serves was declared (`SOURCE` = `cluster` or `organisation`).
* A zone that overlaps the domain Ankra already serves for the organisation (its `<org-id>.<ankra-domain>` zone, or the whole custom Ankra domain when one is registered) is refused: Ankra's own controllers publish there already and cannot be told to stay off those names. A zone **above** the Ankra domain is accepted, and each cluster's controller is told to leave the Ankra-served part alone.
* A domain in Avura needs no credential of your own: once the Avura workspace is connected to the organisation and the domain is shared with Ankra, declare it with `--credential avura`. See [use Avura domains with Ankra](/guides/avura-domains).
* `ankra org custom-dns-zones remove --zone example.dev` withdraws the declaration. Ankra tears down the controllers it rendered on every cluster that inherited the zone; clusters that declared it themselves keep theirs, and the zone's records are yours and are left untouched.

The same declarations are available on the API: `GET`/`POST` `/api/v1/org/custom-dns-zones`, `DELETE /api/v1/org/custom-dns-zones/{zone}`, and the per-cluster `/api/v1/clusters/{cluster_id}/custom-dns-zones` twins.

### Deploying a demo

A demo deploys **every component** of the application by default. A single-app application runs its one image; a monorepo runs one pod per component — the frontend and the API of a two-app repository both come up, wired together, instead of half an application answering where the other half belonged. You can still deselect components or demo a single one.

> [tab] Portal
>
> Open the application's **Previews** section, choose **Launch preview**, pick a branch or enter a pull request number, and deploy. The dialog groups what to preview, its lifetime and environment, and the staging cluster, and lists the branch, image, lifetime, template, resources, cleanup and access in a summary before the launch button; a missing image or an offline staging agent is an explicit blocker. The section shows one card per active preview with its branch or commit, component, image, expiry, access and cluster. Each preview links to its own detail page - live provisioning progress read from the staging cluster, the namespace's bill of materials with manifests (grouped per component), Kubernetes events, and pod logs, plus the preview URL or port-forward command to reach it. On a monorepo the launch dialog lists every component with its own build status and tag, lets you include or exclude each, and marks the **web entry** — the component that owns the demo URL.

> [tab] CLI
>
> ```bash theme={null}
> # Deploy a branch demo
> ankra application demo deploy <application-id> --branch feature/login
>
> # Deploy a PR demo with an explicit TTL
> ankra application demo deploy <application-id> --pr-number 42 --ttl-hours 8
>
> # List active demos, then stop one
> ankra application demo list <application-id>
> ankra application demo stop <application-id> <workspace-id>
>
> # Inspect a demo: record + provisioning steps, and a bounded log tail
> ankra application demo detail <application-id> <workspace-id>
> ankra application demo logs <application-id> <workspace-id> --tail 200
>
> # Read or edit the saved demo defaults
> ankra application demo config get <application-id>
> ankra application demo config set <application-id> \
>   --database=true --env 'DATABASE_URL=${{ ankra.demo_database.url }}' \
>   --migrate-command 'pnpm run db:migrate' --database-extension vector
>
> # Dispatch the AI pre-setup mission for a failed demo
> ankra application demo fix <application-id> <workspace-id>
> ```
>
> The deploy response includes `preview_url` when a public host was resolved. `config set` fetches the saved configuration first and applies only the flags you pass, so it never drops entries or dependency designations you did not name.

> [tab] AI / MCP
>
> Ask the AI assistant to demo a pull request, or call the `deploy_pr_demo` tool directly (it is allowed in **Ask** mode - the demo is isolated and self-expiring). The result carries the same `preview_url`, names the `entry_component`, and lists every deployed workload under `components[]` with its image, container port and ingress path - so a multi-component launch reports what it actually provisioned rather than only the component that owns the URL. Pass `entry_component` to choose which component serves `/`. Tear down early with `demo_stop`.

Opening a pull request on a connected application also deploys a preview automatically and posts the URL back as a PR status comment that updates in place - see the [PR preview environments guide](/guides/pr-preview-environments) for the comment lifecycle, requirements, and troubleshooting.

### Monorepo demos: every component, one URL

A monorepo demo deploys each component as its own Deployment and Service inside the demo namespace, and the demo only reports **ready** once every component accepts connections:

* **The web entry owns the demo URL.** Ankra picks the frontend-shaped component (a name or directory like `frontend`, `web`, `ui`, `portal`) as the entry serving `/` on the demo host; you can move the entry in the launch dialog or with `entry_component` on the API.
* **API components share the host under a path.** The single API-shaped component (`api`, `backend`, `server`) is published under `/api` on the same demo host, routed straight to its Service — so a browser calling `/api/...` reaches the API even when the frontend's own proxy target was baked for another environment. Override per component with `ingress_path`.
* **Save the routing when the guess is wrong.** The entry and the `/api` path above are heuristics, and the lanes with no human in the loop — the automatic PR previews and the MCP demo tools — have no launch dialog to correct them in. Declare the routing once in the demo configuration and every lane follows it:

  ```json theme={null}
  {
    "routing": {
      "entry_component": "commerce-frontend",
      "components": [{ "name": "commerce-backend", "ingress_path": "/api/v1" }]
    }
  }
  ```

  A declaration is authoritative: the `/api` guess stops running, so a component you leave out of `components` stays reachable in-cluster only rather than picking up a path it never asked for. Per-launch `ingress_path` overrides still win over the declaration. Clear it with `"routing": null` to return every lane to the heuristics.
* **Components reach each other by name.** Every component's Service is named after it, so in-namespace URLs like `http://crm-api:8090` resolve. Env values can also use placeholders that resolve at deploy time:

| Placeholder | Resolves to |
| - | - |
| `${{ ankra.demo_component.<name>.url }}` | `http://<component>:<port>` inside the namespace |
| `${{ ankra.demo_component.<name>.host }}` | The component's Service name |
| `${{ ankra.demo_component.<name>.port }}` | The component's container port |

The saved [migration command](#environment-variables-and-a-throwaway-database) runs once per deploy, inside the image of the component that owns the schema (the primary component - usually the backend). Demo environment defaults and the throwaway database are shared by every component of the demo.

> [!NOTE]
>
> Existing demos and single-app applications are unaffected: a demo recorded before multi-component support (or of an application with one component) keeps exactly the previous single-pod shape.

### Environment variables and a throwaway database

Most real applications need configuration to boot — a database name, an API key, an SMTP host. Demos support both **per-application defaults** and **per-launch overrides**, so any codebase can run as a demo without changes:

* **Defaults** are the application's **environment template**, under **Previews** (*Preview settings*), which separates the disposable dependencies each preview gets from the shared services it points at and labels every generated value with the dependency it comes from. Every demo of the application inherits them — manual launches, CLI/MCP deploys, and the automatic PR previews.
* **Overrides** are set per launch in the *Environment & database* section of the launch dialog (or via the `env` argument of `deploy_pr_demo`). Overrides win by name.

Values marked **secret** are stored as Ankra secret slots, held in the platform secret store — the plaintext never persists and is mounted into the demo as a Kubernetes Secret at deploy time.

**Need a database?** Toggle **Attach a throwaway Postgres** and an ephemeral Postgres is provisioned inside the demo namespace with a random per-demo password, destroyed together with the demo. Because every codebase names its configuration differently, nothing is injected automatically — reference these placeholders in your env *values* and they resolve when the demo starts:

| Placeholder | Resolves to |
| - | - |
| `${{ ankra.demo_database.url }}` | Full `postgres://` connection string |
| `${{ ankra.demo_database.host }}` | In-namespace service host |
| `${{ ankra.demo_database.port }}` | `5432` |
| `${{ ankra.demo_database.name }}` | Database name |
| `${{ ankra.demo_database.user }}` | Database user |
| `${{ ankra.demo_database.password }}` | The per-demo random password |

> [!NOTE]
>
> The throwaway database is ephemeral by design: it starts empty on every deploy and is wiped with the namespace. The database runs a pgvector-capable Postgres, so migrations using `CREATE EXTENSION vector` work. `.url` and `.password` references are always delivered through a Kubernetes Secret, never as plain env text.

**Migrations.** If your image does not run its own migrations on boot, set a **migration command** in the demo configuration (`migrate_command`) — for example `pnpm run db:migrate` or `alembic upgrade head`. It runs inside your application image (`sh -c`) as an init container, after the database accepts connections and with the same environment the app sees, so a fresh demo database provisions its schema before the first request. Because every deploy starts the database empty, the command re-runs on every deploy — write migrations to be idempotent (every standard migration tool is).

> [!NOTE]
>
> The command runs with your image's `WORKDIR` as the working directory **and** on `PYTHONPATH`. Python puts the *script's* directory on `sys.path`, not the working directory, so a migration entrypoint that is a script rather than a console script — `python scripts/bootstrap_database.py` — could not import the application package sitting beside it and died at import with `ModuleNotFoundError`. Setting `PYTHONPATH` yourself in the command still wins.

**Extensions.** If your schema needs Postgres extensions beyond what migrations create themselves, list them in `database_extensions` (for example `["vector"]`) and the demo database creates them at initdb, before your migrations run.

Ankra detects both automatically when it analyses a repository: a Postgres client dependency, an ORM configuration, or a composed database marks the application as database-needing, its referenced connection variables are wired to the `${{ ankra.demo_database.* }}` placeholders, and a recognised migration script becomes the migration command — so the first demo of a database-backed application works without any manual configuration. Detection only ever seeds an application that has no demo configuration yet; it never overwrites what you or the pre-setup agent saved.

### The demo container port

The demo's readiness probe, Service, and preview route all target one container port, resolved in this order: the component's recorded port, the generated runtime Dockerfile's `EXPOSE`, the generated Deployment manifest's `containerPort`, the analysed `target_port` parameter, and only then the platform default. The launch dialog shows the resolved port and where it came from; a port you did not edit is left to the platform to resolve.

When the resolved port is still wrong — stale analysis, a hand-edited Dockerfile — the platform corrects itself at runtime: a demo whose container runs cleanly but never accepts connections has its logs read for the port the server actually announces (`Accepting connections at…`, `Listening on…`, and the other common startup banners). If the evidence is unambiguous, the demo is repointed at the announced port on the fly, the correction is recorded on the application so the next launch resolves it statically, and the demo detail page shows the correction. Ambiguous evidence never auto-corrects; it flows into the failure message ("Nothing accepted connections on port 3000. The container's logs say it listens on port 8001.") and dispatches the pre-setup agent instead.

### Automatic pre-setup when a demo crashes

An image that validates its environment on boot — refusing to start without a database URL, an auth secret, an API key — crash-loops when demoed with no configuration. Ankra now detects this and fixes it with an agent:

1. When a demo fails with a **startup crash** (CrashLoopBackOff or a container configuration error), a **failed migration command**, or a port-evidence timeout (the container announced a different port than the demo probed), Ankra dispatches a one-shot **pre-setup agent** for it automatically. The run appears on the **AI agents** page like any other mission.
2. The agent reads the crashed container's logs, works out which environment variables the application demands, and generates a **pre-setup**: missing database URLs become `${{ ankra.demo_database.* }}` references with the throwaway Postgres enabled, secrets get fresh random values, and mode flags get the value that avoids external side effects.
3. It saves the pre-setup as the application's demo defaults — so **every future demo inherits it** — and redeploys the failed demo to prove it boots.

The agent can also set the migration command and database extensions when the logs show schema or `CREATE EXTENSION` failures. It never weakens the application's own validation, never reuses values found in logs, and merges with existing demo settings rather than replacing what you configured. Dispatch is bounded to one run per demo per day; image-pull failures and provisioning timeouts never dispatch (no environment can fix those). You can also trigger it on demand with `POST /org/applications/{application_id}/demos/{workspace_id}/fix`, or just ask the AI assistant to fix the failed demo — the chat has the same `get_demo_diagnostics`, `update_application_demo_config`, and `redeploy_demo` tools the mission uses.

***

## Managing applications

| Action | What it does |
| - | - |
| **Retry** | Re-run analysis and generation after fixing an issue (for example, adding the right credential or repository permissions) |
| **Reconcile** | Re-evaluate the application against its repository and refresh its state |
| **Delete** | Disconnect the application from Ankra |

Which Ankra AI lanes run on the application's repository - the pull request review, the organisation skills review, the automatic preview URL - is set per application under **Settings** → **Ankra AI**. See [Application AI settings](/platform/application-ai).

***

Built the app with Claude? Watch it shipped to Kubernetes on Ankra.

[From the Claude App to Kubernetes: ship a Claude-built app on Ankra](https://www.youtube-nocookie.com/embed/vvKHNo-6ERQ?rel=0)

## Prerequisites

**1. Connect GitHub**

Add a [GitHub credential](/integrations/github) with access to the application's repository. The Ankra GitHub App needs permission to open pull requests, commit workflow files, and manage Actions secrets. Ankra installs the Ankra registry credentials on the repository automatically; for [your own registry](#using-your-own-registry) you set the login secrets yourself.

**2. Have a target cluster**

Make sure you have a [cluster](/guides/import-cluster) with the [agent](/concepts/cluster-agent) connected to deploy onto.

***

## API

Applications are available over the API for CLI and scripted use, under `/api/v1/org/applications` (bearer-token authenticated) - create, list, inspect, retry, reconcile, and delete. See the [API Reference](/api-reference/introduction) for endpoints and schemas.

The same lifecycle is available through Ankra's AI and MCP clients - connect, deploy, retry, reconcile, and delete applications, and follow their CI workflow runs - see the [MCP Tool Reference](/platform/mcp-tools#applications).

See the [CI/CD Pipeline guide](/guides/cicd-pipeline) for how the generated pipeline fits into GitOps.


# Backup Vaults
Source: https://docs.ankra.ai/concepts/backup-vaults

How backup vaults, stack backup policies, restore points, runs and backup posture fit together, and why Ankra copies data between clusters by restoring from a backup.

> [!NOTE]
>
> A backup vault is an organisation-level record of an S3-compatible bucket you own, plus the credentials to reach it. Everything Ankra backs up is written there; nothing passes through the platform.

## The five objects

| Object | Scope | What it is |
| - | - | - |
| **Backup vault** | Organisation | A bucket + credentials, verified by Ankra before use. One organisation can have several - a production vault and a staging vault, or one per region. |
| **Backup policy** | Stack | "Protect this stack": a vault, a schedule and a retention. Stored as the stack's own `backup` block, not as a separate object. |
| **Restore point** | Stack | One captured backup: when it was taken, what triggered it, the assets in it, what it could **not** carry, its size, and its status. |
| **Run** | Organisation | The unit of work that takes, restores or clones a restore point, with a step for each thing it does. Every capture answers with the run that will seal it. |
| **Backup posture** | Stack, cluster, fleet | The answer to "is this data protected, and if not, why" - `protected`, `unprotected` or `unknown`. |

## Where the data flows

```
source cluster  ──write──▶  vault bucket  ◀──read──  target cluster
      (agent)                 (your S3)                 (agent)
```

The source cluster's agent writes backups straight to the bucket. A target cluster - another Ankra cluster, or a UAT environment - reads them back over HTTPS. The platform orchestrates and records; it never holds a byte of your data, which is why a vault must be reachable from the clusters themselves and not just from Ankra.

## Why backup-first

Copying a database live between two clusters needs a network path between them, a consistent snapshot, and a way to replay changes - and it produces nothing durable. Restoring from a backup needs only the bucket, produces a disaster-recovery copy as a side effect, and is how every database operator already models its own recovery. Ankra therefore recommends a backup policy on every stateful stack.

## Engines

The engine that captures an asset decides how consistent its restore point is, and every engine records its honest answer in the restore point rather than an aspiration.

| Engine | Handles | Consistency | Restore in place |
| - | - | - | - |
| Velero | Any persistent volume (Redis, Prometheus, anything on a PVC) | **Crash-consistent.** The workload's own replay (WAL, AOF) finishes the job on restore | Supported |
| Logical dump | PostgreSQL and MySQL captured as a dump, including every `ankra migrate` import | Transactional per dump | Supported |
| CloudNativePG | PostgreSQL clusters run by the CNPG operator, captured through the barman-cloud plugin | Transactional, with point-in-time recovery | **Not yet** - see below |
| Percona | MySQL clusters run by the Percona operators, captured through the operator's own backup | Transactional (XtraBackup) | **Not yet** - see below |

A volume owned by a database operator is backed up by that operator's engine, never twice.

**Volumes are captured two different ways, and which one you get is measured, not assumed.** Where the platform has observed the cluster's CSI driver and that driver can take a volume snapshot, Velero moves the data through a snapshot. Where it has observed that the driver cannot - Hetzner's CSI is the case to know about - or where it has not observed the cluster's storage at all, Velero falls back to file-system backup: slower, universally available, and honest. A cluster the platform has never seen is never assumed to support snapshots, because a render that assumed it would silently produce nothing. The restore point records which it was.

## What a restore point carries

A restore point is self-describing: a schema-versioned manifest naming every asset in it, the source cluster and its Kubernetes version, the sizes, and the list of what the capture could **not** take.

**That last list is a first-class field, not a footnote.** Every engine reports what it left behind and why, and every listing and detail read carries it - in the CLI, in the API and in the dashboard. A volume outside the selection, a data engine no adapter covers, an external managed service that lives outside the cluster: each appears with a reason and a remedy. Silence about un-carried data is the one failure mode that turns a backup product into a liability, so a backup listing that showed sizes and hid omissions would defeat the point of having one.

## Restoring in place

Restoring a restore point over the stack it came from destroys before it replaces: the workloads that own the data are scaled down, the volumes the restore point replaces are removed, the assets are restored, and the workloads are scaled back up. That sequence is printed before any of it runs, and typing the stack's own name is what starts it.

> [!WARNING]
>
> **A restore point carrying a CloudNativePG or Percona database cannot be restored in place yet, and Ankra refuses rather than pretending.** Velero's update policy patches an object's metadata, so a bound claim keeps the volume it was already bound to and the data on disk is never replaced; CloudNativePG's bootstrap runs once, at cluster creation, and an existing cluster ignores it. Running the ordinary path anyway would report success over unchanged data, which is worse than refusing. Those databases are still captured, and still restorable into a new cluster once that lane ships.

## Backup posture

Posture is the same verdict rendered on the stack, the cluster and the fleet, and it has three states rather than two:

| State | Means |
| - | - |
| **Protected** | The stack has an enabled policy naming a vault that is ready. |
| **Unprotected** | No policy, or a policy whose vault is missing or not ready, or one that excludes databases from a stack that runs them, or a stack that holds no data at all. The reason is always given. |
| **Unknown** | The platform could not tell: the stack's `backup` block did not decode, the vault lookup could not be answered, or the cluster's inventory has not landed. |

There is deliberately no boolean beside this. "We could not tell" is a different answer from "this is not protected", and collapsing the two is how a cluster nobody can read gets reported as a cluster with nothing to protect.

## Two ways a vault comes to exist

An **Ankra-provisioned** vault (`ankra_provisioned`) is created from one of the organisation's provider credentials: the platform creates the bucket on that provider, mints the access keys where the provider's API allows it (UpCloud, DigitalOcean), reuses the credential's own keys where they already are S3 keys (Scaleway), or stores the pair the user supplied where the provider issues keys only in its console (Hetzner). A **bring-your-own** vault (`customer_s3`) registers a bucket that already exists, on any S3-compatible service, with its keys. Both end up identical from the backup tooling's point of view: an endpoint, a bucket, a key pair and a repository password in the secret store.

Provisioning runs as a platform job: the vault is recorded in `provisioning` the moment the request is accepted, and moves to `ready` or `error` when the job finishes. Every step of the job is written to be repeatable, so running it again reuses what an earlier attempt created rather than creating it twice - but nothing re-runs it on its own today, so a failed run is recovered by deleting the vault and provisioning again.

## Credentials

Vault credentials live in Ankra's secret store from the moment you submit them. They are never returned by the API, the dashboard or the CLI, never written into a cluster's stack definitions, and never included in exports. Inside a cluster, the backup tooling reads them from a Secret the platform manages.

The vault also holds one **repository password**, minted when the vault is created, which encrypts the volume data in the bucket. Every cluster pointed at that vault is given the same one. A per-cluster password would make a restore point readable only from the cluster that wrote it, which would make restoring into a second cluster impossible - so a vault without a stored repository password is refused rather than allowed to fall back.

Deleting a vault removes Ankra's record and credentials; the bucket and its objects are untouched unless you explicitly ask for the provider resources to be destroyed with it, which Ankra only offers for a vault it provisioned itself.

## The backup data plane

Protecting the first stack on a cluster installs `ankra-backup`, a system stack Ankra owns and keeps current: Velero and its node agent, a CSI snapshot controller and `VolumeSnapshotClass` where the driver supports one, the CloudNativePG barman-cloud plugin where the cluster runs that operator, and cert-manager for that plugin's certificates where the cluster does not already have one. It is installed the same way on every kind of cluster - one Ankra provisioned, one you imported, a managed-Kubernetes cluster, a playground - because a backup product that only protects the clusters the platform built is not a backup product.

You do not author it, and you should not edit it. Unprotecting the last stack never removes it either: the restore points already taken are restored *through* it, so tearing it out would make them unrestorable.

## Permissions

`backups.read` sees vaults, policies, restore points, runs and posture; `backups.operate` verifies a vault, takes restore points and runs restores; `backups.manage` creates and deletes vaults, sets policies and deletes restore points. Organisation admins hold all three.

Permissions are the second gate, not the first: the organisation's **backups** feature is checked before them, so an organisation without the feature answers the same way whatever the caller may do. Beyond that, every restore point is addressed through the cluster and stack it was taken from, and one that belongs to a different cluster's stack of the same name answers exactly as an absent one does - `shop` is not a rare stack name, and two clusters must never see each other's restore points through their own URLs.

## Related

> [card] [Protect a stack and restore it](/guides/backups)
>
> Vaults, protection, restore points, restore in place, runs and troubleshooting.

> [card] [The backup block](/reference/importcluster#spec-stacks-backup)
>
> Every field and default of a stack's backup policy.


# Ankra Agent
Source: https://docs.ankra.ai/concepts/cluster-agent

Learn how the Ankra Agent connects your Kubernetes cluster to the platform.

Ankra has to reach into your cluster to deploy Stacks, read resources and stream logs, but you should not have to open the cluster to the internet for that. The **Ankra Agent** solves this: it runs inside the cluster, opens an outbound connection to Ankra, and carries every request over it. [How Ankra Works](/concepts/how-ankra-works) shows where the agent sits in the overall model.

The agent ships as a single Go binary on the **2.x version track** (`2.0.x`), installed with a Helm chart into the `ankra` namespace. Whether the platform upgrades a cluster's agent for you depends on the auto-upgrade settings described in [Upgrading the Agent](#upgrading-the-agent).

> [!NOTE]
>
> The agent requires **cluster-admin** permissions to manage all Kubernetes resources and deploy add-ons.

## What the Agent Does

* **Resource browsing** - lists and watches Deployments, Pods, Services and other resource types for the portal, CLI and AI.
* **Pod logs** - streams container logs to Ankra.
* **Deployments** - installs and upgrades your Stacks' add-ons and manifests with the native Helm engine (the default) or through ArgoCD. See [Deployment Engines](/concepts/deployment-engines).
* **kubectl access** - proxies authenticated `kubectl` requests to the cluster API server with no inbound ports. See [Accessing Clusters with kubectl](/guides/kubeconfig).
* **Fleet map reporting** - optionally reports the cluster's public egress IP so it appears on the [Dashboard](/platform/dashboard) world map.

***

## Installation

When you import a cluster, Ankra generates a Helm install command with a unique token. It looks like this:

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --version <agent-version> \
  --set config.ankra_url=https://platform.ankra.app \
  --set config.token=<your-token> \
  --namespace=ankra --create-namespace
```

Copy the exact command from the Import dialog rather than typing this one: it pins the agent version and carries your cluster's token.

The agent will connect to the platform and your cluster will appear online within seconds.

### Verify Installation

Check the agent is running:

```bash theme={null}
kubectl get pods -n ankra
```

View agent logs:

```bash theme={null}
kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent -f
```

***

## Cluster States

Every cluster carries one status badge, shown on the clusters list, in the cluster's sidebar and in the activity drawer. It combines whether the agent is connected with the health of what runs on the cluster:

| Status | What it means |
| - | - |
| **Healthy** | The agent is connected and nothing needs attention. |
| **Needs Attention** | At least one thing needs a person: the agent is offline, a resource is failing, the last operation failed, GitOps sync is failing or has a merge conflict, a resource is stuck pending, the kubelet version skew is unsupported, or there is an open AI insight. The badge is red when any of these is critical (agent offline, failing resources, a failed operation, failing GitOps sync, unsupported kubelet skew) and amber otherwise. |
| **Awaiting Connection** | An imported cluster whose agent has never connected. Run the install command to finish the import. |
| **Provisioning** | Ankra is building the cluster. The agent connects when setup completes. |
| **Stopped** | The cluster has been powered off on purpose. Start it to resume live data. |
| **Archived** | The cluster is parked and monitoring is paused. |
| **Destroying** | A playground cluster is being torn down. It leaves the list when the teardown finishes. |

The activity drawer lists the reasons behind a **Needs Attention** badge. A real failure always wins: a cluster that is provisioning, awaiting connection or stopped still shows **Needs Attention** if an operation failed or a resource is failing.

While the agent is offline, the cluster's workloads keep running, but Ankra cannot deploy to the cluster or show live resources and logs. Its configuration and history stay available. To bring it back, see [Agent Not Connecting](#agent-not-connecting).

***

## Configuration Reference

### Required Settings

| Parameter | Description |
| - | - |
| `config.token` | Authentication token (provided during cluster import) |
| `config.ankra_url` | Platform URL (default: `https://platform.ankra.app`) |

### Using an Existing Secret

For production environments, store the token in a Kubernetes secret:

```bash theme={null}
kubectl create secret generic ankra-agent-secret \
  --namespace ankra \
  --from-literal=token=YOUR_UNIQUE_TOKEN
```

Then reference it in your Helm install:

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --namespace ankra \
  --set config.existing_secret_name=ankra-agent-secret \
  --set config.secret_key=token
```

### Performance Tuning

For large clusters (1000+ resources), adjust these settings:

| Parameter | Default | Description |
| - | - | - |
| `nats_worker_max_workers` | `15` | Worker threads for command processing |
| `read_worker_count` | `5` | Concurrent worker slots for read jobs |
| `write_worker_count` | `5` | Concurrent worker slots for write jobs (create/update/delete) |
| `resources.limits.memory` | `512Mi` | Memory limit |
| `resources.requests.memory` | `256Mi` | Memory request |
| `replica_count` | `1` | Number of agent replicas |

Example for large clusters:

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --namespace ankra \
  --set config.token="YOUR_TOKEN" \
  --set nats_worker_max_workers=25 \
  --set resources.limits.memory=1Gi \
  --set resources.requests.memory=512Mi
```

### Fleet world map (public IP reporting)

To place an imported cluster on the [Dashboard](/platform/dashboard) world map when it has no recognisable cloud region, let the agent report its public egress IP on check-in:

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --namespace ankra \
  --set config.token="YOUR_TOKEN" \
  --set public_ip.reporting_enabled=true
```

When enabled, the agent performs an outbound HTTP lookup (to `public_ip.lookup_url`, default `https://api.ipify.org`) and reports the result. Leave it **disabled** (the default) for air-gapped clusters or where egress IP lookups are undesirable.

### All Helm Values

The complete value list - connection, workers, watch tuning, public IP reporting, image, security contexts, scheduling, and metrics - lives in the [Agent Helm Values reference](/reference/agent-helm-values).

> [!NOTE]
>
> The agent runs as a **non-root** container by default (`runAsNonRoot: true`, UID/GID `1000`, `readOnlyRootFilesystem: true`, all Linux capabilities dropped, `seccompProfile: RuntimeDefault`). Because the root filesystem is read-only, the chart mounts writable `emptyDir` volumes for `/tmp`, `~/.cache`, and `~/.config` via `writable_volumes.enabled` (default `true`). Don't lower these security settings unless you are running a custom image.

### Advanced tuning via `extra_env`

Less-common knobs are set as environment variables through `extra_env`:

| Env var | Default | Description |
| - | - | - |
| `KUBERNETES_HTTP2_ENABLED` | `false` | Enable HTTP/2 to the API server (only if the path supports it cleanly) |
| `KUBERNETES_REQUEST_MAX_ATTEMPTS` | `3` | List/get retry attempts on connection-terminated errors |
| `KUBE_PROXY_UNARY_CONCURRENCY` | `64` | Max concurrent unary requests through the kubectl proxy |
| `KUBE_PROXY_STREAM_CONCURRENCY` | `128` | Max concurrent streaming connections (watch/logs/exec) through the proxy |
| `DYNAMIC_API_DISCOVERY_ENABLED` | `false` | Discover and watch additional API groups dynamically |
| `RECONCILE_AUTO_HEAL_ENABLED` | `true` | Auto-heal native-engine releases stuck mid-operation |
| `FORWARD_SERVICE_REQUEST_MAX_TIMEOUT_SECONDS` | `120` | Upper bound for platform-requested forwarded-request timeouts (e.g. Prometheus) |

```yaml theme={null}
extra_env:
  - name: KUBERNETES_REQUEST_MAX_ATTEMPTS
    value: "5"
```

***

## Architecture

The agent uses a NATS-based architecture for real-time communication:

```mermaid theme={null}
flowchart TB
    Portal[Ankra Portal] <-->|HTTPS| Platform[Ankra Platform]
    Platform <-->|NATS JetStream| Agent[Ankra Agent]
    Agent <-->|Kubernetes API| Cluster[Your Cluster]
```

**Key features:**

* **Outbound connections only** - The agent initiates all connections, no inbound ports required
* **Real-time streaming** - Resource data streams efficiently using pagination
* **Automatic reconnection** - Handles network interruptions gracefully
* **kubectl proxy** - Forwards authenticated `kubectl` requests (including `watch`, `logs -f`, and `exec`) from the platform to the cluster API server, so you can reach private clusters without inbound access. See [Accessing Clusters with kubectl](/guides/kubeconfig).
* **Health monitoring** - Exposes `/livez` and `/readyz` endpoints on port 8080

***

## Network Requirements

The agent requires outbound connectivity to:

| Endpoint | Port | Purpose |
| - | - | - |
| `platform.ankra.app` | 443 | API communication |
| `command.platform.ankra.app` | 4222 | NATS real-time streaming |

No inbound ports need to be opened on your cluster.

***

## Upgrading the Agent

New agent releases are published on the `2.0.x` version track. When auto-upgrade is on, the platform rolls clusters forward to the latest published version, a few clusters at a time. You can still trigger an upgrade yourself at any time.

* Organisations created since 7 September 2026 have **Auto-upgrade Agents** on by default. Older organisations turn it on in **Organisation Settings** → **General**.
* A single cluster can opt out with **Disable Auto-upgrade** in its own settings.
* Every change to either switch is recorded in the [audit log](/guides/audit-log) (as `set_agent_auto_upgrade` for a cluster, on `update_organisation` for the organisation) with who made it, the setting it replaced and, when one was given, the reason (`ankra cluster agent auto-upgrade disable --reason "..."`, or `reason` on the MCP tool `set_cluster_agent_auto_upgrade`). Changes to the agent's sizing and pipeline settings are recorded the same way.

### From the Platform

In the cluster's **Settings** → **General**, click **Upgrade to v\<version>**. The agent will self-upgrade using Helm.

### From the CLI

```bash theme={null}
ankra cluster agent upgrade --cluster prod                                     # the newer of the running and the latest stable release
ankra cluster agent upgrade --cluster prod --version 2.1.1250                   # exactly that published release
ankra cluster agent upgrade --cluster prod --version 2.1.1247 --allow-downgrade # roll back on purpose
```

An upgrade you trigger never moves an agent backwards on its own: without `--version` an agent already on a newer release stays on it. A `--version` older than the running release is refused unless `--allow-downgrade` is also given, and a release that is neither published nor the one the agent runs is refused too; both refusals say why and change nothing. The MCP tool `upgrade_cluster_agent` takes the same `version` and `allow_downgrade`. See [`ankra cluster agent upgrade`](/reference/cli/cluster#ankra-cluster-agent-upgrade).

### Manually

```bash theme={null}
helm upgrade ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --namespace ankra \
  --reuse-values
```

Check the current agent version:

```bash theme={null}
kubectl get deployment -n ankra ankra-agent -o jsonpath='{.spec.template.spec.containers[0].image}'
```

***

## Troubleshooting

### Agent Not Connecting

1. **Check agent pods are running:**
   ```bash theme={null}
   kubectl get pods -n ankra
   ```

2. **View agent logs:**
   ```bash theme={null}
   kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent --tail=100
   ```

3. **Verify network connectivity:**
   ```bash theme={null}
   kubectl run --rm -it --restart=Never debug --image=curlimages/curl -- \
     curl -s https://platform.ankra.app/health
   ```

4. **Check the token is set:**
   ```bash theme={null}
   kubectl get secret -n ankra ankra-agent -o jsonpath='{.data.token}' | base64 -d
   ```

### Common Issues

| Issue | Cause | Solution |
| - | - | - |
| Cluster shows **Needs Attention** with *Agent offline* | Agent not running or outbound network blocked | Check the agent pods and firewall rules |
| Cluster stays **Awaiting Connection** | The agent was never installed, or cannot reach Ankra | Run the install command from the Import dialog, then check the agent pods |
| Token invalid | Token expired or revoked | Go to Clusters → Your Cluster → Settings → Generate Command to get a new install command |
| Connection refused | Outbound network blocked | Allow connections to `platform.ankra.app:443` |
| Resources not loading | Agent memory limits too low | Increase `resources.limits.memory` |

### Health Checks

The agent exposes health endpoints:

```bash theme={null}
kubectl port-forward -n ankra svc/ankra-agent 8080:8080
curl http://localhost:8080/livez
curl http://localhost:8080/readyz
```

***

## Uninstalling

To remove the agent from your cluster:

```bash theme={null}
helm uninstall ankra-agent -n ankra
kubectl delete namespace ankra
```

> [!WARNING]
>
> Uninstalling the agent will disconnect your cluster from Ankra. You'll need to re-import it to reconnect.

***

## Security

### RBAC Requirements

The agent requires cluster-admin permissions to:

* Browse all Kubernetes resources
* Deploy Helm charts and manifests
* Manage add-ons via the native Helm engine or ArgoCD
* Stream pod logs and proxy authenticated `kubectl` requests

The Helm chart creates a `ClusterRoleBinding` with the necessary permissions.

### Token Security

* Tokens are unique per cluster
* Tokens can be revoked by deleting the cluster from Ankra
* Store tokens in Kubernetes secrets (not in Helm values) for production


# Deployment Engines
Source: https://docs.ankra.ai/concepts/deployment-engines

How Ankra deploys and reconciles addons on your clusters.

The deployment engine is the part of Ankra that turns a Stack's add-ons into Helm releases on your cluster and keeps them there. You rarely choose one: new clusters use the native engine, and clusters created before it keep ArgoCD until you migrate them. This page explains what each engine does, how an update is applied, and how to move a cluster from ArgoCD to native. [How Ankra Works](/concepts/how-ankra-works) shows where the engine sits in the overall model.

## Overview

Ankra supports two deployment engines for add-ons:

* **Native (`ankra_native`)**: The Ankra agent uses the Helm CLI directly to
  install, upgrade, and reconcile chart-based add-ons. Releases are written to
  standard Helm storage (`helm.sh/release.v1` Secrets).
* **ArgoCD (`argo_cd`)**: The Ankra agent talks to an ArgoCD installation in
  the cluster, which renders the chart and applies it via server-side apply.

The engine is set per add-on, with a cluster-level default. New clusters use
the native engine. Clusters created before it keep ArgoCD until you
[migrate](#migrating-a-cluster-to-the-native-engine).

## Why migrate?

The native engine reduces the dependency surface on your cluster:

* No `argocd-server`, `argocd-application-controller`, `argocd-repo-server`,
  `argocd-redis`, `argocd-applicationset-controller`,
  `argocd-notifications-controller`, or `argocd-dex-server` to run on the
  cluster.
* No JWT lifecycle. The agent's existing ServiceAccount is the only auth.
* Add-on status comes from the agent directly, not from ArgoCD.

On the native engine every add-on is a normal Helm release, so `helm list`, `helm history`,
`helm rollback` and `helm get manifest` work directly against your cluster.

## Feature parity

| Feature | ArgoCD | Native |
| - | - | - |
| Self-heal on drift | Yes | Yes (per-addon `sync_policy.self_heal`) |
| Prune orphaned resources | Yes | Yes (`auto_prune` + post-apply orphan sweep) |
| `ignoreDifferences` (jsonPointers / jqPathExpressions / managedFieldsManagers) | Yes | Yes |
| Sync windows | Yes | Yes (cron-style schedule + duration + timezone) |
| Custom retry policy | Yes | Yes |
| `strict_health_check` | Yes (Healthy only, not Progressing) | Yes (Healthy only, not Progressing) |
| `revision_history_limit` | Yes | Yes (`--history-max`) |
| SOPS-encrypted values | Yes (helm-secrets) | Yes (direct `sops --decrypt`) |
| GitHub repos | Yes | Yes (HTTPS Contents API) |
| Bitbucket Cloud repos | Yes | Yes (HTTPS `2.0` Contents API, OAuth refresh) |
| GHCR via git token fallback | Yes | Yes |
| Multi-source applications | Yes | Not yet (single-source only) |
| ApplicationSet | Yes | Not used |

A cluster's GitOps repository can be on GitHub or Bitbucket Cloud. Bitbucket Data Center is not supported as a GitOps source under either engine.

## Applying an update

Installing or updating an add-on on the native engine runs
`helm upgrade --install`, and the step does not succeed until the release is
healthy. Two waits sit behind that, and both matter when an update cannot
converge on its own.

Helm waits first. The agent passes `--rollback-on-failure --cleanup-on-fail`,
which makes Helm wait for the release's resources to become ready and roll the
release back if they do not, whether or not `--wait` is passed. The budget is
the add-on's `helm_wait_timeout_seconds` setting, 600 seconds by default. The
automatic rollback then starts a fresh wait with the same budget, so a failing
update can occupy twice the configured timeout before the step reports.

The agent waits second, watching the rendered resources after Helm returns. If
that wait expires, the agent rolls the release back to its previous revision -
or uninstalls it, when the update was the add-on's first install.

Two add-on settings switch both behaviours off: `rollback_on_failure: false`
and `keep_failed_resources_for_debug: true`. With either set, Helm applies the
release and returns without waiting and nothing is rolled back. The agent still
watches the rollout and still reports a timeout if the resources never become
healthy, but the release keeps the new revision.

> [!WARNING]
>
> An update whose resources cannot become ready without a further action from you
> will not stick under the default settings. The common case is a DaemonSet with
> `updateStrategy: OnDelete`: its Pods keep the old spec until something deletes
> them, so the release never reaches ready, Helm times out and rolls back, and the
> add-on is left on its previous values.
>
> Apply such a change either by deleting the affected Pods while the wait is still
> running, or by setting `rollback_on_failure: false` on the add-on for that
> update and deleting the Pods afterwards. In the second case the step still
> reports a rollout timeout, but the new revision stays applied.

If the agent stops while a rollback is running, the release can be left in
`pending-rollback`, which blocks every later Helm operation on it. Clearing that
by hand is not necessary: the next update of the add-on recovers the release
before retrying, and so does the reconcile sweep below.

## Reconcile loop

The native engine reconciles each add-on on its own schedule. Ankra asks the
agent to reconcile an add-on whenever it is due. An add-on that just changed or failed is checked again within
a minute or two; one that keeps coming back unchanged backs off in steps (5, 10,
20 minutes) to a check every 30 minutes, and a repeatedly failing one backs off
to once an hour. Any change you make to the add-on makes it due immediately.

The schedule lives in the platform, not in the agent. While a cluster cannot
reach Ankra its workloads keep running untouched, but nothing is reconciled,
deployed or self-healed until the connection returns; the agent reconnects on
its own and the next due reconcile picks up where things stand. If the same
drift reappears on three consecutive reconciles, self-heal for that add-on is
paused for six hours rather than fighting whatever keeps changing the resource.

Each sweep:

1. Recovers any release stuck in `pending-*` for more than 10 minutes:
   first attempts a fresh `helm upgrade --install --atomic`; if that fails,
   rolls back to the last `deployed` revision.
2. Detects drift against `helm get manifest` (live resources fetched in
   parallel; Helm-injected metadata stripped from both sides before diff).
3. If drift is detected and `sync_policy.self_heal=true`, marks the addon for
   update so the existing reconciler re-runs `helm upgrade --install`.
4. If `sync_policy.auto_prune=true`, deletes orphaned resources whose UID is
   no longer in the rendered manifest.

## Sync windows

Set `settings.sync_window.enabled=true` on the addon and provide a 5-field cron
expression and duration. The agent will only run `create`/`update`/`self-heal`
operations inside the configured window. Outside the window, jobs return
immediately as `cancelled` with an "outside\_sync\_window" task message.

## Moving an add-on between namespaces

The native engine supports relocating an add-on to a different namespace. When you change an add-on's target namespace, the agent installs the release into the new namespace and cleans up the resources left behind in the old one, so you don't end up with orphaned objects. As with any namespaced move, persistent data tied to the old namespace (for example, `PersistentVolumeClaim`s) is not automatically carried over - plan for data migration where relevant.

## Migrating a cluster to the native engine

Moving a cluster from ArgoCD to the native engine is one flow in the portal:

1. Open the cluster's **Settings** → **General** and scroll to the **Danger Zone**.
2. Click **Decommission ArgoCD**. Ankra first runs a preflight check and shows
   the add-ons that will migrate, anything that blocks the migration (resolve
   those add-on issues first), and warnings you have to acknowledge.
3. Confirm with **Permanently decommission ArgoCD**. Ankra migrates every
   ArgoCD-managed add-on to the native engine, then removes the Ankra-managed
   ArgoCD user. Workloads keep running during the migration, and re-running a
   failed migration is safe.

Each add-on is adopted with `helm upgrade --install --take-ownership`, so its
live resources move into Helm storage without being recreated: resource UIDs
do not change and no Pod restarts. The only change on the cluster is Helm's
`app.kubernetes.io/managed-by=Helm` label and the `meta.helm.sh/release-name` /
`meta.helm.sh/release-namespace` annotations.

The decommission leaves the ArgoCD installation itself and any ArgoCD
`Application` CRs Ankra does not manage in place. Many teams keep using ArgoCD
outside Ankra. If you no longer need it, uninstall it yourself with the tooling
you installed it with (`helm uninstall argocd`, `kubectl delete -f install.yaml`,
or `argocd uninstall`), and remove the leftover `accounts.ankra` and
`policy.csv` entries from the `argocd-cm` and `argocd-rbac-cm` ConfigMaps if you
keep ArgoCD running.

The migration of addons is **one-way**: changing the cluster default
deployment engine back to ArgoCD after decommission is not supported.


# GitOps
Source: https://docs.ankra.ai/concepts/gitops

Manage your clusters with GitOps using one directory of YAML files per cluster in Git

A change made only in a portal has no review step and no history your team controls. Connecting a Git repository to a cluster gives you both: Ankra writes the cluster's Stacks to the repository, and commits you push are applied to the cluster. Sync runs both ways, and a repository is optional - a cluster without one is fully supported. [How Ankra Works](/concepts/how-ankra-works) shows where Git sits in the overall model.

***

## Repository Structure

There are two ways a cluster's files end up in a repository, and they can look different.

**The layout Ankra writes.** When you connect a repository, or change a cluster in the portal, CLI, API or through Ankra's AI, Ankra writes the cluster to its own directory:

```
my-repo/
  clusters/
    my-cluster-<short-id>/
      my-cluster.yaml              # the cluster's ImportCluster definition
      .ankra-owned.json            # what Ankra last wrote (never edit or delete)
      stacks/
        monitoring/
          add-ons/
            kube-prometheus-stack/
              values.yaml
          manifests/
            monitoring-namespace.yaml
```

Edit these files and push; Ankra applies the change. [What Ankra Writes Back to Git](#what-ankra-writes-back-to-git) explains how it avoids overwriting your edits.

**Files you add by hand.** Ankra reads one directory per cluster, the directory shown above. The file in it named after the cluster, `my-cluster.yaml`, is the cluster file, and it is the only file Ankra reads as a cluster definition. Every other file in the directory is content: it takes effect when an entry in the cluster file names it with `from_file`. You can add your own files anywhere in the directory except under `argocd/`, in subdirectories too:

```
my-repo/
  clusters/
    my-cluster-<short-id>/
      my-cluster.yaml              # the cluster file
      manifests/
        logging-namespace.yaml
        logging-namespace.AGENTS.md
        logging-rbac.yaml
      values/
        fluent-bit.yaml
```

The optional `AGENTS.md` sibling files hold per-manifest and per-add-on operational learnings for your team and Ankra's AI - see [Teach Your Agents with AGENTS.md](/platform/agents-md).

***

## Cluster Definition Example

The cluster file lists every manifest and add-on by `name` and points at its file with `from_file`. For the directory above, `my-cluster.yaml` reads:

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
spec:
  git_repository:
    provider: github
    credential_name: my-credential
    branch: main
    repository: my-org/my-repo
  stacks:
  - name: logging
    manifests:
    - name: logging-namespace
      from_file: manifests/logging-namespace.yaml
      agents_md_from_file: manifests/logging-namespace.AGENTS.md
    - name: logging-rbac
      from_file: manifests/logging-rbac.yaml
      parents:
      - name: logging-namespace
        kind: manifest
    addons:
    - name: fluent-bit
      chart_name: fluent-bit
      chart_version: 0.49.1
      registry_name: fluent
      registry_url: https://fluent.github.io/helm-charts
      namespace: logging
      configuration:
        from_file: values/fluent-bit.yaml
      parents:
      - name: logging-namespace
        kind: manifest
```

Each `from_file`, `agents_md_from_file` and `description_from_file` is a path relative to the cluster directory, and Ankra looks it up exactly as written among the files in that directory. There is no folder or wildcard form, a path that leaves the directory never matches, and Ankra never follows a symlink. When a manifest, an add-on's values, an application or a stack description names a file that is not there, the sync stops with an error ending `which is not in the repository snapshot` and applies nothing; a missing `AGENTS.md` file is skipped. An entry without a `name` stops the sync too: every manifest, add-on and application entry needs one.

One kind of file needs no entry. A file at `stacks/<stack>/manifests/<name>.yaml` (or `.yml`) that no entry already names, for a stack the cluster file declares, is added to that stack as a manifest called `<name>`, unless a stack already lists that name. If two declared stacks hold a file with the same unlisted name, the sync stops until you list it under the stack you mean.

`ankra cluster apply -f` reads the same keys on your machine. It resolves each path against the directory the applied file is in and refuses a path that is absolute or contains `..`, so running it on the cluster file in its cluster directory resolves the same `from_file` paths a sync does; it does not add unlisted manifest files. [Files in the cluster directory](/reference/importcluster#files-in-the-cluster-directory) lists every key that names a file.

***

## Single-File Cluster Definition

A cluster file you apply with `ankra cluster apply -f` can instead carry everything inline, with manifest and values content embedded as base64. This form is for the CLI only: a sync from Git refuses a cluster file whose manifests carry `manifest_base64`, and reads a manifest's content only from its file:

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
  description: Imported cluster with an inline stack
spec:
  git_repository:
    provider: github
    credential_name: my-git-credential
    branch: main
    repository: my-org/my-gitops-repo
  stacks:
  - name: secrets
    manifests:
    - name: secrets-namespace
      manifest_base64: <base64-encoded YAML>
      namespace: secrets
      parents: []
    addons:
    - name: external-secrets
      chart_name: external-secrets
      chart_version: 0.10.5
      registry_name: external-secrets
      registry_url: https://charts.external-secrets.io
      namespace: secrets
      configuration_type: standalone
      configuration:
        values_base64: <base64-encoded values.yaml>
      parents:
      - name: secrets-namespace
        kind: manifest
```

Use `parents` to control deployment order: a resource deploys only after its parents succeed. When Ankra writes a cluster like this to Git, it moves each manifest's and add-on's content into a file in the cluster directory and names it with `from_file`, as in the [cluster definition example](#cluster-definition-example).

Every field of this file - stacks, manifests, add-ons, applications, parents, and encrypted paths - is documented in the [ImportCluster YAML Schema](/reference/importcluster).

### Data Sources in the Cluster Document

The cluster's metrics and log data sources live in the same file, as `spec.prometheus_metrics` and `spec.log_source`. Both are read back on every sync, so writing either block in Git connects the source and updates it - you do not have to configure it in the platform first:

```yaml theme={null}
spec:
  prometheus_metrics:
    endpoint: http://prometheus-operated.monitoring.svc.cluster.local:9090
  log_source:
    provider: loki
    endpoint: http://loki-gateway.monitoring.svc:80
    credential_name: loki-read
```

Credentials stay out of Git: a `username`, `password`, `token` or `auth_scheme` inside a source block is refused, and the credential is referenced by `credential_name` instead. Deleting a block does not disconnect the source - Git can create and update one, only the platform can disconnect it. See [`spec.prometheus_metrics`](/reference/importcluster#spec-prometheus-metrics) and [`spec.log_source`](/reference/importcluster#spec-log-source).

***

## How Ankra Syncs Your Cluster

1. You update or add YAML files in your Git repository
2. Ankra detects the change and automatically syncs your cluster
3. Ankra reads the cluster file and the files it names with `from_file`, and applies the manifests and add-ons in the order you specify

```mermaid theme={null}
flowchart LR
    A[Git Push] --> B[Ankra Detects Change]
    B --> C[Read Cluster Directory]
    C --> D[Apply Manifests]
    D --> E[Deploy Add-ons]
    E --> F[Cluster Updated]
```

## What Ankra Writes Back to Git

Sync is two-way. Changes you commit are applied to the cluster, and changes made through the portal, the CLI, the API or Ankra AI are written back to the cluster's directory in the repository, so Git stays the record. A platform write lands as a commit authored by `ankra-platform[bot]` (a change made in the portal, CLI or API) or by `Ankra Reconciler` with the subject `Sync cluster state from Ankra` (the reconciler exporting stored state).

### The ownership manifest: `.ankra-owned.json`

Every cluster directory carries a file named `.ankra-owned.json`. Ankra rewrites it on each platform write. It is a record of what that write rendered - not an inventory of the directory, and not a claim on it:

* `paths` lists the files the last write rendered. It bounds **deletion**: when a stack or add-on is removed, only files listed here are pruned. A file Ankra never rendered is never deleted, only reported.
* `contents` maps each rendered file to a digest of the bytes Ankra itself last wrote there. It bounds **overwriting**: before writing a file, Ankra compares what is in Git with that digest. If they differ, the file was edited since, and Ankra keeps the Git version instead of replacing it.

Because the manifest is regenerated from each render, it grows when the cluster gains stacks or add-ons, and a write scoped to one stack may list a path it chose not to write. Neither means Ankra will overwrite that path; the digest decides.

> [!WARNING]
>
> **Never delete or hand-edit `.ankra-owned.json`.** It does not fail safe. With no manifest at head, Ankra has no record of what it wrote, so the overwrite boundary switches off and the next platform write replaces whatever is in Git. If it has been removed, restore it from Git history.

### Hand-maintaining a file

To keep a value Ankra would otherwise render - an image tag pinned above a chart's `appVersion` for a CVE fix, an `updateStrategy`, `topologySpreadConstraints` - edit the file in Git and merge it. Ankra syncs the change into the cluster, and from then on the file's bytes in Git no longer match the digest Ankra recorded, so no platform write replaces them. This holds for every write path: portal, CLI, API, Ankra AI and the reconciler's own export.

Three limits apply today:

* **SOPS-encrypted files are not covered.** Their committed bytes are ciphertext that cannot be reproduced from the render, so Ankra keys them on the embedded content fingerprint instead, and re-encrypts the file whenever its stored values change. A hand edit to an encrypted file sealed under the cluster's `.sops.yaml` is imported like any other Git change and then re-sealed by Ankra's next write - the values survive, the ciphertext does not, so expect one re-seal commit after rotating a sealed Secret by hand (see [Rotating by API](/integrations/prometheus#rotating-by-api) and [SOPS](/guides/sops)).
* **`.sops.yaml` in the cluster directory has its own rule.** Ankra rewrites the creation rules it generates there on every export, but it no longer replaces the file: rules you add by hand are kept, and kept above Ankra's own. See [Merging the SOPS configuration file](#merging-the-sops-configuration-file) below.
* **Deciding a preserved file takes the API for now.** While a file is preserved, a change made to it in Ankra does not reach Git, and the cluster reads **Diverged** for as long as the two versions differ. The portal and the GitOps status name those files, but neither the portal, the CLI nor the MCP tools can show both versions or decide them yet. See [Diverged files](#diverged-files) below.

### Diverged files

A file you edited in Git stays yours: no later platform write replaces it. When a later change in Ankra would change that file - an edit through the portal, the CLI, the API, Ankra AI or an MCP client, or a change Ankra makes to the cluster itself - Ankra keeps your bytes, records the file as **preserved** with both versions, and the cluster's GitOps status reads `diverged` instead of `synced`, with the files in `preserved_paths`. The portal shows **Diverged: Git Edits Kept** and lists them.

* **Nothing is paused.** Unlike a [conflict](#when-git-and-the-platform-both-change), a preserved file does not hold the sync. Commits to it and to every other file keep being applied, including a new stack or manifest you register in a preserved cluster file. Only Ankra's own change to that file waits.
* **Only a difference in substance counts.** YAML and JSON are compared as decoded documents, so comments, key order and quoting alone never make a cluster diverged. Your file is still kept byte for byte.
* **It clears when the two versions agree again** - you make the same change in Git, or Ankra's side changes back - or when a person decides it. It does not clear by waiting.

To decide, list the preserved files with both versions, then record a decision for each one. Both calls take an [API token](/api-reference/introduction) (a token scoped to MCP is refused), and the decision needs `clusters.write` on the cluster:

```sh theme={null}
curl -H "Authorization: Bearer $ANKRA_TOKEN" \
  "https://platform.ankra.app/api/v1/org/clusters/<cluster-id>/gitops/preserved-paths"
```

Each entry carries the `path`, Git's version as `head_content` (read at `head_commit_sha`), Ankra's version as `render_content`, the digest of each as `head_content_hash` and `render_content_hash`, when the difference was first seen as `detected_at`, and any `resolution_choice` already made. A file that may hold a secret is listed with `content_redacted` and no content; its digests are still exact.

Each entry also carries `structural_diff`, even when its content is withheld: the key path of every key or list member where the two versions differ, each marked `added`, `removed`, `changed` or `reordered` from Git's version to Ankra's. A value is shown only where Ankra's checks find nothing sensitive in it, and only to a caller holding `kubernetes.secrets_reveal` on the cluster; where a side holds a value that is not shown, the change reads `value_masked: true`, and a key name that may itself be a secret reads `<masked>`.

```sh theme={null}
curl -X POST -H "Authorization: Bearer $ANKRA_TOKEN" -H "Content-Type: application/json" \
  "https://platform.ankra.app/api/v1/org/clusters/<cluster-id>/gitops/preserved-paths/resolve" \
  -d '{"path": "<path>", "resolution": "git", "head_content_hash": "<head_content_hash>", "render_content_hash": "<render_content_hash>"}'
```

| `resolution` | What the next sync does |
| - | - |
| `git` | Imports Git's version into Ankra: wherever your file differs from Ankra's version, yours replaces it. It runs only once every preserved file on the cluster has a decision. The file stays yours, so a later change to it in Ankra is preserved again. |
| `cluster` | Writes Ankra's version over your file in Git, without your comments or layout, and the file is Ankra's to write again. Refused for a SOPS-encrypted file, which would put plaintext over ciphertext. |
| `none` | Withdraws a decision that has not run yet. |

A decision is pinned to the two digests it names. If either version has changed by the time you send it, the call answers `409` and you list again; if one changes before the sync runs it, the decision is cleared. A `git` import Ankra refuses - one that would lower a chart version, for example - records why in `import_refused_reason` and clears the decision, so you decide again. A `git` import never removes a stack: a stack Ankra declares and your file leaves out stays until you remove it through the platform.

### Merging the SOPS configuration file

The `.sops.yaml` in a cluster directory has two authors, so it is not covered by the digest boundary above: it is **merged** on every platform write instead of replaced, and the file it writes opens with a header saying so.

* **Ankra owns only the rules it generates**: a rule carrying a `path_regex` Ankra generates, an `age` key, and at most an `encrypted_regex` - and nothing else. Ankra rewrites those on every sync and lists them **last** in the file. While the cluster declares `encrypted_paths`, each generated rule carries an `encrypted_regex` built from the union of every declaration across the cluster's stacks, rebuilt on every sync as the declarations change, so a `sops -e` that applies the rule seals only declared secret keys and leaves every other key readable. It is one union per cluster, so it is broader per file than what Ankra itself seals per resource: a key declared secret for any resource in the cluster is sealed in every matching file.
* **Every other rule is yours.** It is preserved verbatim and kept **above** Ankra's own. SOPS applies the **first matching** creation rule, so a rule of yours takes precedence over Ankra's - including a deliberately keyless first rule, which is the supported way to keep a path out of encryption and make an external `sops -e` on it fail loudly rather than seal a file that must stay plaintext. **Write its `path_regex` relative to the cluster directory**, not the repository root: `sops` matches a rule against the file's path relative to the directory holding the `.sops.yaml` it is using, so for the cluster's file the path being tested is `stacks/<stack>/add-ons/<add-on>/values.yaml`. A rule written from the repository root never matches, and a refusal caused by *nothing* matching is an accident, not protection - see [Checking that a keyless rule applies](#checking-that-a-keyless-rule-applies).
* **To override one of Ankra's rules, write a rule that is not shaped like Ankra's**: keyless, using `key_groups`, carrying a field other than `path_regex`, `age` and `encrypted_regex`, or on a different `path_regex`. A rule that is a `path_regex` Ankra generates plus an `age` key, with or without an `encrypted_regex`, cannot be told apart from Ankra's own output and is replaced whatever its `age` or `encrypted_regex` values are - that is what lets a key rotation or a changed declaration reach the file, and it happens silently. To keep your own recipients or your own `encrypted_regex` on a path Ankra covers, name the recipients with `key_groups`. The warning below spells it out.
* **Other top-level keys are yours too.** `stores`, `kms`, `shamir_threshold` and anything else in the file are carried through untouched.
* **Ankra does not read these rules.** Its own encryption is driven per resource by that resource's `encrypted_paths` declaration, compiled to a SOPS `encrypted_regex` when the resource is sealed (see [SOPS](/guides/sops)). The file exists for external tooling that runs `sops` against the repository.

A `.sops.yaml` Ankra cannot parse is left exactly as it is, rather than rewritten.

#### Checking that a keyless rule applies

`sops` looks for `.sops.yaml` by walking **up from the current directory**, not from the file it is given, and matches each `path_regex` against the file's path **relative to the directory holding that `.sops.yaml`**. Test a rule from the repository root with an explicit `--config`, writing to stdout (never `-i`):

```sh theme={null}
sops --config clusters/<cluster-directory>/.sops.yaml -e clusters/<cluster-directory>/stacks/<stack>/add-ons/<add-on>/values.yaml
```

What comes back says which rule decided. The wording is from sops 3.13.3 and is not a stable interface; an automated check should key on the positive control below rather than on the text.

| Result | Meaning |
| - | - |
| `Could not generate data key: [empty key group provided]` | Your keyless rule matched first. The path is protected from a configuration-driven `sops -e`. |
| `error loading config: no matching creation rules found` | No rule matched at all, usually a `path_regex` written from the wrong base directory. The refusal is an accident, not protection. |
| `config file not found, or has no creation rules, and no keys provided through command line options` | `sops` found no `.sops.yaml` above the current directory. Pass `--config`, or run from inside the cluster directory. |
| Ciphertext on stdout | A rule with recipients matched first, or `--age` was given on the command line. `--age` bypasses the creation rules entirely, so a keyless rule does not stop it. |

Pair the check with a positive control in the same run: a neighbouring file that only a rule *with* recipients covers must encrypt, or the refusal proves nothing about your rule. Ankra's generated rules are written relative to the cluster directory (`.*values\.yaml$` and `.*manifests/.*\.yaml$`), so on a cluster synced since that change they match and can serve as the control: a values file only they cover must encrypt. A `.sops.yaml` still carrying the older repo-rooted spellings (`<cluster-directory>/.*values\.yaml$`) predates the change - those rules match nothing, Ankra's next write to the cluster replaces them, and until then a control needs a keyed rule of your own, written relative to the cluster directory like the keyless one.

> [!WARNING]
>
> **The shape to avoid: one of Ankra's own `path_regex` values, an `age` key, and nothing else except an `encrypted_regex`.** A rule in that shape cannot be told apart from Ankra's output, so the next platform write replaces it - with no signal anywhere. The sync succeeds, and no portal, CLI or API surface reports it. The only trace is the reconciler's own `Sync cluster state from Ankra` commit, where the rule is simply gone from the diff.
>
> All three conditions have to hold together - that `path_regex`, an `age` key, and no field beyond those two and `encrypted_regex` - so the only rules at risk are those whose `path_regex` is character-for-character one of the two Ankra generates:
>
> ```yaml theme={null}
> - path_regex: .*values\.yaml$
> - path_regex: .*manifests/.*\.yaml$
> ```
>
> The older repo-rooted spellings of the same two patterns, prefixed with the cluster's own directory (`<cluster-directory>/.*values\.yaml$`, `<cluster-directory>/.*manifests/.*\.yaml$`), are read as Ankra's too: clusters synced before the config-relative change still carry them, and the next platform write replaces them with the rules above. The examples below use that older spelling - the ownership test is the same for both.
>
> The trap is tidying. A deliberately keyless rule on one of those two patterns is yours and is kept - but give it an `age` key, to "complete" it or to seal that path with your own recipient, and it becomes Ankra's shape and disappears on the next write. Adding an `encrypted_regex` of your own does not take it back out: that field is part of Ankra's shape, so the rule is still replaced, and your selector with it:
>
> ```yaml theme={null}
> # Kept - keyless, so not Ankra's shape.
> - path_regex: <cluster-directory>/.*values\.yaml$
>
> # Replaced silently - Ankra's shape: its path_regex, an age key, nothing else.
> - path_regex: <cluster-directory>/.*values\.yaml$
>   age: age1...
>
> # Replaced silently too - encrypted_regex is part of Ankra's shape, whatever its value.
> - path_regex: <cluster-directory>/.*values\.yaml$
>   encrypted_regex: ^(password)$
>   age: age1...
>
> # Kept - same path, your own recipients, named with key_groups.
> - path_regex: <cluster-directory>/.*values\.yaml$
>   key_groups:
>   - age:
>     - age1...
> ```
>
> Any one of these keeps a rule out of Ankra's shape: leave it keyless, name recipients with `key_groups`, carry a field outside `path_regex`, `age` and `encrypted_regex` (`unencrypted_suffix`, for example), or write it on a `path_regex` Ankra does not generate. An `encrypted_regex` on its own does not: it is part of Ankra's shape. The header Ankra writes at the top of the file states the same test. The paths in this example show the ownership test only; a rule you rely on `sops` to apply must be written relative to the cluster directory, as described above.

> [!WARNING]
>
> **Removing the last `encrypted_paths` entry on a cluster deletes `.sops.yaml`, and your own rules with it.** Ankra renders the file only while the cluster has encrypted content. Clear the last `encrypted_paths` entry from the last add-on or manifest that had one, and the next platform write stops rendering `.sops.yaml`, so the export prunes it from the cluster directory. Ankra never reads `.sops.yaml` back in, so there is no copy in the platform to restore from - recover it from Git history.
>
> This matters most in the case that leads you there: removing an over-broad entry is the fix for a chart field that was sealed and should not have been (see [SOPS](/guides/sops#troubleshooting)). If that entry is the cluster's last one, keep a copy of `.sops.yaml` first, and re-commit your rules after Ankra's next write.

## When Git and the Platform Both Change

Because sync is two-way, the same resource can change on both sides between two syncs: someone edits a stack in the portal while a commit to the same stack lands in Git. Ankra does not guess which side you meant.

On every sync Ankra compares three things: the head of the branch, the state stored in the platform, and the baseline both sides last agreed on. That comparison has four outcomes:

| What changed since the baseline | What Ankra does |
| - | - |
| Only Git | Applies the commit to the cluster |
| Only the platform | Commits the change to Git |
| Both, on different resources | Merges them, applying the Git side and committing the platform side |
| Both, on the same resource | Records a conflict and waits for you |

A conflict pins the cluster's sync. Nothing further is applied from Git and nothing further is pushed to it until every conflicting resource has a decision. For each one you choose **Git** (the committed version wins and the platform change is dropped) or **Cluster** (the platform version wins and is committed over the Git version). Resolve conflicts from the GitOps section of the cluster settings, one resource at a time or all at once, or with the `list_gitops_conflicts`, `get_gitops_conflict_diff` and `resolve_gitops_conflict` [MCP tools](/platform/mcp-tools). Sync resumes on its own once the last conflict is decided.

There is no setting that makes one side win automatically. If Git should be the authority for a cluster, make changes to that cluster only through Git: with no platform-side edits there is nothing to conflict with. If a platform write finds a commit in Git that Ankra has not imported yet, the change is saved in the platform but its push to Git is held back, and the next sync merges the two sides or raises a conflict as above.

### Connecting a repository to a cluster that already has state

When you connect a repository to a cluster Ankra is already managing, Ankra first pushes the cluster's current state to the repository as a commit named `Connect GitOps repository`, then starts syncing. Connect an empty repository, or one Ankra has written to before. A repository that already holds files at the paths Ankra renders, and has no `.ankra-owned.json`, has no overwrite boundary yet, so that first push can replace those files.

You do not need a repository at all. With the [native engine](/concepts/deployment-engines), Ankra reconciles stacks and add-ons from the state stored in the platform, and a cluster with no repository connected is fully supported. Connecting one adds Git as a second place to read and make changes; it does not change how the cluster is reconciled.

***

## Monitoring Sync Status

Track the status of your GitOps syncs in the cluster settings.

### Sync Status Banner

Navigate to your cluster → **Settings** → **GitOps** to see the current sync status:

| Status | Description |
| - | - |
| **Synced** | All configurations are up-to-date with the repository |
| **Diverged: Git Edits Kept** | The last sync succeeded, but Ankra kept one or more files you edited in Git instead of writing its own, different version over them. Nothing is paused. See [Diverged files](#diverged-files) |
| **Syncing** | A sync is currently in progress |
| **Error** | The last sync failed. Check error details below |
| **Not Configured** | GitOps is not yet connected to a repository |

### Applied Commit and Git Head

`ankra cluster gitops status` and `GET /api/v1/clusters/{cluster_id}/gitops/status` report the last sync time and commit (`last_synced_at`, `last_commit_sha`) for the last full sync only. Beside them are two pointers:

* **Applied Commit** (`applied_commit_sha`, `applied_commit_at`): the commit Ankra holds the cluster in step with, and since when.
* **Git Head Checked** (`head_checked_sha`, `head_checked_at`): the head of the branch as Ankra last read it, and when.

The applied commit moves on a sync or a push, and also without one: when Git's head moves but leaves the cluster's directory unchanged - a commit for another cluster in the same repository, for example - Ankra moves the applied commit to that head without running or recording a sync, so the last sync time can read days old on a current cluster. The same commit on both pointers means the cluster was in step with Git at that read; a different head is a commit Ankra has not applied yet.

### Sync Progress

During a sync, you'll see the progress through these phases:

1. **Fetching** - Pulling latest changes from Git
2. **Validating** - Checking YAML syntax and configuration
3. **Applying** - Deploying changes to the cluster
4. **Completed** - Sync finished successfully

### Manual Sync

Click **Sync Now** to trigger an immediate sync from your Git repository. Use this when:

* You want to apply changes without waiting for automatic detection
* Webhook delivery failed
* You need to force a refresh

***

## Sync History

View a complete history of all GitOps syncs for your cluster.

### Accessing Sync History

1. Go to your cluster → **Settings** → **GitOps**
2. Scroll down to the **Sync History** table

### History Table Features

The sync history table shows:

| Column | Description |
| - | - |
| **Status** | Success, Failed, or Running badge |
| **Source** | How the sync was triggered (webhook or manual) |
| **Commit** | The Git commit SHA with a link to view in GitHub |
| **Started** | When the sync began (relative timestamp) |
| **Triggered By** | Who or what initiated the sync |

**Table Features:**

* **Pagination**: Navigate through history (10 entries per page)
* **Sorting**: Click column headers to sort by any field
* **Commit Links**: Click the SHA to view the commit in GitHub

### Sync Metadata

Each sync entry includes detailed metadata:

* **Last Commit SHA**: The exact commit that was synced
* **Sync Source**: `webhook` (automatic) or `manual`
* **Timestamp**: When the sync occurred
* **Retry Count**: Number of retry attempts (if any)
* **IAC Files Link**: Direct link to view the configuration files in your repository

***

## Handling Sync Errors

When a sync fails, Ankra provides detailed error information to help you fix issues quickly.

### Error Display

Failed syncs show:

* **Validation Errors**: Issues with YAML syntax or configuration
* **Field-Level Guidance**: Specific fields that need attention
* **Missing Fields**: Required fields that weren't provided
* **Typo Detection**: Suggestions for misspelled field names

### Common Error Types

> [accordion] Validation Errors
>
> YAML syntax issues or invalid configuration values.
>
> **Solution**: Check the error details for the specific field and fix the YAML in your repository.

> [accordion] Missing Required Fields
>
> Required configuration fields weren't provided.
>
> **Solution**: The error shows which fields are missing with examples of expected values.

> [accordion] Resource Conflicts
>
> A resource already exists or conflicts with another definition.
>
> **Solution**: Check for duplicate resource names or conflicting configurations.

> [accordion] A Section That Is Not a List
>
> `spec.stacks`, or a stack's `manifests`, `addons` or `applications`, is present but is not a list: a lost `-` or an indentation slip turns a list into a mapping, and a key with nothing after it is null. Nothing is applied, because reading it as an empty list would remove everything it declared before; the error names the section, for example `stack "logging": addons must be a list, got a mapping`.
>
> **Solution**: Fix the YAML. To declare none, write an empty list, for example `addons: []`.

### Large Removals Are Held

A sync that would remove a large share of the cluster at once is held: nothing in the commit is applied, and the sync fails with an error that starts `GitOps sync held, nothing was applied: this commit would remove` and names what would go. A sync is held when it would:

* Remove two or more stacks that have members, when they are half or more of the cluster's stacks with members, or more than three of them
* Remove two or more add-ons, manifests or applications from the stacks it keeps, when they are half or more of those stacks' members, or more than five of them
* Remove every member of a kept stack that has two or more

A commit that removes only one stack, or only one member, always applies. Anything you are already removing through Ankra does not count.

If the removal is intended, remove those stacks or members through Ankra: in the portal, or with `ankra cluster stacks delete` and `ankra cluster manifests delete`. The next sync then applies the rest of the same commit, without a new push; click **Sync Now** to run it straight away. If the removal is a mistake, such as a YAML slip or a merge conflict resolved the wrong way, restore them in the cluster file and push.

### Retrying Failed Syncs

1. Fix the issues in your Git repository
2. Commit and push the changes
3. Click **Sync Now** or wait for automatic detection
4. Monitor the new sync in the history table

A [held large removal](#large-removals-are-held) you meant to make needs no change in Git: remove those stacks or members through Ankra, and the next sync applies the same commit.

***

## Troubleshooting

If Ankra isn't syncing as expected:

| Issue | Solution |
| - | - |
| Sync not triggering | Check that Git credentials are valid and have repo access |
| A sync fails with `which is not in the repository snapshot` | An entry's `from_file` or `description_from_file` names a path no file in the cluster directory has. Write it relative to the cluster directory, exactly as the file is named, and commit the file itself rather than a symlink. See [Cluster Definition Example](#cluster-definition-example) |
| A sync fails with `GitOps sync held, nothing was applied` | The commit would remove a large share of the cluster in one sync. If you meant it, remove those stacks or members through Ankra and the next sync applies the rest of the commit; if not, restore them in the cluster file. See [Large Removals Are Held](#large-removals-are-held) |
| Invalid configuration | Ensure YAML files are syntactically correct |
| Wrong branch | Confirm the branch name in your cluster definition matches |
| Unsure which repository or commit a cluster deploys from | Run `ankra cluster gitops status --cluster <name>`. It prints the configured repository, branch and credential, and the **Applied Commit** and **Git Head Checked** with their times ([Applied Commit and Git Head](#applied-commit-and-git-head)). The repository the last successful sync actually read is `observed_source` in `GET /api/v1/clusters/{cluster_id}/gitops/status` and the `get_gitops_status` [MCP tool](/platform/mcp-tools); `source_mismatch` is `true` when it differs from the configured repository |
| A `prometheus_metrics` or `log_source` block you deleted keeps coming back | Removing the block is not a disconnect - the platform re-renders it. Disconnect the source in the cluster's **Settings** → **Integrations** |
| A field you added to a data source block fails the sync | Only the fields in the [ImportCluster schema](/reference/importcluster#observability-sources-in-git) are accepted; the error names the offending key. Credential fields (`username`, `password`, `token`, `auth_scheme`) are always refused - reference a credential by `credential_name` |
| A value you set in Git is reverted by a platform write | Check that `.ankra-owned.json` exists in the cluster directory - without it the overwrite boundary is off ([What Ankra Writes Back to Git](#what-ankra-writes-back-to-git)). Restore it from history, and report the reverting commit: its author, `ankra-platform[bot]` or `Ankra Reconciler`, tells support which write path produced it |
| A change made in the portal never reaches Git | The file is hand-maintained - its bytes in Git are not what Ankra last wrote, so Ankra preserves it and the cluster reads **Diverged**. Make the change in Git, or [decide the file](#diverged-files) |
| A cluster reads **Diverged** and nobody changed anything in Ankra | Something changed Ankra's side of a file you edited in Git. `ankra cluster gitops status` lists the preserved files, each with when it was detected and whether it has a decision. For both versions, [list them through the API](#diverged-files): `render_content` is Ankra's version, `structural_diff` names the keys that differ even when the content is withheld, and a `Sync cluster state from Ankra` or `ankra-platform[bot]` commit near `detected_at`, when that change wrote other files too, shows what else it changed. Decide the file through the API, and report it to support if the same file comes back after a `git` import |

> [!TIP]
>
> Use the Ankra WebUI to see sync status and any errors. The Operations page shows deployment history and helps identify issues.

***

## Related

* [Stacks](/concepts/stacks) - Learn about organizing resources into stacks
* [Add-ons](/concepts/addons) - Install Helm charts as add-ons
* [Manifests](/concepts/stacks#manifests) - Deploy your own Kubernetes YAML

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.


# How Ankra Works
Source: https://docs.ankra.ai/concepts/how-ankra-works

The one model behind every other concept page - organisation, cluster, Stack, add-ons and manifests, variables, Git and the deployment engine.

Every other page in this section describes one piece of Ankra. This page shows how the pieces connect, so you can read the rest in any order and know where each one sits.

```mermaid theme={null}
flowchart LR
    O[Organisation] --> C[Cluster<br/>runs the Ankra agent]
    C --> S[Stacks]
    S --> A[Add-ons<br/>Helm charts]
    S --> M[Manifests<br/>Kubernetes YAML]
    V[Variables] -.-> S
    G[(Git repository<br/>optional)] <-.-> C
    E[Deployment engine] --> C
```

## Organisation

An organisation is your team's account. It holds the members and their roles, the credentials Ankra uses for Git, registries and cloud providers, organisation-wide variables, and every cluster. Organisations that run several teams or products divide their clusters and applications into [projects](/concepts/projects), each a room a member can be limited to; every organisation starts with a Default project that holds everything. See [Organisations](/concepts/organisations).

## Cluster and agent

A cluster is any Kubernetes cluster Ankra manages, whether you imported it or Ankra built it. Each one runs the [Ankra agent](/concepts/cluster-agent), installed with Helm into the `ankra` namespace. The agent opens the connection to Ankra itself, so the cluster needs no inbound ports and works behind a firewall or NAT. When the agent is not connected, the cluster shows as needing attention and nothing is deployed to it until it reconnects - see [Cluster states](/concepts/cluster-agent#cluster-states).

## Stack

A [Stack](/concepts/stacks) is what a cluster should run: a named set of components with the order they deploy in. A cluster usually has several Stacks, one per concern - monitoring, ingress, your application.

## Add-ons and manifests

A Stack contains two kinds of component. An [add-on](/concepts/addons) is a Helm chart with its values. A [manifest](/concepts/stacks#manifests) is your own Kubernetes YAML, such as a namespace, a Secret or a custom resource. Dependency edges between them decide what deploys first.

## Variables

[Variables](/concepts/variables) hold the values that differ between clusters, such as a domain name or a replica count. You write `${{ ankra.name }}` in values or YAML, and Ankra fills it in when it deploys. You can set a variable on the organisation, a cluster or a Stack, and the more specific one wins.

## Git (optional)

You do not need a repository. Ankra stores each cluster's Stacks itself and deploys from there. When you connect a repository, sync runs [both ways](/concepts/gitops): Ankra writes each cluster's Stacks to its own directory in the repository, and commits you push are applied to the cluster.

## Deployment engine

The [deployment engine](/concepts/deployment-engines) is what turns a Stack into running resources. New clusters use the native engine: the agent runs Helm on the cluster itself and keeps each add-on in line with its Stack. Clusters created before the native engine keep ArgoCD until you migrate them.

## Where to go next

Read the concept pages in order, starting with [Organisations](/concepts/organisations), or follow the [Quickstart](/get-started/quickstart) to see the whole chain work on a real cluster.


# Managed Services
Source: https://docs.ankra.ai/concepts/managed-services

Run PostgreSQL, Valkey, NATS, OpenSearch, S3-compatible object storage, VictoriaLogs and VictoriaMetrics on your own cluster from a package Ankra publishes, and connect them to your applications.

> [!WARNING]
>
> **Closed beta.** Managed services are in closed beta. They are part of the new Ankra portal and are enabled per organisation on request. [Contact support](/platform/support) to have managed services turned on for your organisation.

A managed service is a backing service your applications use, such as a database, a cache or a queue, set up from a package Ankra publishes. You add one from the application that will use it, or from the catalogue. You choose the application environments that will use it, the cluster it runs on and its size. Ankra prepares a plan from those choices, and nothing is installed until you confirm it. Ankra then installs the service on your cluster and shows its progress, its health and how to connect to it under **Managed services** and on the **Services** card of each application it serves. Once the service is ready, Ankra delivers its connection into the namespace of each application it serves on the same cluster, and the application's containers read it as environment variables. When one application no longer needs a service, you disconnect that application through a reviewed plan, and the service keeps running for the others. When you no longer need a service at all, you delete it through a reviewed plan.

While managed services are in the pilot, Ankra charges nothing for them. Their running time and storage are recorded as [usage](/platform/usage).

## The services

Ankra publishes seven services, each built on an open-source engine:

| Service | Provides | Engine | Licence |
| - | - | - | - |
| `postgresql` | Database | PostgreSQL 18.6, run by the CloudNativePG operator | PostgreSQL Licence (operator: Apache-2.0) |
| `valkey` | Cache | Valkey 9.1 | BSD-3-Clause |
| `nats` | Queue | NATS 2.15 with JetStream | Apache-2.0 |
| `opensearch` | Search | OpenSearch 3.9 | Apache-2.0 |
| `seaweedfs` | Object storage (S3 API) | SeaweedFS 4.48 | Apache-2.0 |
| `victoria-logs` | Logs | VictoriaLogs 1.52 | Apache-2.0 |
| `victoria-metrics` | Metrics | VictoriaMetrics 1.153 | Apache-2.0 |

[Managed Service Settings](/reference/managed-services) lists every setting of each one.

## Who runs it

Every service in the catalogue runs on **Your infrastructure**: Ankra installs it on one of your clusters, and your team operates it. You own the cluster, the service's availability and the cost of the capacity it uses. Ankra supplies the package, installs the plan you confirmed and keeps a record of the installation.

**Ankra-hosted** services, which Ankra would run for you, are not available yet.

## How a service runs

* **One stack, one namespace.** Each service is deployed as a stack named after the service, into a namespace of the same name. Several services can share a cluster, including several of the same kind.
* **The service owns its stack.** Deleting the stack on its own is refused, and so is deleting the cluster the service runs on until the service is deleted. Deleting an application the service serves is refused until you [disconnect the application](/guides/disconnect-an-application-from-a-managed-service) from it or delete the service. A cluster whose agent has been offline for 15 minutes, and a playground, can still be deleted: see [A cluster or application a service depends on](/guides/delete-a-managed-service#a-cluster-or-application-a-service-depends-on). To remove the service, [delete it](/guides/delete-a-managed-service): that removes the stack and then deletes the namespace with its data, after you review the plan.
* **Credentials are generated in the cluster.** When a service is first installed, it generates its own password or keys and keeps them in a Kubernetes Secret in its namespace. Every later apply reuses them. Ankra never sees or stores the values, and deleting the service deletes them with its namespace.
* **Cluster-internal only.** Nothing is exposed outside the cluster. Applications reach the service at fixed in-cluster addresses. Inside the cluster, PostgreSQL, Valkey, NATS, OpenSearch and SeaweedFS admit their client port (5432 for PostgreSQL) only from the service's own namespace, the namespace of the cluster's Ankra agent and the namespaces of the applications connected to the service, where the cluster's network plugin enforces NetworkPolicy. A service installed on an earlier package version keeps that port open to every namespace. VictoriaLogs and VictoriaMetrics admit their client port from every namespace.
* **Connections are delivered inside the cluster.** Each application environment the service was set up for, on the service's cluster, receives a `<service>-connection` Secret in its own namespace, copied in the cluster from the service's credentials Secret, and its workloads read it as environment variables such as `DATABASE_URL`. Once the service is ready, Ankra writes the Secret without a redeploy while none of the application's running pods references it, and otherwise leaves it to the application's next deploy. Ankra never sees the values. See [Connect to a Managed Service](/guides/connect-to-a-managed-service).
* **Native deployment engine.** The credentials are generated with a Helm lookup against the live cluster, which only Ankra's [native deployment engine](/concepts/deployment-engines) evaluates. On an ArgoCD cluster every sync would generate new credentials under running applications, so Ankra only places services on native-engine clusters.

## Health and readiness

Ankra reports two things about a running service, and they answer different questions: whether it is running as planned (health), and whether a client can connect to it (readiness).

### Health

Ankra observes each service about once a minute from its own synced view of the service's cluster: the service's workload against the size you chose, the Kubernetes Service its addresses name, the credentials Secret with every key the connection details list, and the stack that owns it. It never reads the Secret's values. Each observation stands for five minutes. [Health checks](/reference/managed-services#health-checks) lists what is checked for each service.

| Health | In the portal | Meaning |
| - | - | - |
| `serving` | **Serving** | Every check passed. |
| `progressing` | **Not serving yet** | A check has not passed while the deployment is still being applied, or within the first minutes after it finished: 10 minutes for PostgreSQL and OpenSearch, 5 for the other services. |
| `degraded` | **Service degraded** | A check failed after that window, a member of the stack failed to apply or is being removed, or the stack that owns the service is gone or being removed. The portal shows the reason. |
| `unknown` | **Health unknown** | Nothing failed, but Ankra could not see enough of the cluster to judge: the cluster's agent is offline, or Ankra's view of a resource type on the cluster is more than 15 minutes old. An observation older than five minutes also reads unknown. |

Health describes the running service, not the operation that deployed it: a failed deployment whose workloads all run reads serving, and one that left a workload missing reads degraded at once. A cluster that is offline reads unknown, never degraded.

In the portal, each service in **My services** carries a **Health** badge, and the service's page has a **Service health** section with the state, when it was observed and what decided it. Until Ankra has observed the service, the section reads **Not observed**. Health is not shown for a deleted service or while a service is being deleted.

### Readiness

Health does not prove that your applications can connect. A serving PostgreSQL service has a ready primary and its credentials Secret, but that does not show a client can reach it and log in. Readiness does.

Ankra checks readiness for every service it publishes, about every five minutes. The cluster's agent starts a short-lived pod in the service's namespace that connects to the address the service publishes, as a client would, with the credentials taken from the service's credentials Secret by reference, and does one small round trip:

| Service | What the check does |
| - | - |
| PostgreSQL | Connects to the read-write address as `app` and runs `SELECT 1`. |
| Valkey | Sends `PING`, then sets a key with a 60-second expiry, reads it back and deletes it. |
| NATS | Answers a request on a check subject from one connection and sends it from another, so a message makes the round trip through the server. |
| OpenSearch | Over TLS, trusting the service's own CA: cluster health must be green or yellow, then it writes, reads and deletes one document in the hidden index `.ankra-canary`. |
| S3-compatible object storage | Writes, reads and deletes one object in the bucket `ankra-canary`, creating the bucket when it is missing. |
| VictoriaLogs | Writes one log line to the stream `{ankra_canary="readiness"}` and reads it back. |
| VictoriaMetrics | Imports one sample of `ankra_canary_probe`, reads it back and deletes the series. |

Everything a check writes is its own, named after the check run, and deleted in the same run. The one exception is the VictoriaLogs line: VictoriaLogs cannot delete single lines, so it stays in the `ankra_canary` stream until your retention removes it. A query that selects your own streams never sees it.

The credentials never leave the cluster, and Ankra keeps no log of the check. A result stands for 15 minutes.

| Readiness | Meaning |
| - | - |
| `verifying` | No check has passed yet. None has run, or the latest failed or could not run while the service was still deploying, or within the grace window after its deployment finished: 10 minutes for PostgreSQL and OpenSearch, 5 for the other services. |
| `ready` | A check passed within the last 15 minutes. |
| `degraded` | A check ran and failed after the service had its chance to start. Once a check has passed, a failure reads degraded straight away. |
| `stale` | Readiness cannot be established right now. The check could not run - no agent, the cluster unavailable, or the pod refused or not finishing - or the last result is more than 15 minutes old. A check that could not run never reads as a failure, and the last result stands until it expires. |
| `unverified` | No check covers the service, or the cluster's agent is too old to run it. For any service other than PostgreSQL, the agent must be recent enough to run the check: until it is, the service reads unverified and `readiness_check.reason` says to upgrade the agent. |

Readiness is reported on the service in the API, as `readiness` and `readiness_check` on [Get a managed service instance](/api-reference/services/get-a-managed-service-instance). The portal shows it on the service's page and in **My services**: **Ready**, **Verifying**, **Not ready** (`degraded`), **Not checked recently** (`stale`) or **Not verified** (`unverified`). While a service reads unverified, check it yourself before you rely on it: see [Check that the service answers](/guides/connect-to-a-managed-service#check-that-the-service-answers).

## Data policies

A **data policy** declares the region a cluster keeps data in and its data boundary. It is optional: you can set up services without one. Declare a policy when services must keep data within a boundary. Your organisation declares it in the cluster's settings. Ankra records who declared it and does not verify the location.

A cluster without a declared policy reads region and data boundary `unspecified`. That boundary is shared by every cluster without a policy, and cannot be declared by hand.

Once a cluster declares a policy, it decides where a service may run:

* One service connects only environments within one data boundary. Environments in two boundaries need two services. A cluster that declares a policy and one that does not are in different boundaries, so one service cannot serve both.
* A cluster can declare that services bound to it must run on that cluster only.

A plan records the policy it was reviewed against. A review prepared before a cluster declares or changes its policy needs a new review.

## Limits and good to know

* **A finished deployment is not yet a ready service.** A PostgreSQL service can report its deployment finished 30 to 100 seconds before the database accepts connections; any service's readiness reads `verifying` until a check passes.
* **Readiness checks need a pod they can start.** The check pods pull their images from Docker Hub (`postgres:16-alpine` for PostgreSQL, `valkey/valkey`, `natsio/nats-box` and `curlimages/curl` for the others); a cluster that cannot pull the image in time cannot run the check, and readiness then reads `stale`. Every check pod runs as non-root, with privilege escalation off, every capability dropped and the `RuntimeDefault` seccomp profile, which a namespace that enforces the `restricted` Pod Security Standard admits. The check pods other than PostgreSQL's also have a read-only root filesystem. On a cluster whose DNS domain is not `cluster.local` the checks fail, as the published addresses do.
* **Connections are delivered within one cluster, without restarting anything on their own.** Once the service is ready, Ankra writes an application environment's connection by itself only while none of the application's running pods references it. When running pods do, Ankra leaves it to the application's next deploy, which writes it and rolls those workloads together, so pods restarting one by one never read different values. A workload deployed before the service was connected reads the connection only after its next deploy adds the reference to it. An application on another cluster than the service is not connected for you: give it the values yourself, as in [Connect from another cluster](/guides/connect-to-a-managed-service#connect-from-another-cluster).
* **Only PostgreSQL is backed up.** In an organisation with backups enabled, a PostgreSQL service is protected into the organisation's [backup vault](/guides/backups): its write-ahead log is archived continuously and a base backup is taken daily, kept for 7 days. It is installed without backups on a playground cluster, whose data is for testing, and when the organisation has no verified backup vault or more than one; the installation then says so, and `ankra cluster stacks protect <service> --vault <vault>` protects it later (the `--vault` flag is always required). A PostgreSQL service installed on an earlier package version has no backups. Restoring a service from **Managed services** is not available yet, and a restore point that carries a CloudNativePG database cannot be [restored in place](/guides/backups) yet either. Valkey, NATS, OpenSearch, SeaweedFS, VictoriaLogs and VictoriaMetrics are not backed up: do not keep data you cannot recreate in them without a backup of your own.
* **Settings are fixed after setup.** Changing, upgrading or recovering a service from **Managed services** is not available yet. You can [delete a service](/guides/delete-a-managed-service) and set it up again, which starts it with new credentials and none of its data.
* **NATS runs a single server.** The `nats` package has no clustered option yet.
* **OpenSearch runs a single node.** An index created with replicas stays yellow.
* **SeaweedFS keeps its data on one volume.** It runs as a single pod and is unavailable while that pod restarts, which happens once, for about 40 seconds, the first time Ankra reconciles it after installation.

> [!WARNING]
>
> **Deleting a service deletes its data.** Its namespace is deleted with every volume claim and Secret in it, and no export is made first. A SeaweedFS service's volume goes with its stack, the first thing a deletion removes, so its objects can be gone even when the deletion then stops short. Export anything you need first. When Ankra cannot show that the data is gone, for example because a volume's reclaim policy kept it, the deleted service reads **Deleted, data may remain** and its page lists the volumes that may still hold it. See [Delete a Managed Service](/guides/delete-a-managed-service#when-data-may-remain).

## Related

> [card] [Set up a managed service](/guides/set-up-a-managed-service)
>
> Prerequisites, the four setup steps, and following the installation.

> [card] [Connect to a managed service](/guides/connect-to-a-managed-service)
>
> Addresses, credential Secrets, and wiring them into an application.

> [card] [Disconnect an application](/guides/disconnect-an-application-from-a-managed-service)
>
> Take one application off a service that keeps running for the others.

> [card] [Delete a managed service](/guides/delete-a-managed-service)
>
> Review what is removed and kept, confirm, and follow the deletion.

> [card] [Managed service settings](/reference/managed-services)
>
> Every setting of each service, and the health and readiness checks.

> [card] [Applications](/concepts/applications)
>
> The applications whose environments use a service.


# Organisations & User Management
Source: https://docs.ankra.ai/concepts/organisations

Manage your organisations, invite users, and control access in Ankra.

An organisation is your team's account in Ankra. It holds the clusters, the people who can reach them and what each person may do, and the credentials and variables every cluster shares. If you work for more than one team or customer, each gets its own organisation, and you switch between them. Inside one organisation, [projects](/concepts/projects) divide the clusters and applications into rooms that a member can be limited to, while people, roles and billing stay organisation-wide. [How Ankra Works](/concepts/how-ankra-works) shows where the organisation sits in the overall model.

## Accessing Your Organisation

Open your current organisation directly from anywhere in Ankra.

1. Click your profile icon in the menu at the bottom left of the Ankra platform.
2. Select **Organisation**.
3. You land straight on your current organisation's overview - members, stats, roles, audit log, billing, and settings are in the sidebar.

## Switching Organisations

Switch between organisations to see the resources, stacks, and credentials for each one.

* In the profile menu, hover **Switch organisation** to see every organisation you belong to. Your current organisation is marked with a check - click any other one to switch to it. The list scrolls, and the search box at the top narrows it by name, slug or id as you type: just start typing anywhere in the submenu, then press **Enter** to switch to the first match or use the arrow keys to pick one.
* **All organisations** at the bottom of that submenu (it shows how many you belong to) opens the full list as a page, including pending invitations. The page has the same search, shows your current organisation first, pages through the rest twenty at a time, and has a switch button per organisation.
* You can also switch from the command palette with the **Switch Organisation** command.
* When you switch, your active session updates to reference that organisation. You'll see only the stacks, clusters, and credentials for the selected organisation.

## Inviting Users

Invite teammates to your organisation by email and assign their role.

* To add people, click **Add User** in the organisation view.
* Enter the user's email address to send an invitation.
* Choose the role the invitation grants. **Project only** is the role for someone who should reach only the [projects](/concepts/projects) you choose and nothing organisation-wide; give them a role in each of those projects afterwards.

## Managing Users & Roles

Ankra has five built-in roles - Owner, Admin, Operator, Member and Viewer - plus custom roles you define, and each can be assigned to the whole organisation, one cluster, a cluster group, or one project. See [Roles & Access](/guides/roles-and-access) for what each role grants and how to assign one.

* To remove a user, use the menu next to their name in the user list.

## Projects

A project is a room inside the organisation: every cluster and application belongs to exactly one, a member can be limited to one project, and cost is reported per project. Credentials, registries, backup vaults, object storage buckets, variables, notification routes and DNS zones are either in a project or organisation-wide. Every organisation has a **Default** project that holds everything you had before projects arrived, so nothing changes until you create a second project. The invoice, the members and the roles never split. [Projects](/concepts/projects) has the model, how your current project is chosen, project-only members, and how resources move between projects.

## Organisation Variables

Variables set on the organisation apply to every cluster and Stack in it, and a cluster or Stack variable of the same name overrides them. Where to set them and how precedence works is on the [Variables](/concepts/variables) page.

## Next

[Ankra Agent](/concepts/cluster-agent) explains how a cluster connects to your organisation.


# Projects
Source: https://docs.ankra.ai/concepts/projects

A project is a room inside your organisation. Clusters, applications and their cost live in one project each, a member can be limited to one project, and people, roles and billing stay organisation-wide.

A **project** is a room inside an [organisation](/concepts/organisations). The organisation keeps everything that is about people and money - members, roles, invitations, billing, single sign-on, the AI provider. A project owns a slice of the resource estate: its clusters, applications, environments, stack profiles, pipeline repositories, AI tickets, workspaces and automations, incidents, and the cost those produce.

Projects are on for every organisation on the new portal. Every organisation has a **Default** project, and every cluster, application, environment, stack profile, pipeline, AI ticket, workspace and automation you already had is in it. Nothing changes until someone creates a second project: the lists, links, tokens and scripts you use today keep working as they did. In an organisation whose portal is not yet the new one (the new portal carries `/next` in its address), projects are off: its Default project stays out of sight and everything works as it did before projects.

Projects exist for the organisation that holds several teams, products or stages that should not see or change each other's clusters, without splitting into several organisations and several invoices.

> [!NOTE]
>
> A project is not a cluster group. A [cluster group](/guides/roles-and-access#cluster-groups) is a named or label-selected set of clusters used as an assignment scope and nothing more. A project is a tenancy boundary: a resource belongs to exactly one, listings and cost are per project, members can be limited to one, and tokens can be pinned to one.

## What lives where

| Level | Holds |
| - | - |
| **Organisation** | Members and invitations, role definitions, billing (customer, plan, invoices, activation), single sign-on, the AI provider and AI configuration (MCP servers, custom tools, skills, playbooks), the image registry, support tickets, cluster groups |
| **Project** (always exactly one) | Clusters and everything reached through a cluster, applications, environments, stack profiles, pipeline repositories, AI tickets, workspaces and automations, incidents, cost budgets and autopilot defaults |
| **In a project, or organisation-wide** | Credentials, Helm and OCI registries, backup vaults and object storage buckets, organisation variables, notification routes, DNS zones |

The third row holds the **shared kinds**. Each credential, registry, vault, bucket, variable, notification route or DNS zone is either **in one project**, where only that project sees and uses it, or **organisation-wide** (no project), where every project sees and uses it. The ones you had before projects were released are organisation-wide. When you create a new one you choose **This project** or **Whole organisation**, and a move can change it later.

For a [notification route](/guides/notification-routing#routes-per-project), the choice decides what it hears, not only who sees it:

* **A route in a project** delivers only that project's notifications. A notification belongs to the project of the thing it is about: the cluster, application, pipeline run, repository, ticket, automation, workspace, incident or environment.
* **An organisation-wide route** delivers every project's notifications, plus the organisation's own, such as billing.
* **A route created without a choice** (before the form asked, or through the API without `project_id`) is in the project its creator was in at the time. Such a route now delivers only that project's notifications. If it should hear everything, move it to the whole organisation.

Reading an organisation-wide resource needs only the ordinary read permission. Changing, revealing or deleting one needs the matching permission held **on the organisation**: a role assigned in a project can create, change and delete that project's own credentials and variables, and can read the organisation-wide ones, but cannot change them. The refusal says so: `403 Organisation-wide resources require an organisation-level grant`.

## The Default project

Every organisation carries a reserved project whose short name is `default`. It is created with the organisation and cannot be deleted. Everything that existed before projects were released is in it, so nobody lost sight of anything on the day they arrived. You create further projects and move resources into them deliberately.

A project has a name (up to 128 characters), a short name or slug (`a-z`, `0-9` and hyphens, up to 63 characters, unique within the organisation, never shaped like a UUID) and an optional description. The short name cannot change once the project exists, because links, the CLI and kubeconfig files use it. Projects are managed under **Settings → People and access → Projects** in the console, or with [`ankra project`](/integrations/ankra-cli#projects).

## Your current project

Every request acts in one project. It is resolved once, when the request is authenticated, in this order:

1. **The token's pin.** A token minted in a project stays in it. See [Tokens and projects](#tokens-and-projects).
2. **The `X-Ankra-Project-Id` header** on a bearer-token request, naming a project of the current organisation by id. An id that is not a project of this organisation is refused with `403 Project not found in this organisation` - a `403` rather than a `404`, so the answer is the same whether the id belongs to another organisation or to nothing - and a pinned token that names a different project is refused outright.
3. **Your current project** in this organisation. Each organisation you belong to remembers its own current project, and switching it is server-side, like switching organisations: after a switch, the console, the API and the CLI read and write in the new project. Two things do not follow: a CLI where you ran `ankra project switch` keeps the project it saved on that machine until you switch there again or run `ankra org switch`, and an MCP token never follows a switch: one minted in a project stays in it, and an older unpinned one acts where [Tokens and projects](#tokens-and-projects) says.

Switch with the project switcher beside the organisation switcher in the console, with `ankra project switch <name>`, or with `POST /api/v1/org/projects/switch`. `GET /api/v1/org/projects/current` tells you where you are, and `GET /api/v1/org/projects` lists the projects you can reach, each with `is_current` and `is_default`.

> [!TIP]
>
> Older CLIs, Terraform and scripts that send no project header run in the current project of the token's owner, the same project that person sees in the console. There is no separate fallback for them: if they stop seeing a cluster, that person's current project is not the cluster's project, or an administrator has moved the cluster.

## Roles at project scope

A project is the fourth [assignment scope](/guides/roles-and-access#scopes), beside the organisation, a cluster and a cluster group. A role assigned in a project grants its resource permissions on every cluster the project holds now and later, and on the project's applications, environments, profiles, repositories and shared resources.

A project assignment can never confer the permissions that are about the organisation as a whole. Whatever role is assigned, these are dropped from a project grant: `organisation.*`, `members.*`, `billing.*`, `tokens.*`, `audit.*`, `projects.*`, `kube_access.manage`, `kube_access.policy`, `sops.manage`, `secrets.manage`, `git.manage`, `security.manage`, `ai.manage`, `workspaces.manage` and `profiles.share`. An `admin` assigned in one project is the resource half of admin inside that project, and cannot invite members, see invoices or create projects.

Creating, renaming, deleting and moving between projects needs `projects.manage`, which owners and admins hold at organisation scope. Listing projects needs `projects.read`, which every built-in role holds.

### Project-only members

A member's organisation role is a floor that reaches every project: a `viewer` on the organisation sees every project, read-only, whatever else is assigned. To give someone one project and nothing else, invite them with the membership role **Project only**. It holds nothing organisation-wide:

* The member reaches only the projects they are assigned a role in - `admin`, `operator`, `member` or `viewer` in that project - and sees nothing of the others.
* They can never hold an organisation-level permission: members, billing, other members' tokens, the audit log and organisation settings stay out of reach whatever role they are given in a project.
* When they sign in they land in their current project if they still reach it, otherwise in the first project they reach, oldest first.

Invitations and the **People** page offer **Project only** beside the organisation roles, and `ankra org invite <email> --role project --project <project> --project-role operator` invites one from the CLI (`--project-role` is `admin`, `operator`, `member` or `viewer`, `member` by default). Change a member to or from it on their row in People. A project-only member whose last project assignment is removed can still sign in, but every request, the console's own `/auth/whoami` included, answers `403 You are not assigned to any project in this organisation` until they are assigned again.

> [!WARNING]
>
> Ankra Cloud console access needs organisation-wide membership for now. A project-only member who opens the Ankra Cloud console is refused rather than shown the whole account. Everything in the Ankra platform itself works for them.

## Tokens and projects

A token is **pinned** to a project when it is minted with one: an MCP token or a [service token](/guides/service-tokens) created in the console is pinned to the project chosen in the create dialog, which defaults to the project you are working in; `ankra tokens create --project <name>` pins from the CLI; and any token minted by a pinned token is pinned to that project. A pinned token:

* reads and writes in that project only, however the request is phrased - `project_id=all` on a cost route and `X-Ankra-Project-Id` naming another project are both refused;
* cannot switch organisations either, as before;
* stops authenticating, with `403 The project this token is pinned to no longer exists`, if its project is deleted. Mint a new one in the project that replaced it.

Tokens minted before projects were released, and REST tokens minted without a project, are not pinned. A personal REST token follows its owner's current project and accepts `X-Ankra-Project-Id`; an unpinned service token acts in the project the header names and otherwise in the Default project. An MCP token minted while the organisation has projects is pinned to the project it was created in. One minted before that is not pinned and never follows a switch: for an organisation-wide member it acts in the Default project whatever its owner switches to, and a project-only member's acts in the oldest project they reach. A project-only member's REST token minted without a project is not pinned either, and reaches only the projects they do. See [API tokens](/reference/tokens).

## Moving resources between projects

A move takes one resource into another project of the organisation, or makes a shared kind organisation-wide. It is one transaction, audited as `move_to_project`. Move from the resource's settings page (**Move to another project**), with `ankra project move --kind <kind> --id <id> --to <project|org-wide>`, or with `POST /api/v1/org/projects/{project_id}/move`.

The kinds a move accepts are exactly these: `cluster`, `application`, `environment`, `stack_profile`, `pipeline_repository`, `ai_automation`, `ai_workspace`, `credential`, `registry`, `backup_vault`, `object_storage_bucket`, `organisation_variable`, `notification_route` and `dns_zone`. Only the shared kinds - the last seven - may be made organisation-wide.

The move carries the rows whose project is derived from the resource:

* a **cluster** takes its DNS zones, incidents, AI tickets and the notification routes pinned to it;
* an **application** takes its connected pipeline repositories;
* a **stack profile** takes its open drafts.

Three things refuse a move, each with a code the console, CLI and API all show:

| Code | Why |
| - | - |
| `same_project` | The resource is already in that project, or already organisation-wide |
| `operations_in_flight` | Operations are still running on the cluster. Wait for them to finish, then move it |
| `follows_cluster` | The DNS zone is bound to a cluster and follows that cluster's project. Move the cluster instead |

Cost already metered stays attributed to the project the cluster was in at the time; only hours from the move onwards count against the destination.

## Deleting a project

A project can be deleted only once nothing is in it: every cluster, application and other strictly scoped resource moved out, and no shared resource still pinned to it. The refusal lists what remains, per kind. Deleting a project retires the role assignments made at its scope, moves every member whose current project it was back to the Default project, removes its budgets and autopilot defaults, and stops the tokens pinned to it. The Default project cannot be deleted.

## Cost by project

Cost is metered per project, so a report for a month in which a cluster moved shows its cost split between the two projects. The Cost pages filter by project, and the fleet view shows **By project**: each project's run rate and cluster count, with an **unattributed** bucket for spend no project can claim, such as waste found on an organisation-wide credential rather than a cluster. The projects reconcile to the fleet total only together with that bucket.

Every cost route and tool takes `project_id`: a project id for one project, `all` for the whole organisation, and nothing for your current project. Cost budgets take a `project` scope, and the cost autopilot takes per-project defaults between the organisation's policy and a cluster's own override. From the CLI, the global `--project` flag reads another project, `--all-projects` on the fleet cost commands reads the whole organisation, and `ankra org usage --group-by project` gives the showback. [Cloud Cost](/platform/cloud-cost#by-project) has the detail.

Billing is never split. The invoice stays one per organisation. The **By project** view under Billing is a showback: each project's share of worker vCPU-hours over a window, for charging teams back internally. See [Billing](/platform/billing#showback-by-project).

## The API, Ankra's AI and the MCP server

* Bearer requests name a project for one call with `X-Ankra-Project-Id: <project-id>`, as described under [Your current project](#your-current-project).
* Portal links Ankra hands you - in notifications, AI answers and MCP results - carry `?project=<project-id>` beside `?org=`, so a link to a cluster in another project opens in that project and offers to switch you to it. See [Portal URLs](/platform/portal-urls).
* The [MCP server](/platform/mcp-server) and the AI Assistant act in the current project of the token or session. `list_projects` and `get_current_project` say where a session is, `move_cluster_to_project` and `move_application_to_project` are the moves, `get_organisation` reports the current project, and the cost tools take the same `project_id` as the routes. See [MCP Tools](/platform/mcp-tools#projects).

## Ankra Cloud

For organisations that also use [Ankra Cloud](/guides/ankra-cloud-clusters), the platform is the source of truth for projects, and Ankra Cloud does not scope anything by project yet. Projects are never created, renamed or deleted from the Cloud, and a project-only member is refused there for now. Servers the platform creates for a cluster carry the cluster's project in the `platform.ankra.io/project-id` label beside the cluster label.

## Related

* [Organisations](/concepts/organisations) - the level above a project.
* [Roles & Access](/guides/roles-and-access) - scopes, project-only members and what each role holds.
* [Service tokens](/guides/service-tokens) and [API tokens](/reference/tokens) - pinned credentials.
* [Ankra CLI](/integrations/ankra-cli#projects) - `ankra project`, `--project` and `ANKRA_PROJECT`.
* [Cloud Cost](/platform/cloud-cost#by-project) and [Billing](/platform/billing#showback-by-project) - cost by project and the showback.


# Stack Profiles, Reusable Kubernetes Stack Templates
Source: https://docs.ankra.ai/concepts/stack-profiles

A stack profile is a reusable, versioned template of a working Kubernetes stack. Set parameters per environment and deploy it to any cluster.

A stack profile is a reusable template captured from a real [stack](/concepts/stacks) of Helm add-ons and manifests. Build a stack once, save it as a profile, and instantiate it on any cluster with parameters filled in per environment. Profiles are versioned, so you can publish updates, diff versions, and see which deployments have drifted behind the latest.

> [!NOTE]
>
> A profile is a **template**, not a running deployment. Instantiating a profile produces a stack draft on a target cluster, which you then review and commit like any other stack change.

***

Watch a working OpenSearch stack reviewed, parameterised and published as a profile.

[Your stack works. Is it correct? Publishing an OpenSearch stack profile on Ankra](https://www.youtube-nocookie.com/embed/zjVtg_09qwU?rel=0)

## Why use profiles

* **Standardise** a golden stack (monitoring, ingress, security baseline) and reuse it across clusters.
* **Parameterise** the bits that differ per environment - domains, replica counts, sizes - instead of copy-pasting YAML.
* **Version** changes with a changelog and channels, and **diff** any two versions.
* **Track drift**: a profile shows how many instantiations are behind its latest version.

***

## Anatomy of a profile

| Concept | Description |
| - | - |
| **Version** | An immutable snapshot of the stack spec. Versions increment as you publish updates and carry a `channel` (e.g. `stable`) and an optional changelog. |
| **Parameters** | Typed inputs callers fill in at instantiation. Each parameter has a `type` (`string`, `number`, `boolean`, `enum`, or `secret`), and may be `required`, have a `default`, an `enum` list, or a validation `pattern`. |
| **Choices** | A parameter can offer `options`, and each option can `set` other parameters. One **Model size** choice of `8b` or `32b` then moves the model id, the context length and the volume size together, so the operator picks one thing instead of keeping four consistent. See [Choices that set other inputs](#choices-that-set-other-inputs). |
| **Protection** | The stack's backup block, carried as one parameter group. A profile captured from a protected stack keeps `enabled`, the schedule, the retention tiers and the selection; the **vault travels by name** and is resolved against the organisation the profile is launched into. See [Protection](#protection-backups-travel-with-the-profile). |
| **Visibility** | `organisation` (default) keeps the profile private to your org; `public` shares it more widely. Independently of visibility, a profile can be [shared with specific organisations](#share-with-specific-organisations). |
| **Category & tags** | Metadata for organising and searching profiles. |
| **Publisher** | The organisation that owns the profile. Publisher names, logos, and verified badges help you identify trusted profiles. Verified Ankra profiles appear first in profile results. |
| **Drafts** | An editable working copy used to build or edit a profile before publishing a version. |
| **Suggestions** | Proposed versions submitted by other organisations that can see the profile. The owner reviews the diff and approves (publishing it as the next version) or rejects. See [Suggestions](#suggestions-propose-and-review-changes). |

Secret-typed parameters and other sensitive values are redacted when a profile is captured, so credentials are never baked into a shared template.

***

## Create a profile

You can create a profile two ways:

> [card] From an existing stack
>
> Capture a profile directly from a stack already running on a cluster.
> Optionally include addon configurations. This is the fastest path - build
> and validate the stack first, then snapshot it.

> [card] Import
>
> Import a profile from exported IaC content, for sharing across
> organisations or storing in Git.

In the portal, **Save as Profile** starts with the stack's existing name and description. Categories combine common options with values your organisation already uses, and tags are suggested as you type.

Choose who can use the profile before saving:

* **This organisation** keeps it private to members of your organisation.
* **Public** makes it available to every organisation.
* **Specific organisations** keeps it private and grants access to the organisation slugs you enter.

Public and specific-organisation sharing require an organisation admin. Quick save publishes immediately. Save and customise opens the profile builder so you can review inputs before publishing.

```bash theme={null}
# Capture from a cluster's stack
POST /org/stack-profiles
{
  "name": "platform-baseline",
  "description": "Shared platform services",
  "category": "platform",
  "tags": ["baseline", "production"],
  "visibility": "organisation",
  "share_organisation_slugs": ["partner-org"],
  "source_cluster_id": "...",
  "stack_name": "platform",
  "include_addon_configurations": true
}
```

Organisation admins can upload a publisher logo under **Organisation Settings**. Profile cards fall back to the organisation's initials when no logo is configured.

### Build with drafts

For more control, work in a draft: create a draft (optionally seeded from a cluster's stack), edit its spec and parameters, validate it, then publish it as a new version.

**1. Create a draft**

`POST /org/stack-profiles/drafts` - optionally seeded from an existing profile or a source cluster stack.

**2. Edit and validate**

Update the draft's spec and parameters, then `POST /org/stack-profiles/drafts/{draft_id}/validate` to surface any issues before publishing.

**3. Publish a version**

`POST /org/stack-profiles/drafts/{draft_id}/publish` with a channel and changelog. This creates the profile (or a new version of it).

> [!NOTE]
>
> To update an existing profile, always author through a draft (**Edit Builder** in the portal, or `ankra stack-profiles drafts` from the CLI) rather than exporting the IaC, editing it, and re-importing. A draft seeded from the profile keeps the version's input annotations - titles, descriptions, enum choices, and [choices that set other inputs](#choices-that-set-other-inputs) - and publishes a new version of the same profile. Importing an edited export re-detects the inputs from the spec, drops those annotations, and creates a separate new profile.

***

## Instantiate a profile

Instantiating turns a profile into a stack on a target cluster:

**1. Choose a profile and version**

Pick the profile and, optionally, a specific version. When no version is
given, the profile's **current** version is used - the pinned version,
which can be older than latest after a rollback.

**2. Bind parameters**

Supply values for the profile's parameters. Required parameters must be set; others fall back to their defaults.

In the portal, **Use Profile** opens a page of its own rather than a dialog:
the destination and the inputs on the left, and a summary beside them that
stays in view while you scroll, ticking off the target cluster, the stack
name and the required inputs until **Create draft** is ready. The form opens
on the inputs the profile left blank and folds the ones that already carry a
default behind a disclosure, with a counter for the required inputs still
empty. Each field names the addon or manifest it
writes into, so a key declared on two components stays unambiguous. Secret
inputs can be generated, revealed, and copied, and any input changed away from
its default can be reset. An input whose name ends in `host`, `hostname`,
`fqdn`, or `domain` offers **Use cluster domain**, filling in that hostname
under the target cluster's delegated zone.

**3. Review the draft**

Instantiation creates a stack draft on the cluster (with the resolved addons and manifests). Review it.

**4. Commit**

Commit the draft to deploy, exactly like any other [stack](/concepts/stacks) change.

### Choices that set other inputs

Some inputs only make sense together. A chat profile that can run a small model on
one GPU or a large one on a bigger card has four inputs that must agree - the model
id, the context length, the GPU memory ceiling and the size of the model store - and
an operator asked for each one separately has to know all four answers.

A profile author can instead give one input **options**, and have each option **set**
the others:

```yaml theme={null}
- name: model_size
  title: Model size
  type: enum
  default: 8b
  options:
    - value: 8b
      title: Qwen3 8B on one L4 (24 GB)
      sets:
        model_id: Qwen/Qwen3-8B
        max_model_len: "16384"
        gpu_memory_utilization: "0.90"
        model_store_size: 60Gi
    - value: 32b
      title: Qwen3 32B on one L40S (48 GB)
      sets:
        model_id: Qwen/Qwen3-32B
        max_model_len: "28672"
        gpu_memory_utilization: "0.95"
        model_store_size: 120Gi
```

When the profile is used, the values resolve in one fixed order, on every surface:

```
a value you set  >  what the selected option sets  >  the parameter's own default
```

* **In the portal**, the choice renders as a card of options above the rest of the
  form, each naming how many inputs it answers. The inputs an option answers show
  the value it assigned, labelled with the choice that made it; type over one and
  it is marked *customised*, and **Reset** hands it back to the option. A required
  input an option answers counts as answered.
* **From the CLI**, `ankra stack-profiles get` prints a `Choices for model_size`
  block listing what every option sets, and
  `ankra stack-profiles apply <profile> --cluster <name> --set model_size=32b`
  deploys the whole set with no other bindings. A `--set` of your own on one of
  those inputs still wins over the option.
* **The platform resolves the choice server-side**, so the AI assistant, the MCP
  tools and Terraform get the same stack from the same selection, and the
  deployment's recorded parameters are the values that actually deployed.

A profile may declare any number of such inputs, each driving a different slice of
the form (model size, storage tier, ingress mode); when two set the same input, the
one declared later wins. An option can never set a **secret** input - a profile
never stores secret values - and cannot set another input that itself offers
options, so every resolution is a single readable pass. Options are authored on the
builder's **Inputs** tab; a choice-only input that no manifest references can be
added there directly, and mistakes that would be refused at publish (a value the
target input would reject, a default that names no option, an unknown target) are
shown inline while you edit.

### From the CLI

The [Ankra CLI](/integrations/ankra-cli) can instantiate a profile directly. Inspect a
profile's parameters first, then apply it to a cluster as a draft (or pass `--deploy`
to deploy in one step):

```bash theme={null}
# See the profile's versions and parameters
ankra stack-profiles get <profile-id>

# Create a draft on a cluster, binding parameters
ankra stack-profiles apply <profile-id> --cluster production \
  --set replicas=3 \
  --set-env api_token=MONITORING_API_TOKEN

# Or apply a specific version and deploy immediately
ankra stack-profiles apply <profile-id> --cluster production --version 3 --deploy
```

> [!NOTE]
>
> For **secret** parameters use `--set-file <name=path>` or `--set-env <name=ENV_VAR>` rather
> than `--set` so the value never appears in your shell history or process list.

***

## Protection: backups travel with the profile

A stack you protect with a backup policy keeps that policy when you save it as a profile, and every instance launched from the profile is protected too - so a fleet does not come up unprotected and need protecting again one cluster at a time.

What the profile carries is the **declaration**, never the rendered schedules. The Velero, CloudNativePG and Percona objects a backup policy materialises are bound to one cluster's vault, storage classes and object prefix; they are recomputed per cluster from the block and are deliberately left out of a capture.

The builder renders it as a single **Protection** section with three inputs:

| Input | What it decides |
| - | - |
| `ankra_protection_enabled` | Whether this launch takes scheduled restore points. |
| `ankra_protection_vault` | The **name** of the backup vault in the organisation being launched into. |
| `ankra_protection_schedule` | `hourly`, `daily`, `weekly`, or a five-field cron expression. |

Retention tiers and the database / volume selection are not launch inputs: they describe what a restore point of this stack *contains*, which is the profile author's decision, so they ride the block and the launcher does not retype them.

### The vault is resolved at launch

Vault ids differ per organisation, so protection travels by vault **name** and is resolved against the target organisation when the profile is instantiated:

* the profile names a vault the target organisation has, ready → that vault;
* the profile names none and the organisation has exactly one ready vault → that one;
* anything else - no ready vault, no vault by that name, several to choose from - the stack is created **without** a backup policy, the result carries a warning saying so, and a deploy is stopped with the draft kept rather than bringing a stateful stack up unprotected. Create and verify a vault, or bind `ankra_protection_vault` to the one this cluster should write to, then deploy the draft.

Bind `ankra_protection_vault` per cluster to send each instance's restore points to a different vault.

> [!NOTE]
>
> A **public** profile carries no vault name - naming one would disclose an organisation-internal resource and describe protection the installer cannot have. `enabled: true` with no vault is the publishable shape: the organisation launching it supplies its own vault. Making a profile public is refused while any of its versions still names one.

***

## Demo a profile before you deploy it

Instantiating a profile puts it on a real cluster. When you only want to see what it deploys - to review a new version, to check a public profile before adopting it, or to show someone the stack running - launch it as a **demo** instead.

A demo installs the profile into its own throwaway namespace on your organisation's staging cluster, quota-bounded and on a timer, and deletes itself when the timer runs out. Open the profile's **Demos** tab to launch one. See [Stack Profile Demos](/guides/stack-profile-demos).

***

## Share with specific organisations

Making a profile `public` exposes it to everyone. When you want to share a golden stack with one partner, customer, or sibling organisation - and nobody else - share it directly instead:

* Shared organisations can **list, view, diff, export, and instantiate** every version of the profile. They cannot edit, delete, or re-share it.
* The profile keeps its `organisation` visibility; sharing is an explicit per-organisation grant.
* The target organisation is identified by its **organisation slug** (found under organisation settings). Ask the other organisation for theirs.
* Only **organisation admins** can grant or revoke shares, and a grant re-runs the plaintext-secret scan over every published version - a profile that still carries plaintext secrets cannot be shared. Grants and revokes are recorded in the audit log.
* Revoking a share hides the profile from the other organisation again. Stacks they already deployed from it keep running - they just stop seeing profile updates.

In the portal, open a profile you own and use **Share**. Via the API:

```bash theme={null}
# Grant an organisation access
POST /org/stack-profiles/{profile_id}/shares
{ "organisation_slug": "acme-corp" }

# List grants / revoke one
GET    /org/stack-profiles/{profile_id}/shares
DELETE /org/stack-profiles/{profile_id}/shares/{share_id}
```

Profiles shared **with** your organisation show up in your profile list marked "Shared with you".

***

## Suggestions: propose and review changes

Sharing is read-only, but improvements can still flow back. Any organisation that can see a profile - shared or public - can open it in the builder with **Suggest changes**, edit a draft of it, and submit the result as a **suggestion**. The owning organisation reviews the diff on the profile's **Suggestions** tab and either approves it - publishing the proposed contents as the profile's next version - or rejects it with a note. The proposer can withdraw an open suggestion. The profile stays owner-only throughout: a suggestion changes nothing until an owner approves it.

Suggestions are frozen at submit and pass the same plaintext-secret and unbound-placeholder gates as publishing, at submit and again at approve, so no secret value ever travels through one.

See [Stack Profile Suggestions](/guides/stack-profile-suggestions) for both sides of the flow, end to end.

***

## Versioning, diffing, and updates

* **Save a new version** from an updated source stack, or by publishing an edited draft.
* **Diff** any two versions to see what changed: `GET /org/stack-profiles/{profile_id}/diff?from_version=1&to_version=2`.
* **Diff a draft** before publishing it, against the version it was opened from: `GET /org/stack-profiles/drafts/{draft_id}/diff`. The draft is redacted first, so the comparison shows what publishing would actually store rather than your working copy. A draft that will create a brand-new profile has no base, so everything in it reads as added.
* **Update tracking**: a profile reports `outdated_instantiation_count` and `has_update_available` so you can find the deployments that are behind.
* **Update a deployment in place**: updating a tracked deployment replaces the contents of the stack it already runs with the chosen version - the same stack, so Kubernetes performs a rolling update of the workloads and nothing is deployed twice - and records the deployment at the new version, so the counters above follow. The non-secret inputs it was last applied with are carried forward; secret inputs are asked for again. Do **not** instantiate the profile a second time to update a deployment: that produces a *new* stack beside the running one, renamed around the name collision.
* **Export IaC** for a version to store the template in Git or move it between organisations.

### Deprecate a version

A published version cannot be deleted - deployments record which version they run, and
that history has to stay readable - but it can be **withdrawn**. When a version turns out to
be incompatible with what clusters run today, to carry a critical bug, or to ship a CVE, the
profile's owner deprecates it with a reason and, optionally, a note and the advisories it
relates to:

```bash theme={null}
ankra stack-profiles deprecate payments 3 --reason cve \
  --note "Fixed in v4." --reference CVE-2026-12345
ankra stack-profiles undeprecate payments 3
```

The same actions sit on each version in the profile's **History** tab. From then on:

* Nothing deploys the version. The launch page refuses it, and so do `ankra stack-profiles
  apply --version 3`, `rollout`, a demo launch and an in-place update onto it - every lane
  answers `409` with the reason and the note (`Version 3 of this profile is deprecated (CVE):
  Fixed in v4. Deploy another version.`), so the person who tried learns what to do instead.
* It cannot be made the current version, and the **current version cannot be deprecated**:
  every launch that names no version resolves to it, so withdrawing it would leave the profile
  with nothing to deploy by default. Make another version current first.
* Deployments still running it are flagged: the Deployments tab marks each row **deprecated**,
  `ankra stack-profiles deployments` counts them, and the profile detail reports
  `update_status.deprecated_instantiation_count`, so a fleet sitting on a withdrawn version is
  visible from the profile rather than discovered cluster by cluster.

The notice travels with the version on the API as `deprecation` (`reason`, `note`,
`references`, `deprecated_at`, `deprecated_by_user_id`; `null` while the version is
deployable), written by `POST /org/stack-profiles/{profile_id}/versions/{version}/deprecation`
and cleared by `DELETE` on the same path. Removing a deprecation restores the version exactly
as it was; deployments made before the notice are never touched either way.

***

## See where a profile is deployed

The profile detail page has a **Deployments** tab listing every stack your organisation
has created from the profile: the cluster, the stack (a link to the running stack, or to
the still-open draft when it was never committed), its current state, the profile version
it runs, the non-secret parameter values it was instantiated with, and when. Rows running
a version older than the profile's current version carry an **Update** action that opens
the update flow pre-filled with the values used last time.

A stack that is deleted from its cluster drops off the list, as does a draft that is
discarded, so the tab always reflects what is actually running. The same rows are served by
`GET /org/stack-profiles/{profile_id}/instantiations`.

### The stack a profile was captured from is not a deployment of it

> [!WARNING]
>
> Saving a profile **from** a running stack - or publishing a new version from it - snapshots
> that stack's contents. It does not register the stack as a deployment of the profile. The
> Deployments tab is therefore empty right after a capture, the source stack never reports
> itself as behind when you publish a new version, and it cannot be updated through the
> profile. Only stacks created by instantiating the profile are tracked until you adopt the
> source stack.

This matters most for the platform layer - a CNI, ingress or storage stack - where deleting
and recreating the stack to get a tracked deployment is not an option.

Adopt the stack to record it as a deployment of the profile without touching it:

```bash theme={null}
ankra stack-profiles adopt platform-baseline --stack platform --cluster my-cluster --version 2
```

Nothing is written to the cluster: only the deployment record appears, after which the
Deployments tab lists the stack and `ankra stack-profiles rollout` can update it in place.
Adopt reports how the live stack differs from the version you name. Read that report before
rolling out: a rollout replaces the stack with what the version lists, so a member that is
only on the cluster is removed by it.

To move such a stack onto a profile version without tracking it, export the version and
apply it to the cluster under the stack's own name:

```bash theme={null}
# Export the version you want the cluster to run
ankra stack-profiles export-iac platform-baseline --version 2 --output platform.yaml
```

Then edit `platform.yaml` before applying it:

* set `metadata.name` to the **target cluster's** name - the export carries the profile's
  name there, and applying it unchanged imports a new cluster under that name;
* set the stack's `name` to the stack already running on that cluster.

```bash theme={null}
ankra cluster apply -f platform.yaml
```

That updates the named stack in place, exactly as editing the stack would. Other stacks on
the cluster are left alone, but any add-on or manifest of *that* stack the document does not
list is removed - so compare the version against what the stack runs first if it has drifted
from the profile. The Deployments tab still will not list the stack afterwards: applying IaC
does not create the tracking record. Adopt the stack, as above, when the profile should track it.

***

## API

All endpoints are under `/org/stack-profiles` and require authentication; write operations require a CSRF header for browser-originated requests.

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/org/stack-profiles` | List profiles (paginated) |
| `POST` | `/org/stack-profiles` | Create a profile from a cluster's stack, with optional visibility and organisation shares |
| `GET` | `/org/stack-profiles/metadata-suggestions` | List categories and tags already used by your organisation |
| `POST` | `/org/stack-profiles/import` | Import a profile from IaC content |
| `GET` | `/org/stack-profiles/{profile_id}` | Profile detail, versions, and update status |
| `PATCH` | `/org/stack-profiles/{profile_id}` | Update metadata (name, description, category, tags, visibility; making a profile public requires the org admin role) |
| `DELETE` | `/org/stack-profiles/{profile_id}` | Delete a profile |
| `POST` | `/org/stack-profiles/{profile_id}/current-version` | Pin the current version (roll back / roll forward) |
| `POST` | `/org/stack-profiles/{profile_id}/versions` | Save a new version from a source stack |
| `GET` | `/org/stack-profiles/{profile_id}/versions/{version}` | Get a version's spec and parameters |
| `GET` | `/org/stack-profiles/{profile_id}/versions/{version}/iac-export` | Export a version as IaC |
| `GET` | `/org/stack-profiles/{profile_id}/diff` | Diff two versions |
| `GET` | `/org/stack-profiles/{profile_id}/instantiations` | List the live deployments of the profile (cluster, stack, state, version, parameters) |
| `GET` | `/org/stack-profiles/{profile_id}/shares` | List the organisations a profile is shared with |
| `POST` | `/org/stack-profiles/{profile_id}/shares` | Share the profile with an organisation by slug (org admin role required) |
| `DELETE` | `/org/stack-profiles/{profile_id}/shares/{share_id}` | Revoke a share (org admin role required) |
| `GET`/`POST` | `/org/stack-profiles/drafts` | List or create drafts |
| `GET`/`POST`/`DELETE` | `/org/stack-profiles/drafts/{draft_id}` | Get, update, or delete a draft |
| `POST` | `/org/stack-profiles/drafts/{draft_id}/validate` | Validate a draft |
| `POST` | `/org/stack-profiles/drafts/{draft_id}/publish` | Publish a draft as a profile version |
| `POST` | `/org/stack-profiles/drafts/{draft_id}/rebase` | Move a stale draft onto the profile's latest version (`reseed` replaces its contents; `acknowledge` keeps them) |
| `POST` | `/org/stack-profiles/drafts/{draft_id}/submit-suggestion` | Submit a draft as a suggestion to another organisation's profile |
| `GET` | `/org/stack-profiles/{profile_id}/suggestions` | List suggestions (owners see all; others see their own organisation's) |
| `GET` | `/org/stack-profiles/{profile_id}/suggestions/{suggestion_id}` | One suggestion with its frozen spec and diffs |
| `POST` | `/org/stack-profiles/{profile_id}/suggestions/{suggestion_id}/approve` | Approve: publish the suggestion as the profile's next version (owner only) |
| `POST` | `/org/stack-profiles/{profile_id}/suggestions/{suggestion_id}/reject` | Reject with an optional note (owner only) |
| `POST` | `/org/stack-profiles/{profile_id}/suggestions/{suggestion_id}/withdraw` | Withdraw an open suggestion (proposer only) |

See [Stacks](/concepts/stacks) for the deploy/commit flow and the [API Reference](/api-reference/introduction) for full schemas.


# Stacks
Source: https://docs.ankra.ai/concepts/stacks

A Stack is what a cluster should run - Helm add-ons and your own Kubernetes manifests, deployed together in dependency order.

A cluster rarely needs just one chart. Monitoring needs a namespace, Prometheus, Grafana and an ingress rule, and they have to go on in the right order. A **Stack** is how you describe that set once in Ankra and deploy it as one unit, to one cluster or to many. [How Ankra Works](/concepts/how-ankra-works) shows where Stacks sit in the overall model.

## What a Stack contains

* **[Add-ons](/concepts/addons)** - Helm charts, each with a chart version and its values.
* **[Manifests](#manifests)** - your own Kubernetes YAML: namespaces, Secrets, CRDs, RBAC, custom resources.
* **[Variables](/concepts/variables)** - Stack-level values referenced as `${{ ankra.name }}`. A Stack variable overrides a cluster or organisation variable of the same name.
* **Dependency edges** - which component has to succeed before another one starts.

A cluster usually has several Stacks, one concern each, rather than one Stack that holds everything.

## Deployment order

Components that do not depend on anything deploy in parallel. A component with parents waits until they have succeeded, so a namespace manifest goes before the add-ons and resources that live in it, and an operator goes before the custom resources it reconciles.

```mermaid theme={null}
flowchart LR
    Namespace[Namespace manifest] --> ConfigMap[ConfigMap manifest]
    Namespace --> App[App add-on]
    ConfigMap --> App
```

Here the namespace deploys first, then the ConfigMap, then the add-on that reads both.

## Manifests

A manifest is a YAML document of Kubernetes resources, written by you, that Ankra applies as part of a Stack. Use one for anything a Helm chart does not create for you: the namespace a chart installs into, a Secret it reads, the RBAC your team needs, or the custom resources an operator add-on reconciles. Manifests always live inside a Stack, so they deploy in order with the add-ons that need them.

A single manifest can hold several resources separated by `---`:

```yaml theme={null}
apiVersion: v1
kind: Namespace
metadata:
  name: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: monitoring
  name: monitoring-reader
rules:
  - apiGroups: [""]
    resources: ["pods", "services"]
    verbs: ["get", "list"]
```

**Secrets in manifests.** If a manifest carries a password or key and the cluster is connected to Git, list the key names under **Encrypted Keys (SOPS)** in the manifest editor, for example `password` or `stringData.admin-user`. Ankra encrypts those values with SOPS before it writes the manifest to Git and decrypts them when it deploys. SOPS needs a one-time setup for the organisation - see [SOPS](/guides/sops).

**Operational notes.** Every manifest and add-on has an **AGENTS.md** tab where you and Ankra's AI record what matters when changing it, such as upgrade order or fields that must stay pinned. Editing it never triggers a redeploy. See [Teach Your Agents with AGENTS.md](/platform/agents-md).

## Building a Stack

In the portal, open the cluster's **Stacks** and click **+ Create**. In the Stack Builder, **Add Add-on** adds a Helm chart and **Add Manifest** adds your own YAML. Drag from one component to another to add a dependency edge, and click a component to edit its values or YAML. The **Variables** tab holds the Stack's own variables. **Create Stack** saves the Stack and deploys it.

A Stack that has not been deployed yet shows a **Draft** badge in the list, or **AI draft** when Ankra's AI proposed it.

You can also describe what you need to Ankra's AI (`⌘J`) and let it propose the Stack, for example:

> I need a monitoring stack with Prometheus, Grafana and alerting for this cluster.

In chat every change needs your confirmation. The same Stack tools are available to MCP clients with the `mcp:write` scope - see the [MCP Tool Reference](/platform/mcp-tools#stacks).

## What a Stack Is Running

The Stack page shows what a Stack declares: its add-ons and manifests and the deployments that applied them. The **Runtime** tab shows what those components actually put on the cluster right now, in four panels: **Endpoints** (the hosts and paths its Ingresses publish), **Pods**, **Services** and **Events**.

Runtime scopes by ownership, not by namespace. Several Stacks can share a namespace and one Stack can span several, so Ankra follows the objects it recorded for the Stack and their owner references down to ReplicaSets, Jobs and Pods. When the cluster cannot answer a listing, the tab says so rather than showing an empty list. It reads the cluster only while it is open.

## Stacks in Git

When the cluster has a repository connected, each Stack is written to its own directory, by default `clusters/<cluster-name>-<short-id>/stacks/<stack>/`, with one `values.yaml` per add-on and one YAML file per manifest. Commits to those files are applied to the cluster. See [GitOps](/concepts/gitops).

## Reusing a Stack

* **Clone to Cluster** in a Stack's menu copies it to another cluster, including one in another organisation. Encrypted values are not copied. See [Clone Stacks](/guides/clone-stack).
* **Save as Profile** turns a deployed Stack into a versioned, parameterised template you can deploy on any cluster. See [Stack Profiles](/concepts/stack-profiles).

## Next

[Add-ons](/concepts/addons) explains how a Helm chart becomes an add-on and how its values are managed.


# Variables
Source: https://docs.ankra.ai/concepts/variables

Define reusable variables at organisation, cluster, and stack levels for flexible configuration management.

The same Stack often needs a different domain, replica count or bucket name on each cluster. Variables let you write `${{ ankra.name }}` once in your values and manifests and set the actual value on the organisation, a cluster or a Stack. Ankra fills it in when it deploys. [How Ankra Works](/concepts/how-ankra-works) shows where variables sit in the overall model.

## Overview

A variable can be set at three levels, and **the more specific one wins: Stack > cluster > organisation**.

```mermaid theme={null}
flowchart TD
    Org[Organisation variables] --> Cluster[Cluster variables]
    Cluster --> Stack[Stack variables]
    Stack --> Final[Value used at deploy]
```

1. **Stack variables** - set on one Stack. They win over everything else.
2. **Cluster variables** - set on one cluster. They win over organisation variables.
3. **Organisation variables** - set once for every cluster and Stack in the organisation.

So a Stack variable named `domain_name` replaces a cluster or organisation variable of the same name for that Stack only.

***

## Variable Syntax

Reference variables in your stacks using the following syntax:

```yaml theme={null}
${{ ankra.variable_name }}
```

**Examples:**

```yaml theme={null}
# In a manifest
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: default
data:
  domain: ${{ ankra.domain_name }}
  api_url: https://${{ ankra.domain_name }}/api
```

```yaml theme={null}
# In Helm values
ingress:
  enabled: true
  hosts:
    - host: ${{ ankra.domain_name }}
```

***

## Organisation Variables

Organisation variables apply to all clusters and stacks within your organisation. Use them for values that are consistent across your entire infrastructure.

### Creating Organisation Variables

**1. Navigate to Variables**

Go to **Organisation Settings** → **Variables**.

**2. Add a Variable**

Click **Add Variable** to open the creation form.

**3. Enter Variable Details**

Fill in the required fields:

* **Variable Name**: Must start with a letter, containing only letters, numbers, and underscores (e.g., `domain_name`, `api_key`)
* **Value**: The variable's value
* **Description** (optional): A brief description for documentation
* **Secret**: Check this box to mask the value in the UI

**4. Create**

Click **Create Variable** to save.

### Common Organisation Variables

| Variable Name | Example Value | Use Case |
| - | - | - |
| `domain_name` | `example.com` | Base domain for all services |
| `registry_url` | `ghcr.io/myorg` | Container registry URL |
| `environment` | `production` | Environment identifier |
| `alert_email` | `alerts@example.com` | Notification email address |
| `log_level` | `info` | Default logging level |

***

## Cluster Variables

Cluster variables apply to all stacks deployed to a specific cluster. Use them for cluster-specific configurations that differ between environments.

### Creating Cluster Variables

**1. Navigate to Cluster Settings**

Go to your cluster → **Settings** → **Variables**.

**2. Add a Variable**

Click **Add Variable** to open the creation form.

**3. Enter Variable Details**

Fill in the required fields:

* **Variable Name**: Must start with a letter, containing only letters, numbers, and underscores
* **Value**: The variable's value
* **Description** (optional): A brief description
* **Secret**: Check this box to mask the value in the UI

**4. Create**

Click **Create Variable** to save.

### Common Cluster Variables

| Variable Name | Example Value | Use Case |
| - | - | - |
| `cluster_domain` | `prod.example.com` | Override the [built-in cluster domain](#built-in-variables) for this cluster |
| `storage_class` | `gp3` | Default storage class |
| `node_selector` | `app=production` | Node selector labels |
| `replica_count` | `3` | Default replica count |
| `resource_quota` | `high` | Resource allocation tier |

***

## Stack Variables

Stack variables are specific to a single stack and have the highest precedence. Use them for stack-specific configurations that should override cluster and organisation variables.

### Creating Stack Variables

**1. Open the Stack Builder**

Navigate to your cluster → **Stacks** and open an existing stack or create a new one.

**2. Go to Variables Tab**

Click the **Variables** tab in the Stack Builder.

**3. Add a Variable**

Click **Add Variable** to create a new variable entry.

**4. Enter Variable Details**

Fill in the fields:

* **Variable Name**: Must start with a letter, containing only letters, numbers, and underscores
* **Value**: The variable's value

**5. Save**

Click **Save Variables** to persist the changes.

> [!TIP]
>
> Stack variables are saved as part of the stack configuration. When you deploy the stack to GitOps, the variables are resolved before manifests are written.

### Common Stack Variables

| Variable Name | Example Value | Use Case |
| - | - | - |
| `app_version` | `v2.1.0` | Application version tag |
| `replicas` | `5` | Stack-specific replica count |
| `feature_flag` | `enabled` | Feature toggles |
| `log_level` | `debug` | Stack-specific logging |
| `custom_config` | `{"key": "value"}` | JSON configuration |

### When to Use Stack Variables

Use stack variables when:

* A specific stack needs values that differ from cluster defaults
* You want to override cluster or organisation variables for one stack
* You're testing different configurations on the same cluster
* You need stack-specific feature flags or version tags

***

## Secret Variables

Mark variables as secrets when they contain sensitive values like API keys, passwords, or tokens.

> [!WARNING]
>
> Secret variables are masked in the UI but are still stored as-is on the server. For encrypted storage, use [SOPS encryption](/guides/sops) instead.

### Secret Variable Features

* **Masked Display**: Values show as `••••••••` in the UI
* **Reveal Option**: Click the eye icon to temporarily reveal the value
* **Copy Protection**: Values can still be copied for use in configurations

### When to Use Secrets vs SOPS

| Feature | Secret Variables | SOPS Encryption |
| - | - | - |
| **UI Masking** | Yes | N/A |
| **Git Storage** | Plaintext | Encrypted |
| **Runtime Decryption** | No | Yes |
| **Best For** | UI-only protection | Values sealed in your Git repository |

> [!TIP]
>
> Use secret variables for convenience in the UI. Use SOPS when you need values encrypted in your Git repository.

***

## Using Variables in Stacks

### In Manifests

Reference variables anywhere in your Kubernetes manifests:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: ${{ ankra.replica_count }}
  template:
    spec:
      containers:
        - name: app
          image: ${{ ankra.registry_url }}/myapp:latest
          env:
            - name: DOMAIN
              value: ${{ ankra.domain_name }}
```

### In Add-on Values

Use variables in Helm chart values:

```yaml theme={null}
# Grafana add-on values
grafana:
  adminPassword: ${{ ankra.grafana_password }}
  ingress:
    enabled: true
    hosts:
      - grafana.${{ ankra.cluster_domain }}
```

### Built-in Variables

Two names are reserved and resolve from platform state without any variable being created:

| Variable | Resolves to |
| - | - |
| `${{ ankra.cluster_domain }}` | The cluster's public domain: by default its generated Ankra domain (`<cluster-id>.<org-id>.<ankra-domain>`), or the organisation's Preview domain when a custom DNS zone you declared covers it. See [Cluster domains](/platform/organisation-settings#cluster-domains). `ankra cluster domain <cluster>` shows the value. |
| `${{ ankra.stack_name }}` | The name the stack carries on its cluster, so a profile deployed twice renders distinct namespaces and hostnames. |

A stack, cluster, or organisation variable of the same name overrides the built-in. A cluster with no public domain at all leaves the reference literal, which an Ingress host rejects loudly rather than resolving to nothing.

### Variable Resolution

When you deploy a stack, Ankra resolves variables in this order:

1. Check for a matching stack variable (highest priority)
2. If not found, check for a matching cluster variable
3. If not found, check for a matching organisation variable
4. If still not found, the literal `${{ ankra.variable_name }}` is left in place (which will likely cause deployment errors)

> [!NOTE]
>
> This precedence allows you to define sensible defaults at the organisation level, environment-specific overrides at the cluster level, and stack-specific customizations when needed.

***

## Managing Variables

### Copying Variable Syntax

Click the **Copy** icon next to any variable to copy its full syntax:

```
${{ ankra.variable_name }}
```

This copies the ready-to-use syntax for pasting into your manifests.

### Deleting Variables

> [!WARNING]
>
> Deleting a variable that is in use by stacks will cause deployment failures. Review stack usage before deleting.

1. Click the **Delete** (trash) icon next to the variable
2. The variable is immediately removed

### Variable Naming Rules

Variable names must follow these rules:

* Start with a letter (a-z, A-Z)
* Contain only letters, numbers, and underscores
* Be unique within their scope (organisation or cluster)

**Valid names:** `domain_name`, `API_KEY`, `replica_count_v2`

**Invalid names:** `123_name`, `my-variable`, `name with spaces`

***

## Managing variables via API and CLI

Organisation and cluster variables have full CRUD over the API and the [Ankra CLI](/integrations/ankra-cli), so you can manage them from scripts and pipelines, not just the UI. (Stack variables are managed as part of the stack via the CLI's stack commands.)

### CLI

```bash theme={null}
# Organisation scope - available to every cluster
ankra org variables set DB_HOST db.example.com --description "Primary DB"
ankra org variables list

# Cluster scope - shadows org variables on that cluster
ankra cluster variables set DB_HOST db.prod.example.com --cluster prod
```

`set` is an upsert, and values can be read from stdin with `-` so secrets can be piped in from a vault or password manager. See the [CLI reference](/integrations/ankra-cli) for the full command set.

### REST API

Both scopes expose the same list/create/update/delete shape under `/api/v1/org/variables` (organisation) and `/api/v1/org/clusters/imported/{cluster_id}/variables` (cluster), bearer-token authenticated. See the [API Reference](/api-reference/introduction) for endpoints and schemas.

***

## AI Prompts

Press `⌘+J` to open the AI Assistant and use these prompts:

> [accordion] Create Variables for a Stack
>
> ```
> I need to deploy the same stack to dev and prod clusters with
> different domain names. Help me set up variables.
> ```

> [accordion] Migrate Hardcoded Values
>
> ```
> Review my stack and suggest which values should be
> converted to variables.
> ```

***

## Related

> [card] [Stacks](/concepts/stacks)
>
> Build stacks that use variables.

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt sensitive values in Git.

> [card] [Organisation Settings](/platform/organisation-settings)
>
> Configure organisation-level settings.

> [card] [Cluster Settings](/platform/cluster-settings)
>
> Configure cluster-level settings and variables.


# Get started with Ankra CI
Source: https://docs.ankra.ai/get-started/ankra-ci

Move a repository's CI to Ankra Pipelines in about 20 minutes: choose the cluster your builds run on, connect the repository, commit .ankra/pipeline.yaml and get a green Ankra pipeline check on your next pull request.

Ankra CI - Ankra Pipelines in the product - runs your repository's CI inside a Kubernetes cluster you already run through Ankra. You describe the pipeline in one file, `.ankra/pipeline.yaml`. Every push and pull request then runs it as hardened Kubernetes Jobs on your own nodes. The result lands on the commit as an `Ankra pipeline` check, next to the logs, test results and scan findings in Ankra.

This tutorial takes one repository from nothing to a green check on a pull request. Every step ends with something you can see, so you know it worked before you move on.

## Why teams move to Ankra CI

| | GitHub Actions, GitLab CI | Ankra CI |
| - | - | - |
| **Where jobs run** | Hosted runners billed per minute, or a self-hosted runner fleet you patch and scale | Pods on a cluster you already operate, under the quotas and node groups you set |
| **Secrets** | Copied into each repository's CI settings, readable by any workflow that names them | References to your Ankra variables and registries, delivered to one step as a file and never written to a log |
| **What a pull request can change** | Anything in the workflow file, including which secrets it reads | The steps and scripts. Secrets, network access, compute and caches stay as an administrator approved them |
| **Image security** | Push first, scan afterwards, if a scan step exists | `build`, `scan`, `gate`, `publish`: nothing reaches your registry until the gate has judged the exact digest |
| **Where the evidence lives** | The CI provider | Ankra, with the same status on GitHub, GitLab or Bitbucket Cloud |

## Choose your starting point

> [card] [I already have GitHub Actions or GitLab CI](/guides/migrate-from-github-actions)
>
> Ankra converts your existing workflow into `.ankra/pipeline.yaml` and opens a pull request. Then come back for steps 1, 2, 6 and 7.

> [card] [I am deploying a new app with Ankra](/guides/deliver-your-app)
>
> The setup pull request Ankra opens for a new application already commits a pipeline that tests, builds, scans and publishes. Steps 1 and 2 are all you need here. Step 7 is done for you when you create the application from the portal and hold pipeline management access.

> [card] [I want to start from a blank file](#1-choose-the-cluster-your-builds-run-on)
>
> Follow this page from top to bottom. It is the best way to learn how a pipeline fits together.

## Before you start

* **An Ankra organisation where you are an administrator.** Choosing the CI cluster and approving a pipeline are administrator actions. Anyone with pipeline access can do the rest.
* **A cluster connected to Ankra** with a healthy agent and some spare capacity. Any cluster works, and it does not have to be dedicated to CI: steps run in their own `ankra-ci` namespace, in a worker pool kept apart from the agent's deploy work. Many teams start on their staging cluster and move CI to its own cluster later.
* **The repository connected to Ankra** through the [Ankra GitHub App](/integrations/github), [GitLab](/integrations/gitlab) or [Bitbucket Cloud](/integrations/bitbucket-cloud). On GitHub, the App needs the **Checks: write** permission to post the `Ankra pipeline` check.
* **The Ankra CLI**, logged in to the right organisation:

```bash theme={null}
brew install ankraio/tap/ankra
ankra login
ankra org switch <your-organisation>
```

Other install methods are on the [CLI page](/integrations/ankra-cli).

## 1. Choose the cluster your builds run on

Pipelines run on one cluster per organisation, the **pipeline cluster**. Until you choose one, a push has nowhere to run, and the commit gets a failing check that asks you to choose a cluster.

> [tab] CLI
>
> ```bash theme={null}
> ankra org ci-settings set --cluster <cluster-name>
> ankra org ci-settings get
> ```

> [tab] Portal
>
> Open **Settings → Pipelines**. Under **Pipeline cluster**, pick the cluster in **Cluster** and click **Save**.

**You should see** your cluster named as the pipeline cluster in `ankra org ci-settings get`, or in the portal.

## 2. Turn on pipeline workers on that cluster

The Ankra agent on every cluster starts with **zero** pipeline workers, which means pipelines are switched off there. Give it some. Each worker runs one pipeline step at a time, separately from the agent's deploy and read work, so a busy pipeline never delays a deploy.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster agent ci set --workers 2 --cluster <cluster-name>
> ankra cluster agent ci get --cluster <cluster-name>
> ```

> [tab] Portal
>
> In **Settings → Pipelines**, under **Workers and step placement**, set **Pipeline-step workers** to `2` and click **Save**.

Ankra applies the setting through the agent's own release. A recent agent picks up the new count straight away, and an older one restarts to pick it up. Do not `helm upgrade` the agent yourself to change it, because Ankra re-renders that release and would overwrite your value.

**You should see** the new worker count when you read the settings back. Start with 2 and raise it once you see steps waiting: the run page says when a step is waiting for a free worker.

## 3. Connect the repository

> [tab] CLI
>
> Find the name of the organisation's Git credential, then connect the repository with it:
>
> ```bash theme={null}
> ankra credentials list
> ankra pipeline repositories connect --provider github --owner my-org --name my-repo --credential <git-credential-name>
> ```
>
> Use `--provider gitlab` or `--provider bitbucket` for those hosts, and add `--default-branch <branch>` when it is not `main`.
>
> The output starts with `Connected my-org/my-repo as repository <repository-id>`. Keep that id - the commands below take it as `--repository <repository-id>`, and `ankra pipeline repositories list` shows it again later.

> [tab] New portal (application)
>
> When the repository already backs an [Ankra application](/concepts/applications), open the application in the new Ankra portal (`/next` on your portal's address, for example `https://platform.ankra.app/next/applications`), then **Technical details → Pipelines**. Under **Connect this repository to pipelines**, pick the **Source connection**, click **Review pipeline connection**, then **Confirm pipeline connection**.
>
> For an application, use `--application <application-name>` in the commands below instead of `--repository`. Inside a checkout of the application's repository you can leave it out: the CLI works it out from your `origin` remote and says which application it picked.

The connect output's second line reads `Definition: absent` until a pipeline file is on the default branch. That is expected - step 5 stores one.

**You should see** the repository in `ankra pipeline repositories list`, and under **Settings → Pipelines** in the portal.

## 4. Add `.ankra/pipeline.yaml`

On a new branch, create `.ankra/pipeline.yaml`. This first pipeline checks out the commit and runs your tests on every push to `main`, on every pull request into it, and whenever you start it by hand. Pick your toolchain:

> [tab] Node.js (npm)
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "node:24-alpine"
>     needs: ["checkout"]
>     env:
>       npm_config_cache: "/workspace/.ankra-node-cache/npm"
>     run: |
>       npm ci
>       npm test
> ```

> [tab] Python (pip)
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "python:3.13-slim"
>     needs: ["checkout"]
>     env:
>       PIP_CACHE_DIR: "/workspace/.ankra-python-cache/pip"
>     run: |
>       python -m venv /workspace/.ankra-venv
>       . /workspace/.ankra-venv/bin/activate
>       pip install -r requirements.txt
>       pytest
> ```

> [tab] Go
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "golang:1.26"
>     needs: ["checkout"]
>     env:
>       GOPATH: "/workspace/.ankra-go"
>       GOCACHE: "/workspace/.ankra-go/cache"
>       GOMODCACHE: "/workspace/.ankra-go/mod"
>       GOTMPDIR: "/workspace/.ankra-go/tmp"
>       GOFLAGS: "-buildvcs=false"
>     run: |
>       mkdir -p "$GOTMPDIR"
>       go test ./...
> ```

Each of these was run on a real pipeline cluster before it was published. A few lines in them are there because of how Ankra runs a step, and every pipeline you write will need them:

* **`checkout` is a stage you declare.** Every run starts from an empty workspace, mounted at `/workspace`, and nothing is cloned unless a `checkout` stage does it. Stages that come after it list it in `needs`.
* **`manual: {}` lets you start a run by hand.** Without it, `ankra pipeline run` and the portal's **Run pipeline** button answer that no trigger matches.
* **`network: "egress-https"` lets a step download packages.** A `run` stage has no network access by default. `egress-https` allows HTTPS to the public internet and nothing private.
* **Package caches point into `/workspace`.** A step runs as a non-root user on a read-only root filesystem. `HOME` is `/tmp`, which is writable but small and held in memory, so the file sends each package manager's cache to `/workspace`, the run's shared, disk-backed volume.

More toolchains, image builds and database-backed tests are in [Starter pipelines](/guides/ankra-ci-starter-pipelines).

## 5. Validate and store the definition

Check the file before you commit it. `validate` plans it for a sample push and a sample pull request and prints which stages would run:

```bash theme={null}
ankra pipeline validate .ankra/pipeline.yaml --repository <repository-id>
```

A `fatal` result means the file cannot run - fix what it names. A `warn` means it runs, but probably not the way you meant, so read it.

Then store the file as the repository's definition, so the very first webhook has something to run:

```bash theme={null}
ankra pipeline definition put .ankra/pipeline.yaml --repository <repository-id>
```

On GitHub, every later run reads `.ankra/pipeline.yaml` from the commit it runs, so changing the file in a pull request changes that pull request's run. On GitLab and Bitbucket Cloud the stored definition is what runs, so run `definition put` again whenever you change the file.

> [!TIP]
>
> You can also ask Ankra's AI to check a pipeline in the portal chat - "validate this .ankra/pipeline.yaml" with the file pasted in - which needs no repository at all.

## 6. Open a pull request and watch the run

Commit the file on your branch, push it and open a pull request into `main`:

```bash theme={null}
git checkout -b add-ankra-ci
git add .ankra/pipeline.yaml
git commit -m "Add the Ankra pipeline"
git push -u origin add-ankra-ci
```

Shortly after the push, the pull request gets an **Ankra pipeline** check with a table of steps. On GitHub it has a **Cancel** button while the run is live and GitHub's own **Re-run** afterwards. Ankra also keeps one status comment on the pull request up to date with the same table.

Follow the same run from your terminal:

```bash theme={null}
ankra pipeline list --repository <repository-id>
ankra pipeline get --repository <repository-id> --branch add-ankra-ci --latest --watch
ankra pipeline logs <run-id> --repository <repository-id> --step test --follow
```

In the portal, the run has a timeline, each step's output, test results and artifacts, with **Re-run failed steps** and **Cancel run** on the run page.

**You should see** both steps succeed. On a repository's first pipeline the check then waits with the title **Awaiting authority approval** - that is the next step, not a failure.

## 7. Approve the pipeline once

The check waits because a pipeline that runs on pull requests carries a security setting an administrator has to accept: `fork_policy: read_only`, which runs pull requests from forks with no secrets, no credentials and no network beyond what their checkout, build and scan need. It is the safest setting there is, and Ankra still asks a person to approve it rather than granting anything on its own. The check lists it in a table:

| Protected setting | Approved today | This pipeline asks for |
| - | - | - |
| `fork_policy` | - | `read_only` |

Approve it:

> [tab] Portal
>
> Open **Settings → Pipelines**. **Pending approvals** lists every repository waiting, with the protected settings it asks for. Review them and click **Approve**. You can also approve from the run page, or press **Approve authority** on the GitHub check if your GitHub account is linked to your Ankra profile.

> [tab] CLI
>
> The pull request comment prints the exact command with the definition id filled in. Read what you are granting, then approve it:
>
> ```bash theme={null}
> ankra pipeline definitions get <definition-id>
> ankra pipeline definitions approve <definition-id>
> ```

Approving needs an organisation administrator with pipeline management access, signed in as themselves - an API token cannot approve.

**You should see** the check turn green. Every later pull request gets a plain green or red check, as long as nobody changes a protected setting. Merge the pull request: the push to `main` runs the pipeline again, this time as a branch run.

### When you add more to the pipeline

The same approval covers more than the fork policy. These settings are **protected**: secrets, credentials, caches, CPU and memory, a stage's timeout, sidecar services such as a database, network access beyond `egress-https`, and where a step runs.

A pull request can change what a pipeline *does* - its stages, scripts and images - but not what it is *allowed to touch*. Otherwise anyone who can open a pull request could read your secrets or claim your biggest nodes. So a protected setting takes effect only once an administrator approves the version of the file on the default branch. Until then, runs execute as if the setting were not there, and the check and `ankra pipeline validate` both say which settings were left out.

The order is always the same: merge the change to the default branch, approve it, and the waiting runs re-run on their own. A change that touches no protected setting never needs approval.

## 8. Make it the check that guards `main`

Once the pipeline has been green on a few pull requests:

1. In your repository's branch protection rules (on GitHub, **Settings → Branches** or **Rules**), add **Ankra pipeline** as a required status check.
2. Remove or disable the old workflow (`.github/workflows/*.yml`, `.gitlab-ci.yml`), so each commit is built once.

[Move a team to Ankra CI](/guides/move-to-ankra-ci) has the full rollout plan for more than one repository.

## What you have now

* [x] A pipeline cluster and pipeline workers for the organisation
* [x] A repository connected to Ankra Pipelines
* [x] `.ankra/pipeline.yaml` that runs on every push and pull request
* [x] An `Ankra pipeline` check on every commit, and run history in Ankra
* [x] Protected settings that only an administrator can grant

## Next steps

> [card] [Starter pipelines](/guides/ankra-ci-starter-pipelines)
>
> Copy-paste pipelines for Node.js, Python, Go and Rust, caches, a Postgres service, and build, scan and publish an image.

> [card] [Move a team to Ankra CI](/guides/move-to-ankra-ci)
>
> A rollout plan from one pilot repository to all of them, with a GitHub Actions to Ankra mapping.

> [card] [Troubleshooting](/guides/ankra-ci-troubleshooting)
>
> A push that started nothing, a step that waits, a step that cannot write or download.

> [card] [Ankra Pipelines in depth](/guides/ankra-pipelines)
>
> How a run is planned and dispatched, the security model, organisation CI settings and capacity.


# Guided Setup
Source: https://docs.ankra.ai/get-started/guided-setup

Go from a new organisation to a live website in four steps: a free cluster, your welcome credit, where the code lives, and a website Ankra generates from one sentence.

Guided setup walks a new organisation from nothing to a website running on its own cluster, with a public address. Open it from the first-run screen (**Guided setup: a live website in ten minutes**) or go straight to `/organisation/onboarding`.

There are four steps. Each one shows its progress and remembers where you got to, so you can leave and come back.

**1. Create your cluster**

One click creates your organisation's free cluster - a [playground](/guides/cluster-sandbox). Playgrounds are moving to Ankra Cloud dev clusters, a single-node Kubernetes cluster managed by Ankra; this is rolling out. The step shows the cluster provisioning, the domain your apps will be published under, and, for a free cluster, when it ends.

If your organisation already has a playground, the step picks it up instead of creating a second one.

**2. Unlock your credit**

Click **Add payment method** to save a card. Saving it unlocks **€59 of credit, valid for 60 days**, which pays for your resources before anything is charged to the card.

> [!TIP]
>
> **You will never be charged without a top-up.** Your card is only charged when you add credit yourself. Automatic top-up stays off unless you turn it on.

We recommend turning automatic top-up on in **Billing** once you are running something you care about: when your credit runs low it adds more, so your services keep running without a pause. See [Credit and payment method](/platform/billing#credit-and-payment-method) for how credit is spent.

Cards are handled by Stripe; Ankra never sees your card number. You can skip this step and come back to it, but without a card a free Ankra Cloud dev cluster lasts 24 hours.

**3. Choose where the website lives**

Pick one:

* **The Ankra default** - no repository. Ankra deploys the generated site straight to your cluster as a Stack.
* **A new GitHub repository** - Ankra creates the repository in the GitHub account or organisation you choose (public or private), commits the site to it, and registers it as an [application](/concepts/applications). Every push to the repository is built and deployed to your cluster. This option needs a [GitHub connection](/integrations/github).

**4. Launch your website**

Describe the website you want in one sentence - for example *"a landing page for a neighbourhood bakery with opening hours and a contact form"*. Ankra's AI generates a complete, responsive site and deploys it to your cluster.

The step follows the site through designing, deploying and live, then links to the public address and, if you chose a repository, to the code.

## What you end up with

* A Kubernetes cluster managed by Ankra, with the Ankra agent installed and connected.
* A website served from that cluster at a public address under the cluster's domain.
* With a repository: an application whose builds and deploys run on every push, the same way as any other [application](/concepts/applications).

From here, everything in the [Quickstart](/get-started/quickstart) works on the same cluster: deploy a Stack, browse live resources, and ask Ankra's AI about what is running.

## Good to know

* Website generation uses your organisation's AI allowance. One website is generated at a time per organisation.
* Steps you cannot complete - for example adding a card without billing permissions - can be skipped. Ask a billing owner in your organisation to add the payment method.
* The free cluster is for development and evaluation. See [Playground](/guides/cluster-sandbox) for its limits and how long it lasts.


# Quickstart
Source: https://docs.ankra.ai/get-started/quickstart

In about 15 minutes, connect a Kubernetes cluster to Ankra (or start a free playground), deploy your first Stack, and ask Ankra's AI about what is running.

Each step below ends with something you can see, so you know it worked before you move on.

> [!TIP]
>
> New organisation? [Guided setup](/get-started/guided-setup) takes you from a free cluster to a live website, generated from one sentence, in four steps.

**What you need:** an Ankra account ([sign up at platform.ankra.app](https://platform.ankra.app)), and either a Kubernetes cluster you can run `helm` against, or nothing at all - the free playground gives you a cluster.

***

## 1. Get a cluster

> [tab] No cluster: use the playground
>
> The [playground](/guides/cluster-sandbox) is a real, writable Kubernetes cluster that Ankra runs for you. It is ready in about two minutes and needs no cloud account.
>
> **1. Start it**
>
> On your first visit, the dashboard offers **See a demo app first** - click **Start the playground**. You land on the new cluster's overview and can watch it provision.
>
> **2. Check it is ready**
>
> When it is ready, the overview shows **Your app is live** with the public URL of a small starter app Ankra deployed for you. Open it.
>
> How long the free playground lasts depends on where it runs - see [Playground](/guides/cluster-sandbox). As an Ankra Cloud dev cluster it lasts 24 hours without a payment method, and saving a card keeps it running, paid from your credit. Everything you do here works the same on your own cluster.

> [tab] Connect your own cluster
>
> Any conformant cluster works: EKS, GKE, AKS, k3s, kind, minikube or on-premises. You need `helm` and a kubeconfig that can create a namespace.
>
> **1. Create the cluster in Ankra**
>
> Go to **Clusters**, click **Import**, give the cluster a name, and click **Import cluster**. The Git repository and add-on fields are optional - you can add both later.
>
> **2. Install the agent**
>
> Ankra shows a `helm` command for this cluster. Copy it exactly as shown - it carries your cluster's token and pins the agent version - and run it wherever your kubeconfig points at the cluster. It looks like this:
>
> ```bash theme={null}
> helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
>   --version <version> \
>   --set config.ankra_url=https://platform.ankra.app \
>   --set config.token=<your-cluster-token> \
>   --namespace=ankra --create-namespace
> ```
>
> The agent only makes outbound connections to Ankra, so it works behind firewalls, NAT and private networks.
>
> **3. Check it is connected**
>
> The cluster's status changes from **Awaiting Connection** to **Healthy**, usually within a minute. Open the cluster: you can now browse its workloads, events and logs.
>
> Not connecting? Run `kubectl get pods -n ankra` and see [Ankra Agent troubleshooting](/concepts/cluster-agent).

> [!TIP]
>
> Want Ankra to build a new cluster on Hetzner, AWS, DigitalOcean or another provider, or create EKS, GKE or AKS for you? See [Add a cluster](/guides/import-cluster) - then come back to step 2.

***

## 2. Deploy your first Stack

A **Stack** is what a cluster should run: Helm charts (called [add-ons](/concepts/addons)) and your own Kubernetes YAML ([manifests](/concepts/stacks#manifests)), deployed together in the right order. You will deploy [Grafana](https://grafana.com/oss/grafana/), the dashboarding tool, so there is something real to look at.

**1. Open the Stack Builder**

Open your cluster, go to **Stacks**, and click **+ Create**. The builder canvas opens.

**2. Add the add-on**

Click **Add Add-on**, search for **Grafana**, and select it. The defaults are fine - click the add-on on the canvas if you want to see or change its Helm values.

**3. Deploy it**

Name the Stack (for example `dashboards`) and click **Create Stack**. This saves and deploys it in one step, straight through the agent - no Git repository needed.

**4. Check it is running**

The Stack's status moves to deployed within a minute or two. Go to **Kubernetes** → **Workloads** → **Pods** and you will see the `grafana` pod **Running**.

> [!NOTE]
>
> You can build the same Stack by asking the AI instead: press <kbd>⌘</kbd> + <kbd>J</kbd> (<kbd>Ctrl</kbd> + <kbd>J</kbd> on Windows and Linux) and type *"Add a Stack with Grafana to this cluster"*. The AI picks the chart, builds the Stack and deploys it for you.

***

## 3. Ask the AI about it

Ankra's AI sees what you are looking at - the pod's logs, events, manifest and recent deploys - so you can ask plain questions without pasting anything.

**1. Open the assistant on the pod**

Open the `grafana` pod from step 2 and press <kbd>⌘</kbd> + <kbd>J</kbd>. Leave the mode on **Ask**, which reads and explains but does not change anything already running.

**2. Ask a question**

Try *"Is this pod healthy, and how do I open Grafana and log in?"* or *"What would happen if this pod restarted?"*. The answer is based on your cluster's actual state.

When you want the AI to make changes, switch to **Agent** (it asks you to confirm each change) or **Plan** (you approve a whole plan once). See [AI Assistant](/platform/ai-assistant) for what each mode may do.

***

## 4. Optional: keep the cluster's configuration in Git

Stacks work without Git. Connect a GitHub repository when you want every change to be reviewed, versioned and reversible - Ankra then commits each Stack change to the repository, and commits you push are deployed back to the cluster.

**1. Connect a repository**

Open the cluster, go to **Settings** → **GitOps**, choose a GitHub credential (or add one), and pick the repository. Nothing extra is installed on the cluster.

**2. Check the commit**

Your `dashboards` Stack appears in the repository under `clusters/`, as Helm values and manifests you can review like any other code.

See [GitOps](/concepts/gitops) for how two-way sync and conflicts work.

***

## You are done

You now have:

* a cluster connected to Ankra, showing **Healthy**
* a Stack deployed to it, with its pod **Running**
* an answer from the AI based on your cluster's real state

## What's next

> [card] [Ship your own app](/guides/deliver-your-app)
>
> Get a repository running on a cluster and redeployed on every merge.

> [card] [Build a monitoring stack](/guides/monitoring-stack)
>
> Prometheus, Grafana and Loki as one Stack.

> [card] [Use the CLI and your AI assistant](/integrations/ankra-cli)
>
> `ankra chat`, `ankra cluster apply`, and the MCP server for Claude and Cursor.

> [card] [Reuse a Stack everywhere](/concepts/stack-profiles)
>
> Turn a working Stack into a template for every cluster.

> [card] [Variables](/concepts/variables)
>
> One Stack, different values per cluster or environment.

> [card] [Get alerted](/guides/alerts)
>
> Page your team in Slack when something in the cluster goes wrong.

Stuck on a step? [Contact support](/platform/support) or ask in the [Ankra community Slack](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA).


# Azure Kubernetes Service (AKS)
Source: https://docs.ankra.ai/guides/aks-clusters

Provision, import, and operate Azure Kubernetes Service (AKS) clusters with Ankra - region-scoped catalogue, availability zones, spot pools, VNet subnets, maintenance windows, retention-aware deletion, GitOps, and AI-assisted operations.

[Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/products/kubernetes-service) is Microsoft Azure's managed Kubernetes service. Azure runs the control plane; Ankra provisions the cluster, then manages everything on top - node pools, Kubernetes upgrades, add-ons, Stacks, GitOps, and AI-assisted operations.

This page covers AKS specifically. For the shared concepts across all managed providers - live options, discovery/import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes).

> [!TIP]
>
> **Already running AKS?** You can bring it into Ankra two ways. A **managed import** uses your Azure credential: in **Clusters**, click **Create cluster** and choose **Import existing**, or run `ankra cluster managed discover --provider aks` and `ankra cluster managed import --provider aks`. Ankra fetches the kubeconfig and installs the agent, so there is nothing to run on the cluster, and the cluster gains the same node-pool and upgrade operations as clusters Ankra created. The **Helm import** needs no cloud credential and works for any cluster: run the one `helm` command the Import dialog gives you - see [Import an existing cluster](/guides/import-cluster#import-an-existing-cluster).

## Why AKS with Ankra

* **A catalogue for the location you pick** - Kubernetes versions, VM sizes, availability zones, subnets and prices are read for the selected Azure location, and sizes your subscription cannot launch there are left out.
* **Spot node pools, zones and OS disks** - run a User pool on spot capacity with an optional price cap, spread a pool across availability zones, and choose a managed or ephemeral OS disk per pool.
* **Bring your own network** - place every node pool in an existing virtual network subnet, or let AKS create its VNet.
* **Planned maintenance** - pin the weekly window in which Azure may run control-plane upgrades and node reboots.
* **Stop and start** - AKS is the only managed provider with native cluster stop/start, exposed in the portal, CLI, API and Ankra's AI.
* **Retention-aware deletion** - keep or delete the resource group Ankra created for the cluster; a resource group you brought is never deleted.

## Prerequisites

An **Azure service principal** stored in Ankra with the roles described in [Azure Credentials](/platform/credentials/azure). Store it from the portal or with `ankra credentials azure create`.

GitOps is optional: connect a repository at creation and Ankra commits the cluster's Stack definitions to Git.

## Creating an AKS cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick Azure's **Cloud Managed** action.
>
> **2. Credential, location and network**
>
> Select the Azure credential and a location (for example `westeurope`). The catalogue reloads for that location. Optionally pick a **virtual network subnet** for the node pools, and name an existing **resource group** to adopt - leave it empty and Ankra creates and owns one.
>
> **3. Node pools**
>
> Define one or more pools: name, VM size (with live pricing), count, labels, taints and autoscaling bounds. Per pool you can pick **availability zones**, the **OS disk** type and size, and - on every pool except the first - **spot capacity** with an optional hourly price cap. The first pool is the AKS System pool and always runs on regular capacity.
>
> **4. Kubernetes and control plane**
>
> Pick a Kubernetes version or keep the default, then the **network plugin** (`azure` or `kubenet`), the **SKU tier** (`Free`, `Standard` with the uptime SLA, or `Premium`), whether the API server is **private**, and an optional **maintenance window**.
>
> **5. GitOps (optional) and create**
>
> Optionally connect a Git repository, then create. Ankra runs the AKS preflight (credential, location, version, name, size availability, zones, OS disk support, vCPU quota, subnet), submits the cluster, shows it while Azure provisions it, retrieves the kubeconfig, and installs the Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider aks \
>   --name my-aks-cluster \
>   --credential-id <azure-credential-id> \
>   --location westeurope \
>   --node-pool-name system \
>   --node-pool-size Standard_D2s_v5 \
>   --node-pool-count 2 \
>   --zone 1,2,3 \
>   --os-disk-type Ephemeral \
>   --network-plugin azure \
>   --sku-tier Standard \
>   --vnet-subnet-id <subnet-arm-id> \
>   --maintenance-window Saturday:22:4
> ```
>
> Every `--` flag after `--node-pool-count` is optional. `--maintenance-window` takes `<Weekday>:<start-hour>:<hours>` in UTC. Add spot pools after creation with `node-pool add --spot`.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/managed/aks \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-aks-cluster",
>     "credential_id": "<azure-credential-id>",
>     "location": "westeurope",
>     "kubernetes_version": "1.31.1",
>     "node_pools": [
>       {"name": "system", "size": "Standard_D2s_v5", "count": 2, "zone": "1,2,3", "root_volume_type": "Ephemeral"},
>       {"name": "batch", "size": "Standard_E4s_v5", "count": 3, "spot": {"enabled": true, "max_price": 0.05},
>        "autoscaling": {"enabled": true, "min_count": 1, "max_count": 10}}
>     ],
>     "aks": {
>       "network_plugin": "azure",
>       "sku_tier": "Standard",
>       "private_cluster": false,
>       "vnet_subnet_id": "<subnet-arm-id>",
>       "maintenance_window": {"day": "Saturday", "start_hour": 22, "duration_hours": 4}
>     }
>   }'
> ```

### AKS options

| Field | Description |
| - | - |
| `aks.resource_group` | Existing resource group to adopt. Omit it and Ankra creates `ankra-<name>`, tags it as Ankra-owned, and deletes it with the cluster. An adopted group is never modified or deleted. |
| `aks.network_plugin` | `azure` (default; pods get VNet addresses, required with a customer subnet) or `kubenet` |
| `aks.sku_tier` | `Free` (default, no control-plane fee), `Standard` (uptime SLA, about \$73 per month) or `Premium` |
| `aks.private_cluster` | Private API server endpoint |
| `aks.vnet_subnet_id` | ARM id of the subnet every node pool joins; pick one from the catalogue's `private_networks`. Omit for an AKS-managed VNet. |
| `aks.maintenance_window` | `{day, start_hour, duration_hours}` - an English weekday, a 0-23 UTC hour and 4-24 hours |

### Node pool options

| Field | Description |
| - | - |
| `zone` | Availability zone(s) from the catalogue's `zones`, comma-separated to spread the pool (`"1,2,3"`). Omit for a regional pool. |
| `root_volume_type` | OS disk type, `Managed` or `Ephemeral`. Ephemeral needs a VM size that supports it; preflight checks. |
| `root_volume_size_gb` | OS disk size, at least 30 GB |
| `spot` | `{"enabled": true, "max_price": <hourly-cap>}` - spot capacity with an optional cap in USD per hour; omit `max_price` to pay up to the on-demand price. Refused on the first pool. |

> [!NOTE]
>
> AKS node pool names are lowercase alphanumeric, start with a letter and are at most 12 characters; cluster names are at most 63 characters. The first pool is the cluster's System pool: AKS requires at least one System pool, so Ankra refuses to delete the only one and refuses spot on it.

### Preflight

Every create runs a preflight you can also call on its own (`POST .../managed/aks/preflight` with the create body). It checks the service principal, pool names, the location and version, a name collision in the resource group, that each VM size is available to your subscription in that location and offered in the requested zones, ephemeral OS disk support, the subscription's regional and per-family vCPU quota against the pools' maximum node counts (and the separate regional spot vCPU quota for spot pools), the subnet, and the maintenance window. Catalogue reads the service principal lacks permission for become warnings; a failing item blocks the create.

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

Node pools, upgrades, stop/start and deletion work from the CLI, portal or API. The CLI examples use `--provider aks`:

```bash theme={null}
# add a spot pool spread over two zones
ankra cluster managed node-pool add <cluster-id> --provider aks \
  --name batch --size Standard_E4s_v5 --count 3 --zone 1,2 \
  --spot --spot-max-price 0.05 --autoscaling --autoscaling-min 1 --autoscaling-max 10

# scale a pool to a fixed count
ankra cluster managed node-pool scale <cluster-id> batch --provider aks --count 5

# turn autoscaling off again
ankra cluster managed node-pool update <cluster-id> batch --provider aks --autoscaling=false --count 3

# upgrade the cluster
ankra cluster managed upgrade <cluster-id> --provider aks --version 1.32.3

# delete the cluster
ankra cluster managed delete <cluster-id> --provider aks
```

In the portal, **Nodes → Node pools** lists every pool with its zones, OS disk and spot state; new pools pick their VM size from the location's catalogue.

### Upgrades

An upgrade moves the control plane **and every node pool** to the target version in one operation - the same request `az aks upgrade` sends. AKS refuses a control plane more than two minor versions ahead of a pool, so Ankra never leaves pools behind. Available targets come from Azure's upgrade profile; preview versions are skipped.

### Stopping and starting

AKS is the only managed provider with native cluster stop/start, and Ankra exposes it in the portal Danger Zone, CLI, API and Ankra's AI. Stopping deallocates the control plane and agent pools (Azure stops billing for compute) while keeping all configuration; starting brings the same cluster back.

```bash theme={null}
ankra cluster managed stop <cluster-id> --provider aks
ankra cluster managed start <cluster-id> --provider aks
```

Both operations are asynchronous on Azure's side - the cluster shows `stopped` or `running` once Azure completes the transition. Ankra advertises the capability per provider as `supports_stop_start`.

## Importing an existing AKS cluster

Discover the clusters in your subscription and adopt one into Ankra without touching it - discovery and import run from the portal, the CLI (`ankra cluster managed discover|import --provider aks`) or the API (see [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters)). Import brings the cluster's node pools, their zones, OS disks, spot settings, labels and taints into Ankra, and records the subnet the pools use.

> [!WARNING]
>
> Ankra needs the cluster's admin kubeconfig, which Azure only issues while **local accounts** are enabled. A cluster configured for Microsoft Entra ID only (`disableLocalAccounts: true`) is refused at import with an explanation; enable local accounts (`az aks update --enable-local-accounts`) before importing it.

## Deleting, disconnecting and retention

These operations are deliberately different:

* **Disconnect** removes the Ankra integration and cluster-local privileged material but never calls Azure. Use it for imported clusters.
* **Delete at Azure** deletes the AKS cluster (Azure removes its `MC_` node resource group with it) and then removes the Ankra integration. It is allowed normally for clusters Ankra created; an imported cluster needs the explicit force option.

With `retention_policy=delete` (the default) Ankra also deletes the resource group it created for the cluster. With `retention_policy=retain` that group survives and is reported in `retained_resources`. A resource group you named at creation is adopted: Ankra never deletes it and always reports it as retained.

> [!WARNING]
>
> A deleted resource group takes every resource in it with it. Keep other workloads out of the `ankra-<name>` group Ankra creates, or adopt a group of your own.

## Troubleshooting

* **403 on the resource group or subscription** - the service principal lacks a role listed in [Azure Credentials](/platform/credentials/azure). Catalogue reads need `Reader` at the subscription; creating clusters needs the AKS and network roles on the resource group.
* **Preflight fails on `quota` or `quota.spot`** - the pools' maximum node counts exceed the free regular or per-family vCPUs, or the spot pools exceed the regional spot (low-priority) vCPU quota, which Azure sizes separately and often at only a few vCPUs on new subscriptions. Request a quota increase for that location or pick smaller sizes.
* **VM size "not available to this subscription"** - Azure restricts the SKU in that location for your subscription. The catalogue already omits such sizes; a size typed by hand is caught at preflight.
* **"cannot run on spot capacity"** - spot was requested on the first pool. Put spot workloads in a later pool.
* **Import refused with "local accounts disabled"** - see the warning under importing.
* **Upgrade refused by Azure** - a pool is more than two minor versions behind the target. Upgrade in steps of one minor version.

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [Azure Credentials](/platform/credentials/azure)
* [Cluster settings](/platform/cluster-settings)


# Alerts
Source: https://docs.ankra.ai/guides/alerts

Monitor your clusters and resources with customizable alert rules

> [!NOTE]
>
> Ankra Alerts help you stay informed about your cluster health, resource issues, and operational events with configurable notifications.

## What are Alerts?

Alerts in Ankra let you define rules that automatically monitor your infrastructure and notify you when specific conditions are met. You can:

* **Monitor Cluster Health:** Get notified when clusters go offline or agents disconnect
* **Track Resource Status:** Watch for issues with GitOps repositories, add-ons, manifests, and stacks
* **Configure Conditions:** Set up multiple conditions with AND/OR logic for precise alerting
* **Receive Notifications:** Send alerts to any webhook-enabled service (Slack, Teams, PagerDuty, etc.)

### How Alerts Work

```mermaid theme={null}
flowchart LR
    A[Resource State Change] --> B[Condition Evaluation]
    B --> C{Conditions Met?}
    C -->|Yes| D[Alert Triggered]
    C -->|No| E[No Action]
    D --> F[Webhook Notifications]
    D --> G[AI Incident Created]
    F --> H[Slack / Teams / PagerDuty]
```

***

## Automatic AI Analysis

Every time an alert triggers, Ankra automatically starts an AI-powered analysis to help you understand what went wrong.

```mermaid theme={null}
flowchart LR
    A[Alert Triggers] --> B[AI Analysis Resource Created]
    B --> C[Analysis Job Scheduled]
    C --> D[Data Collection]
    D --> E[AI Analysis]
    E --> F[AI Incident Ready]
```

### What Happens Behind the Scenes

1. **AI Analysis Resource** - When conditions are met, Ankra creates an AI Analysis resource to track the investigation
2. **Analysis Job** - A background job is scheduled to collect and analyze data
3. **Data Collection** - The job gathers:
   * Pod status and container states
   * Kubernetes events (warnings, errors)
   * Container logs (recent output)
   * Job results and error messages
4. **AI Analysis** - Ankra's AI processes the data to identify:
   * Root cause of the issue
   * Severity assessment
   * Affected resources
   * Recommended actions
5. **AI Incident** - Results are saved as an AI Incident for review

> [!NOTE]
>
> View all AI Incidents in the **AI** → **Inbox**. Each incident includes the full analysis, affected resources, and an interactive checklist of recommended actions.

***

## Alerts Dashboard

The Alerts page displays key metrics at a glance:

| Metric | Description |
| - | - |
| **Total Alerts** | Number of configured alert rules |
| **Active** | Alerts currently enabled and monitoring |
| **Rules** | Total number of individual rules across all alerts |
| **Triggers (24h)** | How many times alerts fired in the last 24 hours |

You can filter alerts by status (Active/Disabled) using the quick filter pills on the dashboard.

***

## Alert Structure

An alert consists of rules, conditions, and webhook integrations:

```mermaid theme={null}
flowchart TD
    subgraph alert [Alert]
        A[Name / Description / Enabled]
    end

    subgraph rules [Rules]
        R1[Resource Type / Clusters / Severity / Cooldown]
    end

    subgraph conditions [Conditions]
        C1[Condition 1]
        C2[Condition 2]
    end
    subgraph webhooks [Webhooks]
        W1[Slack]
        W2[PagerDuty]
    end
    alert --> rules
    rules --> conditions
    C1 -->|AND / OR| C2
    alert --> webhooks
```

***

## Creating Alert Rules

> [!TIP]
>
> **Ask Ankra AI instead.** In the chat, describe the alert you want - "page critical when any cluster goes offline", "warn when a production stack is down" - and the assistant proposes a **Create alert** action with every rule spelled out (severity, clusters, conditions, cooldown). It is created once you confirm. The assistant only writes conditions the evaluator implements, so an alert it creates always fires when its condition is met. It can also mute an alert (**Disable alert**) or remove one (**Delete alert**), and the same tools are on the [MCP server](/platform/mcp-tools) as `create_alert`, `set_alert_enabled` and `delete_alert`.

**1. Name & Details**

Configure the basic alert settings:

* **Alert Name:** A descriptive name (e.g., "Production Resources Down")
* **Severity:** Choose Critical, Warning, or Info
* **Cooldown:** Time in minutes before the alert can trigger again (prevents alert storms)
* **Clusters:** Select "All Clusters" or choose specific clusters to monitor

**2. What to Monitor**

Select the resource type to monitor:

> [card] Cluster
>
> Monitor overall cluster health including:
>
> * Cluster connectivity state
> * Agent status and availability

> [card] Cluster Resource
>
> Monitor specific resource types:
>
> * **GitOps** - GitHub repository sync status
> * **Addon** - Add-on deployment health
> * **Manifest** - Raw manifest deployments
> * **Stack** - Stack deployment status

**3. When to Alert**

Define one or more conditions that trigger the alert. Multiple conditions can be combined using **AND** or **OR** logic.

**For Cluster monitoring:**

* **Cluster State:** Alert when cluster goes offline/online

**For Cluster Resource monitoring:**

* **Resource State:** Alert on state changes (up, down, creating, updating, stopping)
* **Job Status:** Alert on job outcomes (failed, timeout, blocked, etc.)

**4. Notifications**

Select which destinations (webhooks) should receive notifications when this alert fires. You can configure destinations in the [Webhooks](/guides/webhooks) section.

In addition to the alert's own destinations, org-wide **routing rules** (Alerting → Destinations → Routing rules) can match alert firings by kind, severity, cluster, and source - for example, "every critical firing also goes to PagerDuty".

A destination that the alert already notifies directly is skipped by routing rules. That is a guarantee, not a coincidence of timing: **a notification is delivered at most once per destination**, so you can safely keep a destination attached to an alert *and* pointed at by a routing rule. See [Notification routing](/guides/notification-routing) for how rules are ordered, what Exclude and Stop on match actually do, and how to preview which destinations a notification would reach.

If you have set a [home channel](/guides/webhooks#home-channel), a critical or warning firing that no destination or routing rule handles falls back to the home so it is never missed.

***

## Condition Types Reference

### Cluster Conditions

Use these when monitoring **Cluster** resource type:

| Condition | Description | Values |
| - | - | - |
| **Cluster State** | Monitor cluster connectivity | `offline`, `online` |
| **GitOps Sync** | Monitor the cluster's GitOps sync verdict | `failing`, `degraded`, `healthy` |
| **Metric Threshold** | Compare a platform metric against a numeric threshold | `cpu_utilisation_pct`, `memory_utilisation_pct`, `disk_utilisation_pct`, `pod_restarts_15m`, `oom_kills_15m`, `nodes_not_ready`, `pods_pending` |
| **Metrics Stopped Flowing** | Fire when the cluster has shipped no platform metrics for longer than the threshold (minutes) | `platform_metrics` |
| **Security Findings** | Compare the Trivy vulnerability posture against a numeric threshold | `critical`, `high`, `severe`, `fixable_critical`, `fixable_high`, `new_severe_cves`, `new_kev_cves`, `kev`, `risk_score` |

### Cluster Resource Conditions

Use these when monitoring **Cluster Resource** types (GitOps, Addon, Manifest, Stack):

| Condition | Description | Values/Options |
| - | - | - |
| **Resource State** | Monitor resource health state | `all_up`, `up`, `creating`, `updating`, `stopping`, `down` |
| **Job Status** | Monitor job execution status | `blocked`, `failed`, `pending`, `running`, `success`, `timeout`, `cancelling`, `cancelled` |

### Condition Operators

For numeric threshold conditions, you can use these operators:

| Operator | Description |
| - | - |
| `eq` | Equals |
| `neq` | Not equals |
| `gt` | Greater than |
| `gte` | Greater than or equal |
| `lt` | Less than |
| `lte` | Less than or equal |

***

## Alert Severity Levels

| Level | Description | Use Case |
| - | - | - |
| **Critical** | Immediate action required | Production outages, service unavailable |
| **Warning** | Attention needed soon | Resource pressure, degraded performance |
| **Info** | Informational updates | Successful deployments, routine events |

***

## Viewing Alert History

Each alert tracks its trigger history. From the alert detail page, you can:

* **View Statistics:** Total triggers, last check time, last triggered time
* **Review History:** See when alerts triggered and what conditions matched
* **Analyze Patterns:** Identify recurring issues across your infrastructure

Navigate to **Alerts → \[Alert Name] → View History** to access the full timeline.

***

## Related

* [Alert-triggered analysis](/platform/ai-insights#alert-triggered-analysis) - the AI analysis attached to every firing
* [Webhooks](/guides/webhooks) - Configure notification endpoints for alerts

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.


# Ankra CI starter pipelines
Source: https://docs.ankra.ai/guides/ankra-ci-starter-pipelines

Copy-paste .ankra/pipeline.yaml files for Node.js (npm, pnpm, Yarn), Python (pip, uv), Go and Rust, plus caches, a Postgres service, a version matrix, secrets, a nightly run and an image build that is scanned and gated before it is published.

Each pipeline on this page is a complete `.ankra/pipeline.yaml`, or a stage you add to one. The test pipelines, the cache, the Postgres service, the matrix and the secret were each run on a real Ankra pipeline cluster before they were published, against a small project of each kind.

New to Ankra CI? Start with [Get started with Ankra CI](/get-started/ankra-ci), which connects the repository and gets the first run green.

## Three rules every step follows

A pipeline step is a container on your cluster, and three things about it differ from a CI runner or your laptop. Every recipe below already handles them, and anything you write yourself needs to as well:

1. **No network unless you ask.** A `run` stage has no network access by default. `defaults.network: "egress-https"` gives every stage HTTPS to the public internet, which is what installing packages needs. Private addresses stay out of reach unless an administrator allows them.
2. **A read-only root filesystem, and a non-root user.** A step cannot install system packages or write into the image, so `apt-get install` and `corepack enable` fail. Use an image that already has your tools in it. `HOME` is `/tmp`: writable, but 256 MiB and held in memory, so send package caches and build output to `/workspace` instead.
3. **One shared workspace.** `/workspace` holds the checkout and is shared by every stage of the run, so what one stage installs there, the next can use. `/tmp` is private to each step and starts empty.

## Test pipelines by toolchain

All of these run on pushes to `main`, pull requests into `main` and manual runs. Change `branches` to match your default branch.

> [tab] npm
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "node:24-alpine"
>     needs: ["checkout"]
>     env:
>       npm_config_cache: "/workspace/.ankra-node-cache/npm"
>     run: |
>       npm ci
>       npm test
> ```
>
> Needs a committed `package-lock.json`.

> [tab] pnpm
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "node:24-alpine"
>     needs: ["checkout"]
>     env:
>       COREPACK_HOME: "/workspace/.ankra-node-cache/corepack"
>       COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
>     run: |
>       corepack pnpm install --frozen-lockfile --store-dir /workspace/.ankra-node-cache/pnpm-store
>       corepack pnpm test
> ```
>
> Call pnpm as `corepack pnpm`. `corepack enable` tries to write into the image and fails on the read-only filesystem. Corepack installs the pnpm version your `package.json` pins in `packageManager`.

> [tab] Yarn
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "node:24-alpine"
>     needs: ["checkout"]
>     env:
>       COREPACK_HOME: "/workspace/.ankra-node-cache/corepack"
>       COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
>       YARN_CACHE_FOLDER: "/workspace/.ankra-node-cache/yarn"
>       YARN_GLOBAL_FOLDER: "/workspace/.ankra-node-cache/yarn-global"
>     run: |
>       case "$(corepack yarn --version)" in
>         1.*) corepack yarn install --frozen-lockfile ;;
>         *) corepack yarn install --immutable ;;
>       esac
>       corepack yarn test
> ```
>
> The `case` picks the install flag your Yarn version accepts: Yarn 1 takes `--frozen-lockfile`, and Yarn 2 and later take `--immutable`.

> [tab] Python (pip)
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "python:3.13-slim"
>     needs: ["checkout"]
>     env:
>       PIP_CACHE_DIR: "/workspace/.ankra-python-cache/pip"
>     run: |
>       python -m venv /workspace/.ankra-venv
>       . /workspace/.ankra-venv/bin/activate
>       pip install -r requirements.txt
>       pytest
> ```
>
> The virtual environment lives in the workspace because the image's own `site-packages` is read-only. `pytest` has to be in `requirements.txt`.

> [tab] Python (uv)
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "ghcr.io/astral-sh/uv:python3.13-bookworm-slim"
>     needs: ["checkout"]
>     env:
>       UV_CACHE_DIR: "/workspace/.ankra-python-cache/uv"
>       UV_LINK_MODE: "copy"
>     run: |
>       uv sync --locked
>       uv run pytest
> ```
>
> Needs a committed `uv.lock`, with `pytest` in a dependency group `uv sync` installs, such as `dev`.

> [tab] Go
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "golang:1.26"
>     needs: ["checkout"]
>     env:
>       GOPATH: "/workspace/.ankra-go"
>       GOCACHE: "/workspace/.ankra-go/cache"
>       GOMODCACHE: "/workspace/.ankra-go/mod"
>       GOTMPDIR: "/workspace/.ankra-go/tmp"
>       GOFLAGS: "-buildvcs=false"
>     run: |
>       mkdir -p "$GOTMPDIR"
>       go test ./...
> ```
>
> `-buildvcs=false` stops Go from asking git for version information. The checkout belongs to a different user than the step runs as, so git refuses to answer and the build would fail.

> [tab] Rust
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: "my-repo"
> on:
>   push:
>     branches: ["main"]
>   pull_request:
>     branches: ["main"]
>   manual: {}
> defaults:
>   network: "egress-https"
> stages:
>   - name: "checkout"
>     kind: "checkout"
>   - name: "test"
>     kind: "run"
>     image: "rust:1"
>     needs: ["checkout"]
>     env:
>       CARGO_HOME: "/workspace/.ankra-cargo/home"
>       CARGO_TARGET_DIR: "/workspace/.ankra-cargo/target"
>     run: |
>       cargo test --locked
> ```
>
> `--locked` needs a committed `Cargo.lock`. Drop it for a library that does not commit one.

> [!TIP]
>
> Running a test suite in a different image? Use any image your organisation's image policy allows, and keep the three rules above: tools already in the image, caches and build output under `/workspace`, and `network: "egress-https"` when the step downloads anything.

## Make it faster with caches

Without a cache, every run downloads its dependencies again. A `cache` block keeps directories of the workspace between runs, keyed on your lock file, so a run whose lock file did not change starts warm.

Add it to the stage that installs, pointing at the same directories its `env` sends the package manager's cache to. For the npm pipeline above:

```yaml theme={null}
  - name: "test"
    kind: "run"
    image: "node:24-alpine"
    needs: ["checkout"]
    env:
      npm_config_cache: "/workspace/.ankra-node-cache/npm"
    cache:
      - key: "npm-${{ hashFiles('package-lock.json') }}"
        paths: [".ankra-node-cache/npm"]
        restore_keys: ["npm-"]
        fallback: "none"
    run: |
      npm ci
      npm test
```

The paths are relative to the workspace. The same pattern for the other toolchains:

| Toolchain | `key` | `paths` |
| - | - | - |
| npm | `npm-${{ hashFiles('package-lock.json') }}` | `.ankra-node-cache/npm` |
| pnpm | `pnpm-${{ hashFiles('pnpm-lock.yaml') }}` | `.ankra-node-cache/pnpm-store`, `.ankra-node-cache/corepack` |
| Yarn | `yarn-${{ hashFiles('yarn.lock') }}` | `.ankra-node-cache/yarn`, `.ankra-node-cache/yarn-global`, `.ankra-node-cache/corepack` |
| pip | `pip-${{ hashFiles('requirements.txt') }}` | `.ankra-python-cache/pip` |
| uv | `uv-${{ hashFiles('uv.lock') }}` | `.ankra-python-cache/uv` |
| Go | `go-${{ hashFiles('go.mod', 'go.sum') }}` | `.ankra-go/mod`, `.ankra-go/cache` |
| Rust | `cargo-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}` | `.ankra-cargo/home/registry`, `.ankra-cargo/home/git`, `.ankra-cargo/target` |

Use the key's prefix as its `restore_keys` entry (`npm-`, `go-`), so a changed lock file still starts from the newest older cache.

> [!NOTE]
>
> **Caches need approval.** A cache decides whose earlier output is copied into a run, so the `cache` block is a protected setting: it takes effect once an administrator approves the pipeline on the default branch. Until then the stage runs cold and the run says so. The step's **CACHE** column in `ankra pipeline get` shows `miss` on the first run and `hit` from then on. [Caches](/guides/pipeline-reference#caches) covers keys, scopes and retention.

## Give a step more memory or time

Every step gets 500m of CPU, 1Gi of memory and 30 minutes unless the stage asks for more. A large JavaScript install, a TypeScript build or a big test suite often needs more memory - a step killed at its limit fails with the diagnosis `out_of_memory`.

```yaml theme={null}
  - name: "test"
    kind: "run"
    image: "node:24-alpine"
    needs: ["checkout"]
    resources:
      cpu: "2"
      memory: "4Gi"
    timeout: "45m"
    run: |
      npm ci
      npm test
```

`resources` and `timeout` are protected settings, so they apply once an administrator approves them. One step can ask for up to 8 CPU cores, 32Gi of memory and 6 hours.

## Test against a Postgres database

A service is a sidecar container next to your test step, reachable by its name. This pipeline installs dependencies in one stage with internet access, then runs the tests in a second stage on the `services` network tier, which reaches the database and nothing else:

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "my-repo"
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  manual: {}
defaults:
  network: "egress-https"
services:
  postgres:
    image: "postgres:17"
    env:
      PGDATA: "/var/lib/postgresql/data/pgdata"
      POSTGRES_USER: "app"
      POSTGRES_PASSWORD: "ci-only-password"
      POSTGRES_DB: "app_test"
    ports: ["5432"]
    ready:
      tcp: "5432"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "install"
    kind: "run"
    image: "python:3.13-slim"
    needs: ["checkout"]
    env:
      PIP_CACHE_DIR: "/workspace/.ankra-python-cache/pip"
    cache:
      - key: "pip-${{ hashFiles('requirements.txt') }}"
        paths: [".ankra-python-cache/pip"]
        restore_keys: ["pip-"]
        fallback: "none"
    run: |
      python -m venv /workspace/.ankra-venv
      . /workspace/.ankra-venv/bin/activate
      pip install -r requirements.txt
  - name: "test"
    kind: "run"
    image: "python:3.13-slim"
    needs: ["install"]
    network: "services"
    services: ["postgres"]
    resources:
      cpu: "1"
      memory: "2Gi"
    env:
      DATABASE_URL: "postgres://app:ci-only-password@postgres:5432/app_test"
    run: |
      . /workspace/.ankra-venv/bin/activate
      pytest
```

Three details matter, and each one fails in a confusing way when it is missing:

* **Use a Debian-based Postgres image** such as `postgres:17`, not an Alpine one. The sidecar also runs as a non-root user, and the Debian image's entrypoint is the one that can initialise a database that way.
* **Set `PGDATA` to a subdirectory.** The image's own data directory belongs to another user, and Postgres cannot take it over, so the sidecar would restart in a loop and the step would never start.
* **Install before you switch to `services`.** The `services` tier has no internet access, so a package install in the test stage fails. Install in an earlier stage on `egress-https` and reuse what it left in `/workspace`.

The `ready` probe holds the test step until Postgres accepts connections. The password here is for this throwaway database only - use a pipeline secret (below) for anything real. `services`, the `services` network tier, `cache` and `resources` are protected, so approve the pipeline before you rely on them.

## Test against several versions

A `matrix` runs one stage once per value, in parallel:

```yaml theme={null}
  - name: "test"
    kind: "run"
    image: "node:${{ matrix.node }}-alpine"
    needs: ["checkout"]
    matrix:
      node: ["20", "22", "24"]
    env:
      npm_config_cache: "/workspace/.ankra-node-cache/npm-${{ matrix.node }}"
    run: |
      node --version
      npm ci
      npm test
```

The run shows one step per value: `test:node=20`, `test:node=22`, `test:node=24`. Give each leg its own cache directory, as above, because the legs share the workspace and run at the same time. A matrix takes `include` and `exclude` lists as GitHub Actions does, up to 64 legs per stage.

## Use a secret in a step

Store the value in Ankra once, as an organisation variable - **Variables and secrets** in the portal, or from the CLI, which reads the value from standard input so it stays out of your shell history:

```bash theme={null}
ankra org variables set NPM_TOKEN -
```

Then declare it in the pipeline, and name it on the stage that needs it:

```yaml theme={null}
secrets:
  - name: "npm_token"
    from: "org_variable"
    key: "NPM_TOKEN"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "test"
    kind: "run"
    image: "node:24-alpine"
    needs: ["checkout"]
    secrets: ["npm_token"]
    run: |
      printf '//registry.npmjs.org/:_authToken=%s\n' "$(cat /run/agent-secrets/npm_token)" > "$HOME/.npmrc"
      npm ci
      npm test
```

A secret arrives as a **file**, `/run/agent-secrets/<name>`, not as an environment variable, and never appears in the pipeline or a log. `from` is `org_variable` for an organisation or cluster variable, `app_env_secret` for the linked application's environment secret, or `registry` for a registry login. Only the stages that list a secret can read it, and pull requests from forks get none.

`secrets` is a protected setting. Merge the declaration to the default branch and approve it before the first run that needs it - a pull request that adds a secret runs without it until then.

## Run every night

Declare the schedule in the pipeline, then create it once:

```yaml theme={null}
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  schedule:
    - cron: "0 2 * * *"
```

```bash theme={null}
ankra pipeline schedules create --cron "0 2 * * *" --timezone Europe/Stockholm --repository <repository-id>
ankra pipeline schedules list --repository <repository-id>
```

The cron has five numeric fields. It runs against the default branch unless the schedule names another `--ref`. To run only your slow suites at night, give the `schedule` entry a `stages` list, and include `checkout` and every stage those suites need. An application's **Pipelines** page in the portal has **Scheduled runs** as well, to create, pause or delete one.

## Build, scan and publish an image

For a repository linked to an [Ankra application](/concepts/applications), the pipeline can build the container image, scan it and publish it to your organisation's registry. Nothing reaches the registry until the gate has passed the exact image that was scanned. Add these stages after your tests:

```yaml theme={null}
  - name: "build"
    kind: "build"
    needs: ["test"]
    build:
      dockerfile: "Dockerfile"
      provenance: true
      sbom: true
  - name: "scan"
    kind: "scan"
    needs: ["build"]
    scan:
      scanners: ["semgrep", "checkov", "trivy"]
      fail_on:
        semgrep: "error"
  - name: "gate"
    kind: "gate"
    needs: ["scan"]
    gate:
      require_stages: ["scan"]
  - name: "publish"
    kind: "publish"
    needs: ["gate"]
    when:
      events: ["push"]
```

What each stage does:

* **`build`** builds the image rootless, inside your cluster, and stores it by digest in a staging area of your registry. A pull request's build is built and scanned but not published.
* **`scan`** runs Semgrep and Checkov over your source and Trivy over the image. The reports go to the run and to the application's **Security** tab.
* **`gate`** judges what the scanners found against your organisation's image policy - by default, fixable critical and high vulnerabilities in your own dependencies block. `fail_on` can make one pipeline stricter, never looser.
* **`publish`** tags the exact digest the gate passed as `sha-<first 7 characters of the commit>` in your application's repository, only on pushes to the default branch. Your application deploys that tag.

`build` and `scan` reach the internet by default, so they need no `network` line, and `gate` and `publish` run on the Ankra platform rather than in a pod. If your nodes stop the rootless builder from starting, Ankra builds the image on its own platform builders instead, and the scan and gate still run on your cluster. A new application's setup pull request commits these stages for you.

## A monorepo

For a repository with several components, give each component its own test stage with a path filter for pull requests, so a pull request only tests what it touches and a push to `main` tests everything. [Monorepo: PR-only checks, full builds on push](/guides/ankra-pipelines#monorepo-pr-only-checks-full-builds-on-push) has the full pattern.

## Related

* [Get started with Ankra CI](/get-started/ankra-ci) - connect a repository and get the first run green
* [Troubleshooting](/guides/ankra-ci-troubleshooting) - what a failing first pipeline usually means
* [Pipeline reference](/guides/pipeline-reference) - every key, trigger, stage kind and expression


# Ankra CI troubleshooting
Source: https://docs.ankra.ai/guides/ankra-ci-troubleshooting

Fix what a new Ankra pipeline usually hits first: a push that started no run, a check waiting for approval, a step that waits, cannot reach the network, cannot write, runs out of memory or cannot find its secret.

Find the symptom, then the fix. Most first-week problems are one of these, and the run usually names the cause itself: a failed or waiting step carries a **diagnosis** with what happened and what to do, shown above the steps on the run page and in `ankra pipeline get <run-id>`.

```bash theme={null}
ankra pipeline list --repository <repository-id>
ankra pipeline get <run-id> --repository <repository-id>
ankra pipeline logs <run-id> --repository <repository-id> --step <step>
```

Inside a checkout of an [Ankra application](/concepts/applications)'s repository you can leave out `--repository`: the CLI finds the application from your `origin` remote.

## A push or pull request started no run

Work down this list - each line is a reason Ankra records for an event that did not start a run.

| Check | Fix |
| - | - |
| Is the repository connected? `ankra pipeline repositories list` | Connect it - [step 3 of Get started](/get-started/ankra-ci#3-connect-the-repository) |
| Does it have a definition? `ankra pipeline definition get --repository <repository-id>` | Store one: `ankra pipeline definition put .ankra/pipeline.yaml --repository <repository-id>`. Connecting only reads the file when it is already on the default branch. |
| Is there a pipeline cluster? `ankra org ci-settings get` | `ankra org ci-settings set --cluster <cluster-name>`. Until you do, the commit gets a failing check that asks you to choose one. |
| Does `on:` match the event? | `on.push.branches` is the branch you pushed. `on.pull_request.branches` is the pull request's **base** branch, the one it merges into. |
| Did a path filter exclude it? | A push that changed no file under `paths` starts nothing. The run list shows it as concluded `skipped` with the reason. |

`ankra pipeline list` shows runs that were recorded as skipped, with the reason.

### No check appears on GitHub, but the run is there

The Ankra GitHub App needs the **Checks: write** permission to post the `Ankra pipeline` check. Without it, Ankra reports the run in its status comment on the pull request instead, and the comment says which permission is missing. Grant it in the App's settings on GitHub.

## "No trigger this pipeline declares matches this event"

`ankra pipeline run`, and the portal's **Run pipeline** button, answer this when the pipeline does not declare manual runs. Add it to `on:`:

```yaml theme={null}
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  manual: {}
```

## The check says "Awaiting authority approval"

The pipeline asks for a protected setting that no administrator has approved yet, and the check lists which. On a repository's first pipeline this is expected: the pull request trigger's `fork_policy: read_only` is one of them.

An application created from the portal by a person with pipeline management access does not reach this state: Ankra approves the pipeline it generated in that person's name. It still appears for an application added with the CLI, an API token or the AI Assistant, for a repository connected on its own, and whenever a later change edits a protected setting.

The steps still run, but the check stays in progress until an administrator approves. Approve once, in **Settings → Pipelines → Pending approvals**, with **Approve authority** on the check, or with the command the pull request comment prints:

```bash theme={null}
ankra pipeline definitions approve <definition-id>
```

The check then settles. See [Approve the pipeline once](/get-started/ankra-ci#7-approve-the-pipeline-once).

## A setting in the file has no effect

Secrets, credentials, caches, CPU and memory, a stage's timeout, services, a network tier above `egress-https` and step placement are **protected**. A run takes them only from the version of the pipeline on the default branch, and only once an administrator has approved it. Until then the run behaves as if they were not set - a cache does not restore, a memory limit stays at 1Gi, a secret's file is missing.

`ankra pipeline validate` names every protected setting that will not apply yet, and prints the command to approve it:

```bash theme={null}
ankra pipeline validate .ankra/pipeline.yaml --repository <repository-id>
```

Merge the change to the default branch, then approve it. The runs that waited re-run on their own.

## A step waits and does not start

The run page and `ankra pipeline get` say why a step is waiting. The common reasons:

| What it says | What to do |
| - | - |
| Waiting for a CI slot, or `waiting_on_ci_workers` | The cluster's agent has no free pipeline worker. On a new cluster it has none at all: `ankra cluster agent ci set --workers 2 --cluster <cluster-name>`. Otherwise raise the count. |
| `scale_up_in_progress` | A node is being added for the step. It usually joins in one to three minutes. |
| `node_group_at_max` | Every node group that could run the step is at its maximum. Raise the maximum, or add another cluster to the CI pool. |
| `no_node_group_fits`, `stage_exceeds_node_size` | No node is big enough for what the stage asks for. Lower its `resources`, or add a node group with bigger nodes. |
| `provider_quota_exceeded` | Your cloud provider refused a new node for a quota. Raise the quota with the provider. |
| `image_pull_auth`, `image_pull_failed` | The cluster cannot pull the step's image. Check the name and tag, and that the registry is reachable, or add the registry's credential to the organisation. |

A step that never starts is eventually concluded with a message pointing at the cluster's agent and its worker count, so a run never stays open forever. [Diagnosis codes](/guides/ankra-pipelines#diagnosis-codes) lists every code.

## The step cannot reach the network

A package install fails on a DNS lookup or a connection:

```text theme={null}
npm error code EAI_AGAIN
npm error request to https://registry.npmjs.org/... failed, reason: getaddrinfo EAI_AGAIN registry.npmjs.org
```

pip, Go, Cargo and curl report the same thing as `Temporary failure in name resolution`, `bad address` or `Could not resolve host`. A `run` stage has **no network by default**. Give it HTTPS to the public internet:

```yaml theme={null}
defaults:
  network: "egress-https"
```

Or set `network: "egress-https"` on the one stage that needs it. Two more cases:

* **A host on a private address**, such as an internal package mirror, stays out of reach on `egress-https`. An administrator can allow its range for every pipeline: `ankra org ci-settings set --egress-allowed-cidr 10.20.0.0/16`.
* **A stage on `network: "services"`** reaches its sidecar services and nothing else. Install dependencies in an earlier stage on `egress-https`, and reuse them from `/workspace`.

## "Read-only file system" or "permission denied"

A step runs as a non-root user (uid 65532) on a read-only root filesystem. It can write to three places:

| Path | What it is |
| - | - |
| `/workspace` | The run's shared volume, on disk. The checkout lives here. Put caches, virtual environments and build output here. |
| `/tmp` | Private to the step, 256 MiB, held in memory. `HOME` points here. |
| `/dev/shm` | 64 MiB unless the stage sets `shm_size`. |

The usual fixes:

* **`corepack enable` fails with `EROFS`** - call the package manager through corepack instead: `corepack pnpm install`, `corepack yarn install`.
* **`pip install` cannot write to `site-packages`** - create a virtual environment in the workspace first: `python -m venv /workspace/.ankra-venv`.
* **`apt-get install`, `apk add` fail** - a step cannot install system packages. Use an image that already contains the tools, such as `mcr.microsoft.com/playwright` for browser tests.
* **A compiler or test runner reports `No space left on device`** - it is filling `/tmp`. Point its temporary files into the workspace: `export TMPDIR=/workspace/.tmp && mkdir -p "$TMPDIR"` at the top of the `run` script.

## git: "detected dubious ownership in repository"

The checkout belongs to a different user than the one later steps run as, so git refuses to work in it:

```text theme={null}
fatal: detected dubious ownership in repository at '/workspace'
```

Trust the workspace on the command itself:

```bash theme={null}
git -c safe.directory=/workspace rev-parse HEAD
```

Go builds hit the same thing when they stamp version information. Add `GOFLAGS: "-buildvcs=false"` to the stage's `env`, as the [Go starter](/guides/ankra-ci-starter-pipelines#test-pipelines-by-toolchain) does. The commit being built is in `$ANKRA_HEAD_SHA` if that is all you needed git for.

## The step was killed: `out_of_memory`

The step used more memory than it asked for - 1Gi unless the stage says otherwise. Large JavaScript installs and TypeScript builds commonly need more. Raise it on the stage:

```yaml theme={null}
    resources:
      cpu: "2"
      memory: "4Gi"
```

`resources` is protected, so merge and approve it. `ankra pipeline get <run-id>` prints each step's memory peak against what it asked for, which tells you how much to ask for.

## The secret file is missing

```text theme={null}
cat: can't open '/run/agent-secrets/npm_token': No such file or directory
```

Check, in order:

1. The pipeline declares it in the top-level `secrets` list, **and** the stage lists its name under `secrets`.
2. The declaration is on the default branch and approved. A pull request that adds a secret runs without it until then.
3. The run is not from a fork. Pull requests from forks get no secrets.
4. The value exists: `ankra org variables get <NAME>` for an organisation variable.

## The cache never restores

The step's **CACHE** column in `ankra pipeline get` says what happened:

* **Nothing shown, or the cache is ignored** - `cache` is protected. Merge and approve it.
* **`miss` every time** - the key changes on every run, often because `hashFiles` matched nothing. Check the lock file name and that it is committed.
* **`disabled`** - the cluster has no StorageClass to back the cache. Give the pipeline cluster a default StorageClass.

Pull requests from forks and tag runs never share caches, by design.

## The build step fails before the Dockerfile is read

`build_runtime_confined` means the cluster's nodes stop the rootless image builder from starting - common with AppArmor on Ubuntu or k3s nodes. No pipeline or cluster setting changes that. Ankra builds the image on its own platform builders instead, and the scan, gate and publish still run as usual. That is on by default: `ankra org ci-settings get` should show `Build fallback: platform_builders` and `Platform builds enabled: yes`. If either says otherwise, set `ankra org ci-settings set --build-fallback platform_builders`, or [contact support](/platform/support).

## The check says `action_required`

The run failed because of Ankra or the cluster, not your code - an agent that went offline, a volume that would not attach, an image that could not be pulled. Ankra retries these once by itself. If the retry fails too, the check names the cause. Fix it if it is on your side, then press **Re-run** on the check, or:

```bash theme={null}
ankra pipeline rerun <run-id> --repository <repository-id> --failed-only
```

## Still stuck

Ask Ankra's AI in the portal chat - "why did run #12 of my-repo fail?" - and it reads the run, the step logs and the cluster's events. Or [contact support](/platform/support) with the run's link from the check.

## Related

* [Get started with Ankra CI](/get-started/ankra-ci)
* [Starter pipelines](/guides/ankra-ci-starter-pipelines)
* [When something fails](/guides/ankra-pipelines#when-something-fails) - every error class and how retries work


# Ankra Cloud Clusters
Source: https://docs.ankra.ai/guides/ankra-cloud-clusters

Build self-managed kubeadm or k3s clusters on Ankra Cloud servers with Ankra - a private network behind a NAT router, a bastion with public IPv4, IPv6-first nodes, and the Ankra Cloud CCM and CSI driver wired in.

Ankra builds **Ankra Managed** Kubernetes clusters on [Ankra Cloud](https://cloud.ankra.app) servers: a private network with a NAT router, a bastion server, control plane and worker servers on the private network, kubeadm or k3s installed over SSH, and the Ankra Cloud cloud controller manager and CSI driver deployed as a stack. You own the control plane and every server; Ankra provisions, upgrades and repairs them.

> [!WARNING]
>
> **Closed beta.** Ankra Cloud as a cluster provider is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request - until it is, Ankra Cloud does not appear in the create-cluster dialog or among the credential providers, and its endpoints are not served. [Contact support](/platform/support) to have it turned on for your organisation.

This is the self-managed lane. If you want the Ankra team to run the control plane for you, use [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes) instead; the [comparison table](/guides/managed-kubernetes#cloud-managed-or-ankra-managed) sets the two side by side.

***

## Before you start

> [card] Ankra Cloud Credential
>
> An Ankra Cloud API token (`act_...`) from a user allowed to create servers, networks and routers. The same credential serves both self-managed clusters and Ankra Cloud Kubernetes. See [Ankra Cloud Credentials](/platform/credentials/ankra-cloud).

> [card] SSH Key Credential
>
> An SSH public key for server access. You can provide your own or let Ankra generate one. See [SSH Key Credentials](/platform/credentials/ssh-key).

***

## Create the cluster

### Dashboard

**1. Open the create dialog**

Go to **Clusters**, click **Create cluster** and pick **Ankra Cloud** under **Ankra Managed** (kubeadm or k3s on Ankra Cloud servers).

**2. Credentials & Zone**

Pick the Ankra Cloud credential, or add one inline with **Add Ankra Cloud credential**. Choose the **Runtime credential** the in-cluster cloud controller and CSI driver use: the default reuses the provisioning credential, and a separate, dedicated credential limits what those components can reach. Pick an SSH key, then the zone. Zones, plans and templates load live from your Ankra Cloud account; a zone that runs no servers (a network-only location such as Stockholm) is refused.

**3. Private Network & Bastion**

Choose **Create a dedicated network** (Ankra creates and owns the network and its router; the wizard proposes `10.64.0.0/20`) or **Use an existing network** in the zone. Pick the bastion plan, and optionally restrict **Bastion allowed IPs** to the CIDRs that may reach the bastion over SSH; empty allows any address. **Storage retention on teardown** decides whether persistent volumes are kept (the default) or deleted when the cluster is deprovisioned.

**4. Compute**

Set the control-plane count (the wizard offers 1, 3 or 5; the API accepts any count from 1 to 9) and plan, then one or more worker node groups, each with its own plan, count, labels and taints. The cost summary prices every server from the live plan catalog, plus public IPv4. The router, storage, load balancers and transfer are not in the total; see [Cost](#cost).

**5. Kubernetes**

Choose the server template (default `debian-13`), the distribution and the Kubernetes version:

* **kubeadm** (default) - vanilla Kubernetes with containerd and Cilium. Cilium is the only CNI kubeadm accepts on Ankra Cloud. etcd runs stacked on the control-plane nodes, or on 3 or 5 dedicated external etcd servers with their own plan.
* **k3s** - a single binary with batteries included, with a choice of CNI.

**6. GitOps**

Optionally connect a Git repository, and Ankra commits the cluster's stacks to it. Two checkboxes are on by default:

* **Include Networking Stack** - Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind an Ankra Cloud load balancer.
* **Include DNS Integration** - external-dns, so Ingress hostnames publish their DNS records automatically.

Skipping GitOps still deploys the cloud controller manager and CSI driver; the `ankracloud-cloud-provider` stack is then not committed to Git.

**7. Preflight & Review**

Name the cluster and click **Run preflight**. The checks run against your account: the credential authenticates, the zone offers compute, every plan and the template exist, an existing network lives in the chosen zone, and kubeadm is paired with Cilium. Any failing check blocks creation and says why. Then click **Create cluster**; a progress view tracks the network, router, firewall, bastion, servers, Kubernetes installation and Ankra Agent.

### API

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/ankracloud \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<ankra-cloud-credential-id>",
    "ssh_key_credential_id": "<ssh-key-credential-id>",
    "zone": "de-fsn1",
    "bastion_plan": "<plan>",
    "control_plane_count": 1,
    "control_plane_plan": "<plan>",
    "worker_count": 2,
    "worker_plan": "<plan>",
    "distribution": "kubeadm"
  }'
```

Plans are account-wide; list them, and the zones, templates and networks the wizard offers, with `GET /api/v1/clusters/ankracloud/plans?credential_id=<id>` (and `/zones`, `/templates`, `/networks?zone=<zone>` alongside). `POST /api/v1/clusters/ankracloud/preflight` takes the same body and answers the checks without creating anything.

| Field | Default | Description |
| - | - | - |
| `zone` | | Ankra Cloud zone the servers are built in, for example `de-fsn1` |
| `template` | `debian-13` | Public server template: `debian-13`, `debian-12` or `ubuntu-24.04` |
| `distribution` | `kubeadm` | `kubeadm` or `k3s` |
| `kubernetes_version` | latest stable | Kubernetes version for the chosen distribution |
| `cni` | | CNI for k3s; kubeadm accepts only Cilium |
| `etcd_topology` | `stacked` | kubeadm only: `stacked` or `external`, with `etcd_node_count` (3 or 5) and `etcd_plan` |
| `network_ip_range` | a derived `/20` | RFC 1918 range, `/16` to `/29`, for the network Ankra creates |
| `private_network_id` | | Adopt an existing network in the zone instead; mutually exclusive with `network_ip_range` |
| `bastion_plan` | | Plan of the bastion server |
| `bastion_allowed_ips` | any | IPv4 or IPv6 addresses or CIDRs allowed to reach the bastion over SSH |
| `control_plane_count` | | 1 to 9 control-plane servers. The wizard offers 1, 3 and 5 |
| `control_plane_plan` | | Plan of the control-plane servers |
| `worker_count`, `worker_plan` | | A single worker group; use `node_groups` (each with `name`, `instance_type`, `count`, labels and taints) for several |
| `runtime_credential_id` | the provisioning credential | Ankra Cloud credential the in-cluster CCM and CSI use |
| `retention_policy` | `retain` | `retain` or `delete` persistent volumes on deprovision |
| `include_networking`, `include_dns` | `true` | Networking stack and DNS integration |
| `gitops_credential_name`, `gitops_repository`, `gitops_branch` | branch `master` | Optional GitOps repository |

A cluster has at most 100 workers across its node groups, and at most 64 nodes in all, control planes included, because of the pod range it is given (see [Network ranges and their limits](/platform/cluster-mesh#network-ranges-and-their-limits)). A request that plans more, counting each node group's autoscaling maximum, is refused before anything is provisioned.

***

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

***

## Network design

```mermaid theme={null}
flowchart TB
    Internet((Internet))
    Platform[Ankra Platform]

    subgraph Network [Ankra Cloud private network]
        Bastion[Bastion<br/>public IPv4 + IPv6]
        CP[Control plane servers<br/>private IPv4 + IPv6]
        Workers[Worker servers<br/>private IPv4 + IPv6]
        LB[Ankra Cloud load balancers<br/>created by the CCM]
    end

    Router[Router with NAT]

    Platform -->|SSH as root, port 22| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    CP -->|IPv4 egress| Router
    Workers -->|IPv4 egress| Router
    Router --> Internet
    Internet --> LB
    LB --> Workers
```

| Component | What Ankra creates |
| - | - |
| **Private network** | An RFC 1918 network, named after the cluster, that every server joins. Kubernetes runs on it: each kubelet's node IP is its private IPv4 address. An adopted network is used as it is and left in place on deprovision. |
| **Router with NAT** | A router attached to the private network with NAT enabled. It is the nodes' IPv4 path to the internet, and only that - it is never an SSH hop. |
| **Bastion** | A plain server with a public IPv4 address. Ankra connects to it as `root` on port 22 and jumps through it to every other server to install Kubernetes, run upgrades and reconcile. |
| **Control plane and workers** | Servers on the private network. They keep the public IPv6 address every Ankra Cloud server gets, behind the firewall, and have no public IPv4 address. The Kubernetes API is not published: Ankra reaches it through the bastion, and the Ankra Agent in the cluster connects out to Ankra. |
| **Firewall** | Ankra Cloud has no security groups, so Ankra applies a firewall to each server: inbound traffic is dropped by default, the private network is trusted as a whole, and the bastion accepts SSH from `bastion_allowed_ips` (or anywhere when it is empty). |

Ankra Cloud servers are IPv6-first. Nodes do not rely on the per-server IPv4 translation (CLAT) Ankra Cloud offers IPv6-only servers; pod and node IPv4 traffic leaves through the router's NAT instead.

Every server Ankra creates carries the labels `platform.ankra.io/managed-by=ankra-platform`, `platform.ankra.io/cluster-id=<cluster-id>` and `platform.ankra.io/role`, so you can find a cluster's servers in the Ankra Cloud console.

### Cost

Ankra Cloud bills the cluster's resources to your Ankra Cloud account. A cluster is made of:

* **Servers** - the bastion, the control planes and the workers, each at its plan price.
* **Public IPv4** - one address, held by the bastion. The nodes hold none, and IPv6 is not billed.
* **The router with NAT** - one for each cluster, billed monthly while NAT is enabled.
* **Load balancers** - the ones the cloud controller creates for `LoadBalancer` Services, the networking stack's Traefik included.
* **Persistent volumes** - the storages the CSI driver provisions, by tier and size.
* **Transfer** - outbound traffic beyond what each server includes.

The wizard's estimate covers the servers and the public IPv4 address only. For the current price of every line, see [Billing](https://cloud.ankra.app/docs/billing) in the Ankra Cloud documentation.

***

## Cloud controller and storage

After the Ankra Agent is installed, Ankra deploys the `ankracloud-cloud-provider` stack into `kube-system`: the `ankra-cloud-ccm` and `ankra-cloud-csi` charts, sharing the runtime credential's token through the Secret `ankra-cloud` (SOPS-encrypted when the stack is committed to Git). Every kubelet runs with `--cloud-provider=external`, and the controller links each node to its server as `ankracloud://<zone>/<server-id>`. The charts' own behaviour, values and annotations are documented by Ankra Cloud: [Kubernetes cloud controller manager](https://cloud.ankra.app/docs/kubernetes-ccm) and [Kubernetes CSI driver](https://cloud.ankra.app/docs/kubernetes-csi).

**LoadBalancer Services.** `ankra-cloud-ccm` gives each Service of type `LoadBalancer` an Ankra Cloud load balancer on the cluster's private network, with the nodes' private addresses as members. The networking stack's Traefik uses one, with `externalTrafficPolicy: Local` so the client address is preserved. Deleting the Service deletes its load balancer; Ankra itself never deletes one, so remove your `LoadBalancer` Services before you [terminate the cluster](#operate-it), or a load balancer still bound then stays in your Ankra Cloud account.

**Persistent volumes.** `ankra-cloud-csi` provisions Ankra Cloud storages. It installs four StorageClasses:

| StorageClass | Tier | Use |
| - | - | - |
| `ankra-standard` (default) | `standard` | General purpose, replicated |
| `ankra-maxiops` | `maxiops` | Databases and other latency-sensitive workloads |
| `ankra-hdd` | `hdd` | Bulk data |
| `ankra-local-nvme` | `local-nvme` | The compute node's own disks: fastest, single copy, pinned to one server |

Volumes are ReadWriteOnce and created in the zone of the node their pod is scheduled on.

***

## Operate it

Day-2 tasks work as on every Ankra Managed provider, from the dashboard or the API - the released CLI has no Ankra Cloud commands yet:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) - **Nodes → Node groups**
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane), [restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start) - a stop powers the servers off and keeps them with their disks; a start powers them on again
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster) - deletes the servers, the bastion, the router, the firewall rules and the network Ankra created. A network you adopted with `private_network_id` is left in place, and persistent volumes follow the retention policy, deleted only once you accept it

## Troubleshooting

| Issue | Solution |
| - | - |
| Preflight: `zone "..." is a network-only location and runs no servers` | Pick a zone that offers compute, for example `de-fsn1` |
| Preflight: `plan "..." is not available to this account` | Pick a plan from the live catalog in the wizard |
| Preflight: `template "..." is not a public Ankra Cloud template` | Use `debian-13`, `debian-12` or `ubuntu-24.04`; custom templates are not supported |
| Preflight: `kubeadm supports only Cilium on Ankra Cloud` | Choose Cilium, or switch to k3s for another CNI |
| Preflight: `network ... lives in zone ..., not ...` | Adopt a network in the cluster's zone, or let Ankra create one |
| Create fails with a quota error | Ankra Cloud enforces account quotas when servers are created; raise them in the Ankra Cloud console or pick smaller plans |
| Credential refused | Check the token in the Ankra Cloud console and [rotate it](/platform/credentials/ankra-cloud) |

## Related

* [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes)
* [Ankra Cloud Credentials](/platform/credentials/ankra-cloud)
* [Cluster settings](/platform/cluster-settings)


# Ankra Cloud Kubernetes
Source: https://docs.ankra.ai/guides/ankra-cloud-kubernetes

Provision, import, and operate Ankra Cloud Kubernetes clusters with Ankra - a control plane the Ankra team runs in Ankra Cloud, node pools with autoscaling, upgrades, GitOps, and AI-assisted operations.

Ankra Cloud Kubernetes is the managed Kubernetes service of [Ankra Cloud](https://cloud.ankra.app). The Ankra team runs the control plane inside Ankra Cloud; Ankra creates the cluster through the Ankra Cloud API, installs the Ankra Agent, and manages everything on top - node pools, Kubernetes upgrades, add-ons, stacks, GitOps, and AI-assisted operations.

> [!WARNING]
>
> **Closed beta.** Ankra Cloud as a cluster provider is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request - until it is, Ankra Cloud Kubernetes does not appear in the create-cluster dialog or among the import providers. [Contact support](/platform/support) to have it turned on for your organisation.

This page covers Ankra Cloud Kubernetes specifically. For the shared concepts across all managed providers - live options, discovery and import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes). To run kubeadm or k3s yourself on Ankra Cloud servers instead, see [Ankra Cloud Clusters](/guides/ankra-cloud-clusters).

## Prerequisites

An **Ankra Cloud credential** stored in Ankra - the same credential the self-managed clusters use. See [Ankra Cloud Credentials](/platform/credentials/ankra-cloud). No SSH key is needed: there is no bastion and no server access.

GitOps is optional: connect a repository at creation and Ankra commits the cluster's stack definitions to Git.

## Choosing a control plane

A cluster comes in one of three shapes. You choose when you create it, and the choice cannot be changed afterwards.

| | Production control plane | Development control plane | Dev cluster |
| - | - | - | - |
| Control plane | Three replicas, run by the Ankra team | One replica, run by the Ankra team | k3s on the cluster's one server |
| Highly available | Yes | No | No |
| Control-plane fee | €40 a month per cluster | None | None |
| Nodes | Node pools, billed as servers | Node pools, billed as servers | One server, billed as a server |
| Autoscaling | Yes | Yes | No |
| Use it for | Anything that must stay up | Development, test and preview environments | A small cluster to try something on |

The **production** control plane is the default. Its three replicas keep the Kubernetes API available through an upgrade or the loss of a host node.

The **development** control plane has no fee of its own: you pay for the nodes only. It is not for production. With one replica, an upgrade or a host node failure interrupts the Kubernetes API while the control plane restarts, and you cannot deploy or change anything until it is back.

A **dev cluster** is a different shape, described in [Dev clusters](#dev-clusters).

## Creating a cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick **Ankra Cloud Kubernetes** under **Cloud Managed**.
>
> **2. Credential & Zone**
>
> Select the Ankra Cloud credential, or add one inline, and a zone. Zones, versions and plans load live from Ankra Cloud.
>
> **3. Node Pools**
>
> Define one or more node pools: name, plan (with live pricing), count, labels and taints, and optionally autoscaling bounds.
>
> **4. Kubernetes**
>
> Pick a Kubernetes version or keep Ankra Cloud's default, and choose the control plane: production or development. Production is selected to begin with. The cost summary's control-plane row shows the fee of the one you chose, which is none for development.
>
> **5. GitOps (optional) & Create**
>
> Optionally connect a Git repository, then create. Ankra runs the preflight checks, creates the cluster, fetches a kubeconfig, and installs the Ankra Agent.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/managed/ankracloud_k8s \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<ankra-cloud-credential-id>",
>     "location": "de-fsn1",
>     "node_pools": [
>       {"name": "workers", "size": "<plan>", "count": 2,
>        "autoscaling": {"enabled": true, "min_count": 2, "max_count": 5}}
>     ]
>   }'
> ```
>
> `location` is the Ankra Cloud zone and `size` is the plan name. This request creates a production control plane. For a development one, add `"ankracloud_k8s": {"control_plane": "development"}` to the body.
>
> `GET /api/v1/clusters/managed/ankracloud_k8s/options?credential_id=<id>` lists the zones, versions and plans, and the control planes on offer in `control_planes`, each with its replica count and monthly fee.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider ankracloud_k8s \
>   --name my-cluster \
>   --credential-id <ankra-cloud-credential-id> \
>   --location de-fsn1 \
>   --node-pool-name workers \
>   --node-pool-size <plan> \
>   --node-pool-count 2
> ```
>
> This creates a production control plane. `--control-plane development` asks for a development one:
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider ankracloud_k8s \
>   --name my-test-cluster \
>   --credential-id <ankra-cloud-credential-id> \
>   --location de-fsn1 \
>   --node-pool-size <plan> \
>   --node-pool-count 2 \
>   --control-plane development
> ```

### Ankra Cloud Kubernetes options

Every option is optional and goes in an `ankracloud_k8s` block on the create request:

| Field | Default | Description |
| - | - | - |
| `private_network_id` | | An existing Ankra Cloud private network the nodes join |
| `network_cidr` | `10.0.0.0/24` | The RFC 1918 range of the network Ankra creates when `private_network_id` is not set. It must not overlap the Ankra Cloud public range `10.100.0.0/20`, and a range that does is refused |
| `public_ipv4` | `true` | Give the cluster's API endpoint a public IPv4 address, at €4 a month. The endpoint is IPv6 otherwise, and Ankra installs the agent over IPv4 |
| `control_plane` | `production` | `production` or `development`. See [Choosing a control plane](#choosing-a-control-plane). Any other value is refused, and so is `control_plane` together with `dev_cluster` |
| `dev_cluster` | `false` | Create a [dev cluster](#dev-clusters) on one server instead of a cluster with a managed control plane |

Without `private_network_id`, Ankra creates a network named `ankra-<cluster-name>` and deletes it again when the cluster is deleted. A network you named is never deleted.

### Limits

| Limit | Value |
| - | - |
| Clusters per Ankra Cloud account | 5 |
| Cluster name | 2 to 40 lowercase letters, digits or hyphens, starting with a letter |
| Node pools at creation | 8 |
| Node pool name | 2 to 32 lowercase letters, digits or hyphens, starting with a letter |
| Nodes per pool | 0 to 100 |

Preflight checks the name, zone, version and every pool's plan, and counts the account's live clusters, so a sixth cluster is refused before anything is created.

The control plane is chosen when the cluster is created and cannot be changed afterwards. To move from development to production, or back, create a new cluster and redeploy your workloads to it.

## Dev clusters

A dev cluster is one Ankra Cloud server running k3s. That server is the control plane, the only node and the cluster's own network edge, so there is no managed control plane and no control-plane fee: you pay for the one server at its plan price. It cannot autoscale and it joins no private network. Use it to try something out, not to run anything that has to stay up.

> [!WARNING]
>
> Ankra Cloud says this about every dev cluster, and the options call returns it as `production_warning`: "A dev cluster is one server: it is the Kubernetes API, the data store, every workload and the network edge. It has no high availability, no upgrades in place and no snapshots. Run production on a managed Kubernetes cluster."

Dev clusters are offered zone by zone. The `dev_cluster` block of the options call says where:

| Field | Meaning |
| - | - |
| `is_available` | Whether any zone offers dev clusters to your organisation |
| `zones` | The zones that offer one. `all_zones` is `true` when every zone does |
| `minimum_memory_mebibytes` | The memory of the smallest plan a dev cluster runs on |
| `ipv4_price_monthly` | The monthly price of a public IPv4 address for the server |
| `production_warning` | The warning above |

Create one from **Create Cluster** with the **Ankra Cloud** card labelled **Dev cluster on one server**, under **Cloud Managed**. The wizard limits the zones to the ones that offer dev clusters, asks for one server plan in place of node pools, and uses the latest stable Kubernetes release Ankra Cloud offers for dev clusters. Its cost summary prices the server and the public IPv4 address from the same options. Where no zone offers dev clusters, the wizard says they are not available for your organisation yet and creates a managed Kubernetes cluster instead.

From the CLI:

```bash theme={null}
ankra cluster managed create \
  --provider ankracloud_k8s \
  --name my-dev-cluster \
  --location <zone> \
  --node-pool-size <plan> \
  --dev-cluster
```

`--location` is a zone from `dev_cluster.zones` and `--node-pool-size` is the plan of the one server. `--dev-cluster` is refused together with `--autoscaling`, `--network-cidr`, `--private-network-id`, a `--node-pool-count` other than 1, and `--control-plane`.

On the API, set `ankracloud_k8s.dev_cluster` to `true` and send exactly one node pool with a `count` of 1, whose size is the server's plan. The request is refused when that pool enables autoscaling, when `cni` is set, and when `ankracloud_k8s.network_cidr` or `ankracloud_k8s.control_plane` is set.

## How Ankra connects

Ankra Cloud hands out a kubeconfig whose token expires eight hours after it is issued. Ankra never stores it: it fetches a fresh one each time it needs the Kubernetes API directly, installs the Ankra Agent with it at creation, and from then on works through the agent. For your own access, use [Ankra's kubeconfig](/guides/kubeconfig) or download one from the Ankra Cloud console.

Ankra labels the cluster in Ankra Cloud with `platform.ankra.io/managed-by=ankra-platform` and `platform.ankra.io/cluster-id=<cluster-id>`, so Ankra Cloud knows the platform already manages it.

Ankra Cloud installs its own cloud controller manager and CSI driver in the cluster, so `LoadBalancer` Services get Ankra Cloud load balancers and persistent volumes use Ankra Cloud storage, with the same StorageClasses as a [self-managed cluster](/guides/ankra-cloud-clusters#cloud-controller-and-storage). Ankra does not add a cloud-provider stack of its own.

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

* **Node pools** - add, scale and delete pools from cluster settings or the API. Labels and taints are set when a pool is created.
* **Autoscaling** - set `min_count` and `max_count` on a pool and Ankra Cloud scales it between them; clear autoscaling to return to a fixed count. See [Managed Kubernetes - day-2 operations](/guides/managed-kubernetes#day-2-operations).
* **Upgrades** - Ankra Cloud upgrades one minor version at a time; cluster settings offer the next version when one is available.
* **Deletion** - deleting the cluster waits for Ankra Cloud to release its nodes, volumes and load balancers, then removes the network Ankra created for it.

## Cost

What a cluster costs depends on its control plane:

* **Production control plane**: €40 a month per cluster, for three replicas that keep the Kubernetes API highly available.
* **Development control plane**: no control-plane fee. You pay for the nodes only. It runs one replica and is not for production, because an upgrade or a host node failure interrupts the Kubernetes API while it restarts.
* **Dev cluster**: no control-plane fee. You pay for its one server.

Nodes are billed by Ankra Cloud as servers, at their plan price, whichever control plane you choose. A public IPv4 address on the API endpoint costs €4 a month on top, on both control planes. The wizard reads the fees live from Ankra Cloud and includes them in the cost summary.

## Importing an existing cluster

Already running Ankra Cloud Kubernetes? Discover the clusters in your Ankra Cloud account and adopt them into Ankra without touching them. See [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters).

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [Ankra Cloud Clusters](/guides/ankra-cloud-clusters)
* [Ankra Cloud Credentials](/platform/credentials/ankra-cloud)


# Ankra Pipelines
Source: https://docs.ankra.ai/guides/ankra-pipelines

Connect a repository, push a commit, and watch it get built, scanned, gated and published by digest inside your own cluster - triggers, a hardened Job per stage, check runs, artifacts, and what a pull request can and cannot change.

> [!NOTE]
>
> Ankra Pipelines runs a repository's CI as Kubernetes Jobs inside a cluster you already operate through Ankra. One file, `.ankra/pipeline.yaml`, declares the triggers and the stages; a push, a pull request or a tag starts a run, every in-cluster stage runs as a hardened Job in the `ankra-ci` namespace of your CI cluster, and the result lands as an `Ankra pipeline` check on the commit and a run you can follow with `ankra pipeline logs --follow`. There are no GitHub-hosted or self-hosted runners to keep alive.

New to Ankra CI? [Get started with Ankra CI](/get-started/ankra-ci) is the short tutorial, [Starter pipelines](/guides/ankra-ci-starter-pipelines) has copy-paste pipelines per language, and the [Ankra Pipelines overview](/pipelines/overview) explains the system in diagrams: [how it works](/pipelines/how-it-works), [fast CI](/pipelines/fast-ci), [caching](/pipelines/caching), the [merge train](/pipelines/merge-train) and [AI in pull requests](/pipelines/ai-in-pull-requests). This page gets a repository connected, its first commit through a run, and the result on your pull request - then says exactly what is and is not in place yet, so nothing here claims more than the platform does today.

## Before your first run

The first four are preconditions, not preferences, and the failure modes differ: three of them stop a run before anything is dispatched, and one lets it run and then quietly strip every protected section out of it. The two vault entries at the end are not preconditions at all - they are where a run's logs and reports go if you do nothing, and why you might want somewhere else.

* **A connected repository.** The repository is connected through the [Ankra GitHub App](/integrations/github), GitLab, or [Bitbucket Cloud](/integrations/bitbucket-cloud), so Ankra receives its webhooks - and then connected to Ankra Pipelines itself, which is self-service: automatically when it backs an Ankra Application, or with one call for a bare repository (below). Pipelines are repository-scoped with an optional link to an [Application](/concepts/applications); a repository with nothing to build can have a pipeline too. A Bitbucket Cloud repository gets its webhook when you connect it to Ankra Pipelines with a Bitbucket credential, and its pull requests start runs only once that credential grants Bitbucket's `pullrequest` scope - see [Granting the pull request permission](/integrations/bitbucket-cloud#granting-the-pull-request-permission).
* **A CI cluster.** An organisation administrator sets `ci_cluster_id` in the organisation's CI settings. Without one, the staging cluster the organisation nominated for AI work is used; with neither, a provider event records `no_ci_cluster` and nothing runs.
* **An agent that advertises pipeline steps.** The CI cluster's agent runs pipeline steps in a third scheduler that is off by default - `ci_worker_count` (`AGENT_CI_WORKER_COUNT`) is `0` on every cluster until someone raises it. An agent with the scheduler off does not advertise the pipeline job names at all, so the platform refuses a step for that cluster up front instead of dispatching it. Set the count through Ankra, per cluster, and Ankra re-renders that agent's own release; never `helm upgrade` the agent by hand (below).
* **An approved definition.** A pipeline's protected sections - its `secrets`, `credentials`, `permissions`, network tier, placement, resources, timeout, caches, `services` and a `gate` stage's `with:` - carry no authority until an organisation administrator approves the definition on the default branch. Until one does, a run still executes, with **none** of them: the check run and the pull request comment carry "No administrator has approved any authority for this repository yet, so this run executes with none." Approve before the first run that needs any of it (below).
* **For check runs, `checks:write`.** Without it the GitHub App cannot create a check run, and the run's status is carried by a comment on the pull request instead - the comment says so and names the permission.
* **Somewhere to keep the objects - and you already have it.** A `scan` stage's reports, the findings a `gate` reads, the complete step log and every declared artifact are objects, and they need a bucket. An organisation with no ready [backup vault](/concepts/backup-vaults) of its own is lent one: Ankra keeps them in a vault the platform owns, under a key prefix of your organisation's own, with the same retention, the same per-object download links and the same reaper. Nothing to provision before a first run.
* **A vault of your own, when where the objects live matters.** Register one for data residency, for a bucket only your own credentials reach, or simply because cluster backups, restore points and `ankra migrate` data need one - those never use the platform's vault. A ready vault of your own takes precedence automatically, from the next step onward (below).

## Connect a repository, push, see the run

**1. Connect the repository**

Two paths, both self-service:

* **An Ankra Application.** Creating or reconciling an Application connects its repository and decides its pipeline automatically. For a genuinely new application, the setup pull request now commits `.ankra/pipeline.yaml` instead of a generated GitHub Actions workflow - unless the repository already carries an Ankra-authored workflow (which keeps healing rather than switching underneath you) or you asked for `github_actions` explicitly. A monorepo gets one file with each component's stages suffixed by its name, not one workflow per app. Ankra AI's proposal tool on the [MCP server](/platform/mcp-server) takes the same choice as `target: "ankra_pipeline"` or `"github_actions"`.
* **A bare repository** - nothing to build, or you'd rather write the file yourself:

  ```bash cURL theme={null}
  curl -X POST https://platform.ankra.app/api/v1/org/pipelines/repositories \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "github",
      "owner": "my-org",
      "name": "my-repo",
      "default_branch": "main"
    }'
  ```

  Needs `pipelines.manage`. For a **GitHub** repository, Ankra reads `.ankra/pipeline.yaml` at `default_branch` itself, through the organisation's stored Git credential, and stores a valid file as the definition of record in the same call - connect a repository that already commits one and the first webhook after connecting has something to run. GitLab and Bitbucket Cloud repositories connect the same way but need `ankra pipeline definition put` afterwards (step three, below): reading the committed file at connect time is GitHub-only today. `default_branch` defaults to `main`; `credential_name` is optional for a public repository. Connecting a repository the organisation already connected answers `409` with the existing repository's id, not a second row.

  For a **Bitbucket Cloud** repository, send `"provider": "bitbucket_cloud"`, the workspace as `owner`, the repository slug as `name`, and the Bitbucket credential as `credential_name`, public repository or not: once the connect commits, Ankra registers the repository's webhook with that credential, unless the organisation already has one on it. Connected without a credential, it gets no webhook from the connect, so unless the organisation already has one on the repository, no push, tag or pull request reaches its pipeline.

  Two more fields on the same call, both optional and both addressed by id rather than name: `application_id` links the repository to an existing Ankra Application without changing what that application deploys, and `cluster_id` overrides the organisation's CI cluster for this repository alone, instead of the organisation-wide `ci_cluster_id` (below). Disconnect a repository with `DELETE /org/pipelines/repositories/{id}` - `pipelines.manage`, `204` on success, `409` while a run is still live; it is a soft delete, so reconnecting the same identity later revives the row rather than creating a second one.

`GET /org/pipelines/repositories` lists what is connected, keyset paginated; `GET /org/pipelines/repositories/{id}` reads one. The CLI does the same with `ankra pipeline repositories connect|list|get|disconnect` (CLI v0.15.0 or later), and the portal's **Settings → Pipelines** page lists connected repositories.

**2. Optionally, give the organisation a vault of its own**

Every report a `scan` stage writes, every finding a `gate` reads, every step log archive and every declared artifact is a presigned upload into the organisation's oldest ready [backup vault](/concepts/backup-vaults) - or, for an organisation that has none, into the Ankra-managed default vault. So this step is optional: skip it and the first run still keeps its logs and its reports. Do it when the objects should live in a bucket you own, or when you want cluster backups and `ankra migrate` as well, which never use the platform's vault. One vault serves the whole organisation, and one it already uses for cluster backups serves pipelines too - if `ankra backup vaults list` already shows a `ready` row, this step is done.

Let Ankra create the bucket from a Hetzner, UpCloud, DigitalOcean or Scaleway credential:

```bash theme={null}
ankra backup vaults provision ci-artifacts --credential upcloud-main --region europe-1 --wait
```

Every argument is an override: `ankra backup vaults provision` on its own names the vault, picks the only credential it can provision from and takes that provider's usual region, printing all three before it creates anything. A Hetzner credential is the one exception - Hetzner issues Object Storage keys in its Cloud Console (**Object Storage > Manage credentials**) and its API cannot mint them, so the command prompts for the pair.

Or register a bucket you already run, on any S3-compatible service:

```bash theme={null}
ankra backup vaults create ci-artifacts --endpoint https://s3.example.com --bucket ankra-ci
```

Either way the vault has to reach `ready` before it counts: a vault still provisioning, or one whose last verification failed, has no bucket a presigned URL would reach, so the platform treats it as absent and keeps using its own default vault. Registering a vault changes nothing about what is already stored - objects stay where they were written, and are still downloadable and still reaped; the *next* step's objects go to yours. `ankra backup vaults get ci-artifacts` shows the status, and [Backups](/guides/backups) covers the rest.

**3. Choose the cluster that runs pipelines, and turn on its agent's pipeline-step workers**

An organisation administrator sets the CI cluster. Any member can read the settings; changing them answers `403` for everyone else.

```bash cURL theme={null}
curl -X PUT https://platform.ankra.app/api/v1/org/ci-settings \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"ci_cluster_id": "<cluster-id>"}'
```

The same request takes the rest of the CI settings - see [Organisation CI settings](#organisation-ci-settings). Leave `ci_cluster_id` unset and the organisation's AI staging cluster is used instead.

Then raise that cluster's pipeline-step worker count above zero - the number of pipeline steps its agent runs at once, in slots separate from its read and write pools. It is `0` on every cluster until you change it, and an agent at zero does not advertise the pipeline job names at all, so a step for that cluster is refused before it is dispatched.

```bash cURL theme={null}
curl -X PUT https://platform.ankra.app/api/v1/org/clusters/<cluster-id>/agent/ci-settings \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"ci_worker_count": 2}'
```

```bash theme={null}
ankra cluster agent ci set --workers 2 --cluster <cluster-name>
```

This is a setting Ankra owns on the agent's behalf, not a chart value you apply yourself: the write is stored, and Ankra hands it to the agent through the agent's own upgrade lane so the running release re-renders with it. An online agent new enough to take chart values picks it up immediately, an older one at its next upgrade, and an offline one when it reconnects - the response says which. Never `helm upgrade` the agent by hand to set it: Ankra re-renders that release, so a hand-set value is overwritten by the next reconcile.

`ci_storage_class` on the same call names the StorageClass for cache volumes and for a workspace claim that names none; leave it empty for the cluster default. The agent creates the `ankra-ci` and `ankra-ci-build` namespaces on first use, with their Pod Security admission labels, a `ResourceQuota` and a `LimitRange`. See the [agent Helm values](/reference/agent-helm-values) for what the release carries.

**4. Write and validate .ankra/pipeline.yaml**

This is the shape Ankra's own setup pull request commits for a new Go application - reuse it as a starting point. Every stage below now executes (see [What is in place today](#what-is-in-place-today)): `checkout` clones the commit, `test` runs your script, `build` produces a real digest in a rootless BuildKit pod, `scan` runs Trivy, Semgrep and Checkov against that digest and your source, `gate` judges what they found against your organisation's policy, and `publish` re-tags the one digest `gate` approved into your real repository. The image is never rebuilt and never a mutable tag until that last step - the same digest the whole way from `build` to the registry your application deploys from.

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "orders-api"
on:
  push:
    branches:
      - "main"
  pull_request:
    branches:
      - "main"
    fork_policy: "read_only"
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
workspace:
  size: "10Gi"
  access: "rwo"
defaults:
  image: "golang:1.26"
  timeout: "30m"
  network: "egress-https"
permissions:
  contents: "read"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "test"
    kind: "run"
    image: "golang:1.26"
    run: "go run gotest.tools/gotestsum@v1.13.0 --format testname --jsonfile test-results.json -- ./..."
    needs:
      - "checkout"
    test_results:
      - format: "go-test"
        path: "test-results.json"
  - name: "build"
    kind: "build"
    needs:
      - "test"
    build:
      dockerfile: "Dockerfile"
      platforms:
        - "linux/amd64"
      build_args:
        - "VERSION"
      provenance: true
      sbom: true
  - name: "scan"
    kind: "scan"
    needs:
      - "build"
    scan:
      scanners:
        - "semgrep"
        - "checkov"
        - "trivy"
      fail_on:
        checkov: "none"
        semgrep: "error"
        trivy: "app"
  - name: "gate"
    kind: "gate"
    needs:
      - "scan"
    gate:
      require_stages:
        - "scan"
  - name: "publish"
    kind: "publish"
    with:
      image: "harbor.ankra.cloud/orders/orders-api"
    needs:
      - "gate"
    when:
      events:
        - "push"
```

The `fail_on` map above reads per scanner and only ever tightens the gate: `semgrep: "error"` raises Semgrep's own floor to `error`, while `checkov: "none"` and `trivy: "app"` are not severities in those tools' vocabularies, so they carry no floor at all and leave the organisation's `ci_image_gate` policy to decide. Nothing a pull request writes here can loosen that policy.

Ask Ankra AI to validate it - in the portal chat or through the [MCP server](/platform/mcp-server), the `cicd_validate_pipeline_yaml` tool answers with a severity (`ok`, `warn` or `fatal`) and every violation with its key. A `fatal` definition cannot be planned; fix it before committing. A `warn` is worth reading rather than skipping past: a stage whose `kind` has no executor on this build reports one, and that stage will be skipped.

```bash theme={null}
ankra pipeline validate --application my-service
```

Reads `.ankra/pipeline.yaml` from the current directory (or the file you name), plans it for a synthetic push and a synthetic pull request, and prints the steps that would run, the stages that would be skipped and why, and every diagnostic - no repository connection required for this step alone. `--repository <repository-id>` validates for a bare repository instead of `--application`.

**5. Store the definition, commit and push**

```bash theme={null}
ankra pipeline definition put .ankra/pipeline.yaml --application my-service
git add .ankra/pipeline.yaml && git commit -m "Add the Ankra pipeline" && git push
```

`definition put` needs `pipelines.manage` and stores the definition server-side; it does not touch the repository. On **GitHub**, a run no longer needs that stored copy to be current: the planner fetches `.ankra/pipeline.yaml` at the run's own head commit and plans the run's *logic* from it, so editing the file in a pull request takes effect on that pull request's next run. On **GitLab** and **Bitbucket Cloud** the stored definition is still what runs, so keep it identical to the committed file there. Either way the run's *authority* - the protected sections - still comes from the default branch's approved definition, never from the head file (see [Logic is open, authority is closed](#logic-is-open-authority-is-closed)).

**6. Approve the definition's protected authority**

An organisation administrator does this once per definition, and again whenever a protected section changes on the default branch. The id to approve is the repository's **current default-branch** definition, and the run's own status is where it is named: the check run summary and the pull request status comment carry it inside the approve command they suggest. `ankra pipeline get <run>` reports the authority state and says where to read the id, deliberately without guessing one - the definition a run drew its *current* authority from is rarely the one waiting to be approved, and approving that would answer `409`. With the id in hand, read what you are about to grant, then approve it:

```bash theme={null}
ankra pipeline definitions get <definition-id>
ankra pipeline definitions approve <definition-id>
```

`definitions get` prints the definition's protected hash and whether it is the approved one; when it is not, it names the exact `approve` command to run. `approve` needs `pipelines.manage` and a **human actor** - a service token or agent token is refused, because approving grants whatever permissions, credentials, secrets scope and network tier the definition declares. It confirms first; `--yes` skips the prompt for scripted use. Only the repository's *current* default-branch definition can be approved, and only once: a definition the default branch has since moved past, or one already approved, answers `409`. The same act is `POST /api/v1/org/pipelines/definitions/{definition_id}/approve` on the API. In the portal, an administrator approves from **Settings → Pipelines → Pending approvals** or from the run page, and an administrator whose GitHub account is linked to their Ankra profile can press **Approve authority** on the GitHub check run. Approving re-runs the runs that waited for it.

Skipping this does not stop a run - it strips it. A pipeline whose default-branch definition declares any protected section executes with **none** of them until an administrator approves, and the check run and pull request comment say so verbatim: "No administrator has approved any authority for this repository yet, so this run executes with none." A definition that declares no protected section at all needs no approval, because there is nothing to grant.

**7. Watch the run**

The push you just made triggers a run on a connected repository. To dispatch one by hand, name the commit - and it has to be one of the repository's own. Ankra resolves `--ref` (or the repository's default branch when you name none) through the repository's own host before writing anything, and accepts your `--sha` only when it is that reference's current tip or - on GitHub, through a compare read - a provable ancestor of it. Anything else is refused by name, and so is a question the host could not answer at all. GitLab and Bitbucket Cloud have no compare read, so a commit you name there has to be the exact tip.

```bash theme={null}
ankra pipeline run --wait
ankra pipeline list
ankra pipeline logs <run-id> --step checkout --follow
```

Run from inside the checkout, the CLI reads what it can see: the application is the one bound to the repository your `origin` remote points at, and the commit is your `HEAD`. It says which it used. Name them yourself with `--application` and `--sha` when you are outside a checkout, when the repository has more than one application, or when you mean a commit other than the one in front of you:

```bash theme={null}
ankra pipeline run --application my-service --sha "$(git rev-parse HEAD)" --wait
```

`--wait` follows the run to its conclusion and exits non-zero on anything but `success`. Every stage runs for real: `checkout` clones the commit, `test` runs your script, `build` produces a digest in a rootless BuildKit pod, `scan` runs Trivy, Semgrep and Checkov against it, `gate` judges what they found, and `publish` re-tags the digest `gate` approved to `sha-<7>` in your real repository - nothing is published that was not scanned and gated first. Because `--wait` already blocked until the run concluded, the `logs --step checkout --follow` command above is reading `checkout`'s log back after the fact, not watching it live - from the CLI's next release that reads the step's complete, archived output; today it reads only whatever a fresh connection to the live relay happens to catch from an already-finished step, which for a step this far in the past is usually nothing. `--follow` earns its name against a step that is still running, which is the case whenever you check on a pipeline without also passing `--wait`. On GitHub the commit carries an `Ankra pipeline` check with a step table and a Cancel button, and on a pull request the same run populates the `pipeline` section of Ankra's one status comment; the portal's **Pipelines** section shows the same run with a timeline and an in-app log viewer, and **Settings → Pipelines** lists the repository you connected in step one.

**8. Wait on a run a push or pull request started**

Most runs are not dispatched by you: the push or pull request webhook starts them, so a CI job that has to wait for the result holds no run id. `ankra pipeline get` selects the run by what the job does know instead - `--head-sha` (the full sha), `--branch` and `--trigger` narrow it, and `--latest` takes the newest match (on its own, the pipeline's newest run). Several matches without `--latest` are refused and listed, exit `2`; no match is exit `3`.

```bash theme={null}
ankra pipeline get --head-sha "$(git rev-parse HEAD)" --trigger pull_request --latest --wait --timeout 45m
```

`--wait` blocks until the run concludes, then prints its final detail, exactly as `pipeline run --wait` does. The webhook can land a moment after the job asks, so under `--wait` or `--watch` a selection that matches nothing yet waits for the run to appear, up to `--timeout` or ten minutes when none is set. `--timeout` takes a duration and bounds `pipeline run --wait` and `pipeline rerun --wait` the same way. On GitHub Actions, a `pull_request` job's checkout is a merge commit rather than the head the run was started for, so pass `${{ github.event.pull_request.head.sha }}` there instead of `git rev-parse HEAD`.

To react while the run moves instead of only when it ends, `--watch` prints each run and step state change until it concludes:

```bash theme={null}
ankra pipeline get <run-id> --watch -o json
```

With `-o json` that is one JSON object per line: `event` (`run` or `step`), `observed_at`, `pipeline_run_id`, `run_number`, `step_key`, `status`, `previous_status` (`null` the first time a run or step is seen), `outcome`, and the whole `run` or `step` object. The first lines are the full current state, and the run's conclusion is always the last line.

With `--wait` or `--watch` the exit code is the verdict: `0` when the run succeeded, `1` when it concluded any other way or the platform could not be read, and `5` when `--timeout` ran out. A plain `get` still exits `0` whatever the outcome; add `--exit-code` to a single read to branch on it without waiting - `0` or `1` for a concluded run, `5` while it has not concluded yet.

That loop - webhook, trigger decision, plan, dispatch, a real checkout, your steps, a check run, the portal - is what the rest of this page documents in depth: the mechanics behind it, why CI belongs in your cluster at all, exactly which stage kinds execute today, what a pull request can and cannot change, and the limits every run is held to.

## How a run happens

```mermaid theme={null}
flowchart LR
    Event[Push, pull request, tag or dispatch] --> Trigger[Trigger decision]
    Trigger -->|enqueued| Plan[Plan: stages, matrix, needs, skipped]
    Trigger -->|no run| Reason[Recorded reason]
    Plan --> Dispatch[Org-fair dispatch to the CI cluster]
    Dispatch --> Job[One Job per step in ankra-ci]
    Job --> Settle[Settle: outcome, unblock, conclude]
    Settle --> Check[Check run and commit status]
    Settle --> Vault[Logs and artifacts in your vault]
```

1. **Trigger.** A verified delivery from GitHub, GitLab or Bitbucket Cloud - a branch push, a pull request opened, synchronised or reopened, or a tag - is normalised into one event and decided in a fixed order: is the repository connected, is the head trusted, is there a cluster to run on, is there a definition, does the definition's `on:` block accept the event. A dispatch from the CLI, the API or an agent goes through the same decision, after one of its own: a delivery's commit arrives proven by the provider, a dispatch's does not, so the ref it names is resolved against the repository's own host and a caller-supplied `head_sha` is accepted only as that reference's tip or a provable ancestor of it. Every answer is recorded, so a push that started nothing still says why ([the reason tokens](/guides/pipeline-reference#triggers-and-reasons)).
2. **Plan.** The planner first decides *which* definition it is planning: on GitHub it fetches `.ankra/pipeline.yaml` at the run's own head commit and uses that for the run's logic, falling back to the stored definition (with a diagnostic) if the read fails, and recording which source won; on GitLab and Bitbucket Cloud the stored definition is always what runs. A dispatch that carried its own definition (`--spec-file`, `spec_yaml`) outranks both: the override is stored verbatim on the run, and the planner and the dispatcher both render from it. Protected authority is resolved separately and never from the head file - nor from an override, which is content nobody committed. It then turns that definition and the event into the step DAG: which stages survive the trigger and stage filters, how a matrix fans out (at most 64 legs per stage), what each step depends on, which `if:` conditions can be settled now, and - for a pull request that touches a protected section - which authority the run actually executes under (see [Logic is open, authority is closed](#logic-is-open-authority-is-closed)). Nothing is dropped silently - a filtered stage is recorded with a reason code, and a run whose every stage is filtered out is recorded as concluded with outcome `skipped`. A stage whose `kind` has no executor on this build - `preview`, `agent`, `approval`, `webhook`, `automation`, `ankra`, `external` and `verify` - is skipped right here, with reason `kind_unavailable` and a sentence naming the kind and the wave that ships its executor, so a run that declares one still concludes instead of holding itself and its concurrency group open forever.
3. **Dispatch.** Steps are claimed org-fairly, never global FIFO: organisations are served in order of how many steps they already have running, and a run already at its own step cap is passed over for the next run's step rather than holding the queue (see [Capacity and concurrency](#capacity-and-concurrency)). The dispatcher resolves the cluster per step - the organisation's CI cluster, otherwise the staging cluster it already nominated for AI work - and probes that the cluster's agent advertises the `run_pipeline_step` job before sending anything. Dispatch is also the point where a step's deferred `if:` is evaluated and its remaining `${{ steps.<key>.outputs.<name> }}` and `needs.<stage>.*` references are interpolated into `run`, `env`, `with`, `image`, `working_directory` and the stage's own `outputs:`, now that the steps it waited for have concluded: a condition that reads false concludes the step `skipped`, and a reference that still cannot be resolved concludes it `infra_error` naming the field, rather than handing a container a literal `${{ }}`. Both happen *before* anything is revealed, so a step about to be skipped spends no secret. Declared secrets and credentials are resolved into one-time, per-step reveal grants at this point, never written into the payload itself.
4. **Run.** The agent renders the step's own Kubernetes objects from the signed payload - it never applies what the platform sent verbatim - and runs a hardened batch/v1 Job. A `checkout` step clones the run's commit with a pinned public git image, reading a revealed credential only if the host it is cloning from matches; a `run` step executes your script. Output streams live while the step runs; the complete log and the declared artifacts are uploaded to your backup vault when it concludes, through presigned URLs minted at dispatch. The vault is the organisation's own oldest ready one, and an organisation with none is granted uploads into the Ankra-managed default vault instead; the step's execution says which - `pipeline_artifacts: "granted"` or `pipeline_artifacts: "granted (Ankra-managed default vault)"`. Only when there is no ready vault on either side does a step get no upload grants at all, recording `pipeline_artifacts: "unavailable: This organisation has no ready backup vault, so pipeline step logs and artifacts have nowhere to be stored"` - live output is unaffected, and everything archival is lost.
5. **Settle.** The settle loop records the verdict, unblocks the steps that waited on it and concludes the run when nothing is left. Each pass re-stamps the run's own heartbeat, so a build that legitimately takes hours is no longer failed out from under you by the platform's stale-run reaper at twenty minutes. Only Ankra's own failures are retried, once; a non-zero exit is the step's verdict and is final. A concluded `build` step's digest is stamped as the application's build observation, ranked below your own CI's, so push-to-deploy, previews and rollback already read a pipeline-built image. `gate` and `publish` settle in the same pass: `gate` reads the run's own persisted scan findings against your organisation's policy, tightened per scanner by the `fail_on` each required `scan` stage declared and recording the digest it actually judged, and `publish` re-tags that digest into your real repository as `sha-<7>` - refusing outright if the build's digest is a different one, or if the gate recorded none.
6. **Report.** The `Ankra pipeline` check run (or commit status) is updated on every change, naming the authority the run executed under when it differs from what the head asked for. On Bitbucket Cloud each kind of run keeps a commit status key of its own, so a tag, pull request or dispatched run on a commit no longer overwrites the branch run's result there: `ankra/pipeline` for a push, `ankra/pipeline/pull-request`, `ankra/pipeline/tag`, `ankra/pipeline/dispatch` for a manual, API or agent dispatch, and `ankra/pipeline/schedule`, and a re-run keeps its original's key. On a pull request the same run state and the same authority sentence populate the `pipeline` section of Ankra's one status comment. The run's outcome also leaves the pull request: `pipeline_run_failed`, `pipeline_run_succeeded`, `image_gate_blocked`, `preview_ready` and `preview_failed` are ordinary Ankra notification kinds, so they reach whichever Slack, Teams, PagerDuty or webhook destination your [routing rules](/guides/notification-routing) send them to.

Deploying the result follows straight from what `publish` just did: an Ankra Application deploys the `sha-<7>` image `publish` tagged into your real repository, exactly as it would deploy an image your own CI published. A pull request gets its own preview from the same pipeline, before `publish` ever runs (`publish` fires only on `push`, per the example above) - the application's preview deploys the digest `build` produced for that head, by digest, never a mutable tag, and GitLab and Bitbucket Cloud pull requests now get previews the same way GitHub ones always could. The [generated GitHub Actions workflow](#bring-your-own-ci-github-actions) still works and is still what an application with no pipeline connected uses; nothing forces you off it.

> [!NOTE]
>
> **A build you start by hand does not go through the gate.** The two paths publish to different places, deliberately:
>
> * a **pipeline** build stages the digest under `ankra-ci/<application>/<component>`, and `publish` re-tags it into `<application>/<component>` only after `gate` has judged it;
> * **`ankra application build start`** publishes straight to `<application>/<component>` - no `scan`, no `gate`.
>
> So a manual build writes directly to the repository your Application deploys from. That is what it is for: it is the recovery route for when the pipeline itself is broken, which is exactly when the gated path is unavailable. Use it knowing the image has not been scanned or gated, and let the pipeline publish anything you intend to keep.

### Which component a build belongs to

A `kind: build` stage of an application's pipeline belongs to one of the application's components, and that decides where it pushes and where `publish` re-tags it. Ankra reads it in this order:

1. **`build.component`**, when the stage declares it. The value is the name of a component the application records.
2. **The stage name**, otherwise: a stage called `build-<component>` belongs to that component.
3. **The application's one component**, for a single-component application, whatever the stage is called.

Declare `build.component` when one component has more than one build, or when you want to name a stage for what it builds. A typical case is a component that ships both a container image and a release bundle:

```yaml theme={null}
stages:
  - name: build-portal          # release bundle for host deploys, attributed by its name
    kind: build
    build:
      bundle:
        path: dist/portal
        manifest: deploy/portal/ankra-release.yaml
  - name: build-portal-image    # container image for Kubernetes, attributed explicitly
    kind: build
    build:
      component: portal
      dockerfile: portal/Dockerfile
      context: portal
  - name: build-node-agent      # release bundle that belongs to no component
    kind: build
    build:
      bundle:
        path: dist/node-agent
        manifest: deploy/node-agent/ankra-release.yaml
```

Each stage pushes to its own repository, so an image and a bundle of the same commit never overwrite each other's `sha-<7>` tag:

| The stage builds | It publishes to |
| - | - |
| an image of a component | the component's repository, `<application>/<component>` |
| a release bundle of a component | the component's bundle repository, `<application>/<component>-bundle` |
| a release bundle that belongs to no component | `<repository>/<stage suffix>`, for example `<repository>/node-agent` |

An image has to belong to a component, because a deploy of the application only reads component repositories. A pipeline that declares no `build.component` anywhere keeps working exactly as before. In a repository with no linked application, `build.component` has no effect, and every stage still publishes as `<repository>/<stage suffix>`.

`ankra pipeline validate` checks the stages against the application before a run. It reports a stage that belongs to no component, a `build.component` the application does not record, and two stages that would publish to the same repository. That last finding is fatal when both stages always run, because each run's commit tag would be overwritten by whichever stage publishes last, and a warning when one of them runs only under a condition. The components an application records come from its [`.ankra/ankra.yaml`](/reference/application-descriptor#components) when it declares them. When a run reaches a stage it cannot attribute, the step concludes `step_refused`, and the message lists the components the application records.

### Monorepo: PR-only checks, full builds on push

A monorepo usually wants a pull request to check only the components it touches, while a push to the default branch builds everything. Write **one stage per component**, and give each stage an [event-scoped `when`](/guides/pipeline-reference#event-scoped-filters) block: the pull request filters on paths, and the push does not. Do not duplicate stages per event.

```yaml theme={null}
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

stages:
  - name: checkout
    kind: checkout
  - name: test-web
    kind: run
    image: node:22
    run: pnpm -C web test
    needs: [checkout]
    when:
      pull_request:
        paths: ["web/**", "packages/ui/**", ".ankra/**"]
      push: {}
  - name: test-api
    kind: run
    image: golang:1.26
    run: go test ./...
    working_directory: api
    needs: [checkout]
    when:
      pull_request:
        paths: ["api/**", "go.work", ".ankra/**"]
      push: {}
  - name: report
    kind: run
    image: alpine:3
    run: ./scripts/summarise.sh
    needs: [test-web, test-api]
    if: always()
```

A pull request that touches only `web/` runs `checkout` and `test-web`. `test-api` is skipped as `path_filter` and recorded as skipped on the run. A push to `main` runs every stage. Put the pipeline file (`.ankra/**`) in each list so a change to the pipeline checks everything it touches.

* A pull request's changed files are read from your provider when the run is triggered, up to 300 paths. When they cannot be read, or the change is larger than that, no stage is skipped for its paths, and the run's `paths_unverified` says why.
* A stage that needs a component stage keeps the usual rule: it is skipped when that stage is left out. To run it anyway, name the stage in [`skippable_needs`](/guides/pipeline-reference#fields-common-to-every-stage), so it waits on what the skipped stage waited on, or give it an `if:` with a status function such as `always()` (above), so its condition decides and `needs.test-api.result` reads `skipped`.
* Check the shape before you commit it. `ankra pipeline validate --changed-file web/app.ts` prints each stage against push and pull request, so you can see the plan for that change.
* Write each list once. When several stages share a list, or every list carries `.ankra/**`, name it under [`path_sets:`](/guides/pipeline-reference#path-sets) and write `{set: <name>}` where the list was, for example `path_sets: {pipeline: [".ankra/**"], web: ["web/**", "packages/ui/**", {set: pipeline}]}` and `paths: [{set: web}]`.

### Affected-only stages: skip what a change did not touch

A change that touches only `web/` should not wait for the API's tests, and it should still build, scan and gate, and on a push publish. Give each component's test stage `paths:`. A stage with `paths:` is **affected-only**: when no changed file matches, it is skipped as `path_filter` and the stages that need it run without it, waiting on what it waited on.

```yaml theme={null}
stages:
  - name: checkout
    kind: checkout
  - name: test-web
    kind: run
    image: node:24
    run: pnpm -C web test
    needs: [checkout]
    paths: ["web/**", "packages/ui/**", ".ankra/**"]
  - name: test-api
    kind: run
    image: golang:1.26
    run: go test ./...
    working_directory: api
    needs: [checkout]
    paths: ["api/**", "go.work", ".ankra/**"]
  - name: build
    kind: build
    needs: [test-web, test-api]
    build:
      dockerfile: Dockerfile
  - name: scan
    kind: scan
    needs: [build]
    scan:
      scanners: [semgrep, trivy]
  - name: gate
    kind: gate
    needs: [scan]
    gate:
      require_stages: [scan]
  - name: publish
    kind: publish
    needs: [gate]
    with:
      image: registry.example.com/acme/shop
    when:
      events: [push]
```

A push that changes `web/app.ts` runs `checkout`, `test-web`, `build`, `scan`, `gate` and `publish`; `test-api` is skipped and `build` waits on `test-web` and `checkout`. A pull request with the same change runs the same stages except `publish`, which runs on pushes only. A push that changes only `README.md` skips both tests and still builds and publishes; that is deliberate here, because the image is built from the whole repository either way. If a documentation change should not publish, give `build` and the stages after it a `when.paths` filter, which skips them together. A change to `.ankra/pipeline.yaml` runs everything.

* **`paths:` or `when.paths`.** `when.paths` skips the stages behind a stage it leaves out, so a filtered test stops the publish behind it; that is the right rule for a component's whole chain (its build, scan, gate and publish skipped together), and it is what the generated monorepo pipeline uses. `paths:` is for a stage whose absence should not hold anything back. One stage declares one of them, never both.
* **Every event.** `paths:` applies to pushes as well as pull requests, so a push to `main` also runs only the affected tests. For "pull requests check what they touch, pushes check everything", use the [event-scoped `when`](#monorepo-pr-only-checks-full-builds-on-push) recipe with `skippable_needs`.
* **What it refuses.** A stage that is left out produced nothing, so `ankra pipeline validate` refuses (`pipeline_paths:`) a stage that reads its outputs, a `build` that another stage needs (what needs a build reads its image), a `checkout`, `gate` or `approval` with `paths:`, and a scan a gate names in `require_stages`. It warns about an affected-only scan (a change outside its paths is not scanned) and an affected-only `deploy`, `publish` or `preview` that another stage needs.
* **When the change cannot be seen** (no change list, or more than 300 files), no stage is left out, and the run's `paths_unverified` says why.
* Check a change before you commit it: `ankra pipeline validate --changed-file web/app.ts` prints which stages run and which are skipped.

### Affected from the dependency graph: `affected:`

Path globs have one blind spot: a package a stage's tests import from somewhere else in the repository. `test-api` lists `api/**`, a change to `libs/auth` that `api` imports matches nothing, and the tests that would have caught the break are skipped. `affected:` names the packages instead of the files, and Ankra follows their imports.

```yaml theme={null}
stages:
  - name: checkout
    kind: checkout
  - name: test-api
    kind: run
    image: golang:1.26
    run: go test ./...
    working_directory: api
    needs: [checkout]
    affected:
      go: ["./..."]
    paths: ["migrations/**"]
  - name: test-web
    kind: run
    image: node:24
    run: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @acme/web... test
    needs: [checkout]
    affected:
      pnpm: ["@acme/web"]
  - name: build
    kind: build
    needs: [test-api, test-web]
    build:
      dockerfile: Dockerfile
```

A stage with `affected:` runs when a changed file is in the dependency graph of what it names, its tests included, or matches its `paths:`. Otherwise it is skipped as **not affected**, and the stages that need it run without it, exactly as for an affected-only stage left out by its `paths:`.

* **`go`** names Go packages the way the stage's own `go test` does: `./...` and `./internal/api` are read from the stage's `working_directory`, and an import path such as `example.com/shop/libs/...` works too. Ankra reads every `go.mod` in the repository, so a module another one pulls in through a local `replace` directive counts. A change to `go.mod`, `go.sum` or `vendor/` reaches every package of that module.
* **`pnpm`** names workspace packages by name (`@acme/web`) or by directory (`./apps/web`). A dependency on another workspace package, by name, `workspace:` alias or `file:` path, is followed. A change to a file at the repository root, such as `pnpm-lock.yaml`, the root `package.json` or `pnpm-workspace.yaml`, or to a pnpm patch (any file under `patches/` and any `.patch` file), reaches every pnpm stage. Documentation and Go files at the root do not: `*.md`, `LICENSE`, `CHANGELOG`, `.gitignore`, `.gitattributes`, `*.go`, `go.mod`, `go.sum`, `go.work` and `go.work.sum`.
* **`paths:` beside `affected:`** adds files no import graph sees: migrations, fixtures a test opens by path, a script the stage runs. A matching file runs the stage.
* **Where the graph comes from.** The run's checkout step reads the graph of the exact commit it checked out, in a few seconds, and records an answer for each stage. Nothing is cached and there is no extra step. The planner decides only what it can without the code: a change list it could not read in full, a change to `.ankra/pipeline.yaml` or a matching `paths:` glob runs the stage, and a change of no files leaves it out.
* **A skip needs an answer.** The stage is skipped only when the checkout answered that no changed file reaches it. No answer at all (a pattern that names nothing, an analysis that failed or took over two minutes) runs it, and the checkout's log says why. A pipeline with no checkout stage never reads the graph: its `affected:` stages run on every change, `ankra pipeline validate` warns about it (`pipeline_paths:`), and the run's plan records it (`plan_paths:`).
* **A skip never waits for capacity.** A not-affected stage is concluded as soon as the checkout has answered, without waiting for a free CI slot on a busy cluster, and the stages that need it start as soon as they have one of their own. The time it saved is recorded with reason `not_affected`.
* **Promotion.** A merge that [promotes](/guides/pipeline-reference#promote-a-tested-image-instead-of-rebuilding) the pull request run's image counts a stage that run skipped as not affected, when the merge changes no file that run's graph was not asked about. Otherwise the merge builds in full and reads the graph itself.
* **The same rules as `paths:`.** `affected:` makes a stage affected-only, so it is refused where a skip would be unsafe: a stage whose outputs another reads, a `build` another stage needs, a `checkout`, `gate` or `approval`, a scan a gate judges. A false `if:` is still the condition's own skip and skips what needs the stage.
* Check a change before you commit it: inside your checkout, `ankra pipeline validate --changed-file libs/auth/token.go` reads the same graph from your working tree and shows which stages the change reaches.

### Newest commit wins

A `concurrency.group` decides which runs serialise. `cancel_in_progress` decides what happens when a newer one arrives: with it, the new commit supersedes the run it replaces; without it, the new run waits for the older one to finish - and on a group that varies per branch, that is a branch queueing behind itself while the older commit's run keeps your step slots.

```yaml theme={null}
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
```

Every pipeline Ankra generates ships exactly that. A definition you wrote keeps whatever it says - Ankra never flips the flag for you, because that would cancel runs your own file says should finish. What Ankra does instead is tell you:

* `ankra pipeline validate` (and `ankra application pipeline validate`) reports `pipeline_concurrency_queues_behind:` at severity `advice`, naming the group and the one line that changes it. Advice never blocks a run and never fails the command.
* A queued run whose `Waiting:` line names an older run of the *same* branch or pull request that will not be superseded carries the same recommendation. A holder on another branch does not - that is the group serialising across branches, which is what a group is for.
* A pipeline [converted from a GitHub Actions workflow](/guides/migrate-from-github-actions) keeps the workflow's own queue-behind behaviour, with a conversion note recommending the flag for a per-branch group on a `pull_request` trigger.

A branch whose every commit must end in a verdict, such as the default branch that deploys or writes the caches pull requests read, wants the opposite trade from a pull request. You don't need two files for that: each flag can be one expression that is settled per run, for example `cancel_in_progress: "${{ event.kind != 'push' }}"` with `cancel_queued: "${{ event.kind == 'push' }}"`. See [A concurrency policy per event](/guides/pipeline-reference#a-concurrency-policy-per-event).

Superseding is a soft stop, not a failure. The older run concludes as cancelled and is shown as **Superseded** in grey rather than red, the commit status it leaves on GitHub, GitLab or Bitbucket is neutral rather than a failed check, and no failure notification is raised for it - attention follows the newest run of the branch.

## What a pull request gets

A connected pull request carries one comment, not several: a run, its preview and Ankra AI's own review each write into that comment's own `pipeline`, `preview` and `review` sections in place rather than posting separately - see [One status comment per pull request](/changelog#one-status-comment-per-pull-request). The pipeline section is the run's own state, plus the authority sentence whenever the run executed under anything but the plainly approved definition; the preview section is the throwaway environment deployed from the run's own digest; the review section is Ankra AI's verdict on the diff.

### The review reads your pipeline, not just GitHub Actions

Ankra's pull request review used to read a GitHub check run for its "is this commit passing" signal, so a repository already running on Ankra Pipelines still got a review that could not see its own pipeline. The review now resolves the newest pipeline run of the reviewed commit first, and falls back to GitHub's own check runs only for an application whose real build authority is still its own CI or the generated workflow, or for a head no pipeline run has touched yet. When a pipeline run answers, the review's prompt carries a bounded set of facts about it, each independently sourced so an absent one never reads as a clean one:

* the failing step's name, kind and error message, when the run is failing - not its log, which stays behind `ankra pipeline logs`
* the run's scan findings, by tool and severity, with the highest-severity individual findings named
* the `gate` step's own verdict and blocking count, once one has concluded
* the `build` step's reported image digest, once one has concluded
* the authority sentence, when the run executed under anything other than the plainly approved definition

The branch **Code review** lane (no pull request involved, see [Application AI Settings](/platform/application-ai)) does not read this block - only the pull request review does.

### A human can say "merge when green"

Mention **`@ankraai merge when green`** in a pull request comment, ask Ankra AI in chat, or call the API, and Ankra records the request and watches the pull request, merging it (squash) the moment every condition holds:

* the requester is an active member of your Ankra organisation holding **`pipelines.operate`**, and the binding's [AI mode](/integrations/github#ask-ankra-in-a-comment) is **Agent** - in **Ask** mode the request is refused, naming the setting to change
* the GitHub login that commented is linked to that member through an **OAuth-verified** identity. A login claimed by hand, or auto-filled from an Auth0 GitHub sign-in, proves the account exists and not that the commenter owns it, so it no longer counts as verified; the refusal says to link GitHub again. A service principal is refused outright - merging is a human act
* the requester still holds `pipelines.operate`, is still an active member and is still OAuth-verified when the sweep actually merges, not only when the comment was written. A request can wait up to 24 hours, and an administrator can revoke the permission inside that window
* the pull request's head is not a fork
* the newest pipeline run for the head concluded successfully, and its `gate` step, if the definition declares one, passed
* the run executed under plainly approved authority - one that fell back to an earlier approval, or none, is refused rather than merged under it
* Ankra's own review has not requested changes on that exact commit
* no human reviewer's most recent review is **Changes requested** - unlike the AI review's check, this one is not scoped to the current commit, so a changes-requested left on an earlier push still blocks until the same reviewer clears it with a later review

The request expires 24 hours after it is made, and a new push to the pull request invalidates it. Every refusal is posted once, naming the exact condition that failed. This works on GitHub only today: a request against GitLab or Bitbucket Cloud is accepted and then refused, because neither provider adapter reports the capability to merge yet.

### The merge train: test every pull request as it will merge

A pull request that is behind its base branch merges as a tree nobody tested: the pull request's own run tested its head, not its head on top of everything that landed since. Turn on the **merge train** for a repository and Ankra tests each pull request **as the commit its merge will produce** before it merges it - the way GitLab's merge trains work, and without GitHub's merge queue, which Team-plan private repositories do not have.

```bash theme={null}
ankra pipeline train enable --application orders-api            # pipelines.manage; --max-cars 3 to test three at once
ankra pipeline train add 412 --application orders-api           # pipelines.operate; --head-sha pins the commit you reviewed
ankra pipeline train list --application orders-api              # the train in order, and what recently left it
ankra pipeline train remove <entry-id> --application orders-api
ankra pipeline train front 412 --application orders-api         # CLI 0.47.0+; organisation administrators only
```

For each pull request in the train, Ankra writes a **car**: the pull request squashed onto the base branch - or onto the car ahead of it, when more than one is tested at once - exactly as GitHub's squash merge will produce it, on a branch of its own (`ankra-merge-train/<entry>`). A pipeline run tests that commit. It is planned as a pull request into the base branch, so it runs only when the pipeline declares `on.pull_request` and its `branches` match the base branch, `when.events: [pull_request]` stages run and push-only `publish` and deploy stages do not, under the base branch's approved authority. When the car's run passes and the base branch has not moved, Ankra squash-merges the pull request through GitHub's own merge - branch protection, required reviews and required checks apply exactly as for a person's merge, and Ankra never pushes to or force-pushes the base branch.

Because the merge is exactly the tree the car tested, a definition whose `publish` declares [`promote_from: pull_request`](/guides/pipeline-reference#promote-a-tested-image-instead-of-rebuilding) publishes the car run's tested image on the merge instead of building and testing it again: merge to published is a re-tag.

What happens when something moves:

* **A car fails.** The pull request leaves the train with the failing run linked; every car behind it, which included it, is rebuilt without it. Each car tests everything ahead of it, so the pull request that failed is the one that broke, with no bisection.
* **Somebody merges around the train.** Every car built on the old base branch head is rebuilt on the new one, and nothing is merged onto a base its car did not test.
* **The pull request is pushed to, retargeted or closed.** It leaves the train: the train merges the head a person put in it, never one that arrived later.
* **GitHub declines the merge** - usually because the pull request's own required check is still running. The car waits, passed, and the merge is retried every pass, while the cars behind it keep building and testing. After three hours it leaves the train with GitHub's reason, or after 15 minutes when GitHub says a required check is failing, because a failed check does not turn green by waiting. See [Merges GitHub declines](/pipelines/merge-train#merges-github-declines).
* **A fork.** Refused, as for merge when green.
* **An administrator moves a pull request to the front.** With CLI 0.47.0 or later, `ankra pipeline train front` puts it ahead of every car that is still queued, building or testing; cars that already passed or are being merged stay ahead. Every car it passes is rebuilt on top of it, so those pull requests wait longer. That is why only an organisation administrator can do it: being the pull request's author or having write access is not enough.

Ankra posts an **Ankra merge train** check on every pull request it holds, and concludes it `success` only immediately before it merges. Make that check required on the base branch, and every merge goes through the train.

The train writes with a GitHub App token minted for that one repository with only `contents`, `pull_requests` and `checks` permissions. It works on GitHub only today.

### Chat watches a run, and a failed build gets a fix

Ask Ankra AI to watch a run - or dispatch one, which registers the watch itself - and the `watch_pipeline_run` tool wakes the same conversation the moment it concludes, with the failing step, a bounded tail of its log, the findings and the gate verdict already in the prompt. Separately and unattended, a failed `build` step (never `infra_error`, a stranded step, or one a protected policy refused - only a genuine script failure) on a **direct push** to the tracked branch, in **Agent** mode, dispatches the same auto-fix mission the generated GitHub Actions workflow's own failed-build webhook already dispatches, with a log excerpt as evidence. A failed build on a **pull request** never gets an unattended commit from this lane, in either mode - it gets its diagnosis (the failing step, its error class, a log excerpt) posted into the status comment's `pipeline` section instead, pointing at Agent mode's **Propose a fix** on the [pull request review](/integrations/github#ask-ankra-in-a-comment) as the actual route to a fix.

## Why CI belongs in your cluster

The generated GitHub Actions workflow Ankra Applications ship with works, and keeps working - see [Bring your own CI](#bring-your-own-ci-github-actions) below. Ankra Pipelines exists because of what that model cannot fix:

* **Runners are a second fleet.** GitHub-hosted runners are shared and rate limited; a self-hosted runner pool is one more set of machines to size, patch and pay for. A pipeline step is a Job on nodes you already have, scheduled under the quota and node selectors you set, and never at the expense of a deploy - the agent runs pipeline work in its own worker pool.
* **Credentials live in CI secrets.** A workflow needs registry logins, cloud credentials and deploy tokens as repository secrets, copied per repository and readable by any workflow that names them. In a pipeline definition those are *references* the platform resolves and delivers as a one-time, per-step reveal - never written into a job spec or a log - and the sections that grant them are protected: a pull request can rewrite what a pipeline does, and cannot widen what it may touch.
* **Publish happens before the gate.** A workflow that pushes an image and scans it afterwards has already published a vulnerable image by the time the scan fails. The pipeline vocabulary separates `build`, `scan`, `gate` and `publish` so that nothing is published that the gate did not pass - enforced end to end today: a `publish` step refuses by name when its run has no successful `gate` step immediately upstream, and it re-tags only the exact digest that gate evaluated.
* **The evidence is somewhere else.** Run history, logs, scan artifacts and the check on the commit all lived on the CI provider. A pipeline run is an Ankra object: `ankra pipeline get`, live logs, artifacts in a backup vault - the organisation's own, or the Ankra-managed default one - and the same status on GitHub, GitLab or Bitbucket.

## What is in place today

Ankra Pipelines is landing in pieces, and this page is honest about the line. Everything in the first list is on the platform and the agent now; everything in the second is not, and is described in [What comes next](#what-comes-next).

**In place**

* The definition: `.ankra/pipeline.yaml` (`apiVersion: ankra.io/v1`, `kind: Pipeline`) with its parser, validator and dry-run planner - see the [pipeline.yaml reference](/guides/pipeline-reference).
* Conversion of an existing GitHub Actions, GitLab CI, Bitbucket Pipelines or CircleCI definition into a pipeline, from chat or the MCP server - see [Migrate from GitHub Actions](/guides/migrate-from-github-actions).
* The organisation's CI settings (which cluster runs pipelines, parallelism, image allow-list, retention, the image gate) and its pipeline policy (the authority ceiling an administrator sets). The image gate is no longer only a setting: `gate` steps (below) evaluate every run against it.
* **Connecting a repository**, with an optional link to an application and a CI-cluster override, and **disconnecting** one. `POST /org/pipelines/repositories` connects a bare repository and, on GitHub, reads its committed `.ankra/pipeline.yaml` as the definition of record in the same call; `DELETE /org/pipelines/repositories/{id}` disconnects it, `409` while a run is still live. An Ankra Application connects and decides its own repository automatically on create and on every reconcile. A new application's setup pull request commits `.ankra/pipeline.yaml` by default instead of a generated workflow.
* **Migrating an existing application onto a pipeline with one call** - see [Migrate an existing application](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call).
* The runs API and the `ankra pipeline` commands: dispatch, list, get, cancel, re-run, live step logs, artifacts, the stored definition, schedules.
* Triggers from push, pull request and tag deliveries on GitHub, GitLab and Bitbucket Cloud, deduplicated across redeliveries, with a recorded reason whenever nothing runs. A Bitbucket Cloud push that updates several branches or tags at once starts each branch's and each tag's pipelines, and a Bitbucket pull request's abbreviated head commit is resolved to the full commit through the repository's credential before its run is created; a head that cannot be resolved starts no run. A **private GitLab repository** builds through the organisation's stored source credential the same way GitHub and Bitbucket Cloud ones do, and a GitLab project under a **nested group** (`group/subgroup/project`) resolves to a clone URL instead of being refused by the owner grammar.
* **A stage kind nothing can run is skipped, not left pending.** The kinds this build has no executor for - `preview`, `agent`, `approval`, `webhook`, `automation`, `ankra`, `external` and `verify` - now report a validation **warning** naming the stage, its kind and the wave that ships its executor (severity `warn`, so the pipeline still plans and every other stage still runs), and the planner skips exactly those stages with reason `kind_unavailable`. A run that declares one concludes on its own; before this it sat `pending` forever, holding its concurrency group with it. A `pending` step whose run has outlived the sum of every step's `timeout` is additionally reaped as `infra_error` / `step_stranded`, so a step that stranded for a reason no static check can see - a cluster that never resolved, an agent that never advertised support - cannot pin a run open either.
* **`uses:` is refused by name, at validate time.** Any `uses:` reference - `ankra/*`, `custom_tool/*` or `repo:<owner>/<name>@<ref>#<path>`, however it is spelled - is fatal with one sentence, "Reusable steps are not available yet; write the step as `run:`", until the step library ships. That is deliberately louder than the old behaviour, where a `uses:` stage validated and then failed at dispatch with an error that read as "you forgot to write a script".
* **Step outputs and deferred conditions are resolved at dispatch.** A stage's `if:` that depends on a step's result, and every `${{ steps.<key>.outputs.<name> }}` or `needs.<stage>.*` reference in `run`, `env`, `with`, `image`, `working_directory` and `outputs:`, are evaluated once the steps they wait on have concluded - a false condition concludes the step `skipped` before any secret is revealed, and a reference dispatch cannot resolve concludes it `infra_error` naming the field rather than passing a literal `${{ }}` into a script.
* **`on_failure` and `finally` stages run when their names say.** An `on_failure` stage runs after the main stages have all concluded and only when one of them failed; after a green run it is skipped with its reason. A `finally` stage runs after everything before it has concluded, whatever the outcome, and also after a run that had started is cancelled (`ankra pipeline cancel --force` skips it). See [Failure and cleanup stages](/guides/pipeline-reference#failure-and-cleanup-stages) for the exact rules.
* **In-cluster execution of `checkout` and `run` stages** on the organisation's CI cluster: a hardened Job per step in `ankra-ci`, a per-run workspace volume, cache volumes, service sidecars, network tiers, resource ceilings, timeouts, live logs, and one automatic retry of Ankra's own failures. `checkout` clones with a pinned public git image, a shallow fetch of the exact commit with a fallback to fetching its ref, and refuses an `lfs:` request by name rather than silently checking out pointer files.
* **Caches survive between runs, inside their own trust scope.** A stage's `cache:` block resolves to the same PersistentVolumeClaim on every run that declares the same key, scoped to the repository, cluster, cache path **and the trust of the run resolving it** - the second run's `test` stage mounts what the first run's left behind, not an empty volume. A miss on the exact key that matches a `restore_keys` prefix restores the most recently used claim under that prefix instead of starting cold, the same semantics as GitHub Actions' own cache action, and that prefix search stays inside the caller's own scope too. Retention is unchanged by any of this: a claim nothing has resolved to for `ci_cache_retention_days` (below) is still deleted by the same sweep, per claim.
* **A fork's run resolves no shared cache at all, and a branch never resolves the default branch's.** Two holes, closed together. A pull request from a fork that runs restricted - the ordinary `fork_policy: read_only` case - is refused a shared cache at dispatch, on the same predicate that already withholds its secrets and credentials: every declared cache degrades to the pod-lifetime volume a cluster with no usable StorageClass already gets, and the step's execution metadata carries `pipeline_caches: "caches are not shared with fork runs"` so an operator can see why the build was cold rather than guessing. Such a step never reaches the cache store at all. Separately, every claim now carries a **trust scope**: `default_branch` for a run on the repository's own recorded default branch, `branch` for everything else - a feature branch push, a pull request (fork or not), a tag, a manual dispatch of a non-default ref. The two scopes never share a claim, and neither an exact-key hit nor a `restore_keys` prefix match crosses between them, so a less-trusted ref can no longer poison what a production build restores. It is deliberately coarser than per-branch isolation: the threat is an untrusted ref writing into what a trusted one reads, not one feature branch reading another's warm cache. **Claims that existed before this deploy were backfilled into `branch`, the untrusted scope** - nothing on a row records which run wrote it, so the true value cannot be recovered, and defaulting the other way would have carried the hole forward for every cache written before the fix. The cost is one cold build per cache key on your default branch, once.
* **A restricted fork run is budgeted, not only restricted.** It is clamped to at most **8 matrix legs per stage**, a **60-minute timeout per step**, **2 CPU and 4Gi of memory per step**, **no sidecar services**, **no cache volumes** and **256 MiB of artifacts and logs across the whole run** - fractions of the platform-wide ceilings of 64 legs, 6 hours, 8 cores, 32 GiB and 2 GiB, because a drive-by pull request triggers this with nobody having reviewed it first. Matrix legs, timeout, compute and sidecars are clamped in the **planner**, so the plan `ankra pipeline validate`, the dry run and the pull request's status comment render is the run that actually executes, rather than one silently rendered smaller at dispatch; caches are refused at dispatch, and the artifact budget bounds what the run is granted, from the sizes its steps declare. The matching ceiling on what actually *arrived* - the one number a step cannot lie about - is written into the artifact store but has no settle lane calling it yet, so today the budget is enforced on the grant rather than on the upload. A `plan_fork_budget:` diagnostic states the ceilings once per run, plus one more for each stage that actually hit one, and a declared quantity the planner cannot read is clamped rather than given the benefit of the doubt. An organisation's own policy may lower these numbers further; nothing raises them for a fork.
* **`build` produces a real digest.** A rootless BuildKit pod in its own `ankra-ci-build` namespace resolves its own builder, source and push target at dispatch and pushes the image it builds, by digest, to the organisation's CI staging repository; a bare repository with no application link, or a component with no resolvable registry, gets a named refusal instead of a guess. `provenance: true` and `sbom: true` ask BuildKit to attest the digest it pushes.
* **Ankra platform builders build when your cluster cannot.** When the CI cluster cannot build, the organisation set `ci_build_fallback: platform_builders`, **and** Ankra has granted the organisation platform builds, a `build` step runs on Ankra platform builders instead - the same staging-repository push and the same `scan`/`gate`/`publish` downstream, with the step's `executor` recorded as whichever lane actually ran it. What "cannot build" covers, how to confirm and request the grant, and what a fallback build looks like from your side are all in [Ankra platform builders](#ankra-platform-builders) below. An application that publishes to [a registry you operate yourself](/concepts/applications#using-your-own-registry) is pushed by this lane with the push robot Ankra minted for it there, exactly as the in-cluster build is.
* **`scan` runs three tools for real, one step per tool.** Trivy (filesystem, a CycloneDX SBOM, and - once a build produced one - the image itself), Semgrep and Checkov, each from a pinned, digest-referenced public image the organisation's own `ci_allowed_image_prefixes` cannot turn off, writing the reports `gate` and the application's **Security** tab both read. `with.semgrep_config` names the registry packs to run (`p/default p/docker …`); undeclared, Semgrep runs its own `--config=auto`.
* **`gate` judges what `scan` found, and `scan.fail_on` is part of the judgement.** It reads the run's own persisted findings against the organisation's `ci_image_gate` policy (below), which a `gate` stage's own `with:` may only tighten, never loosen; a declared scanner that recorded nothing fails the gate by name rather than passing as clean. Each required `scan` stage's own `fail_on` is folded in on top, per scanner and **tighten-only**: a pull request head may add scrutiny to its own pipeline, never remove the organisation's. A `fail_on` value that is not that scanner's own severity vocabulary at all - Checkov's `none`, a Trivy image-gate word such as `app` - carries no floor rather than the loosest one.
* **`publish` re-tags only the digest `gate` approved, and proves it.** A `publish` step refuses by name when its run has no successful `gate` step; otherwise it re-tags the exact digest `build` pushed to staging as `sha-<7>` in the application's real repository - never rebuilt, never a different digest than the one `scan` and `gate` judged. The gate now records the digest it actually judged on its own step outputs, and `publish` refuses when the build's digest is anything else - **including when the gate recorded none at all**, because "no record" is unknown, not agreement. Before this the guarantee rested on ordering alone: a successful gate existed upstream, so surely it had judged this image.
* **`deploy` rolls a release out to your own hosts.** A `kind: deploy` stage releases the signed release bundle a `publish` stage of the same run produced to the active host targets of its `environment`: machines outside Kubernetes that run `ankra-host-agent` and connect outbound only (see [`ankra targets`](/reference/cli/targets)). The platform settles the step from what each host reports, and [`ankra deployments`](/reference/cli/deployments) shows how every host fared. The stage's `environment` and `deploy` block are protected, a pull request or fork run never deploys (`deploy_untrusted_event`), and the step refuses an artifact this run did not publish. It does not deploy to a Kubernetes cluster: an application's own push to deploy does that. See the [`deploy` row](/guides/pipeline-reference#stages) of the reference.
* **A monorepo's components are tracked separately.** A `publish` step resolves the `build` and `gate` steps carrying its own stage suffix rather than whichever succeeded first, so `publish-web` can no longer re-tag `api`'s digest into web's repository, and a stage name following neither convention is refused by name instead of guessed at. A `scan` stage honours `working_directory`, so a component's scan reads the tree its build and test stages do rather than the whole checkout. Build observation is recorded per component, with only the primary component also moving the application-level record, so push-to-deploy, previews and rollback keep converging on the image they always did.
* **A run plans from `.ankra/pipeline.yaml` at its own commit** (GitHub). The planner fetches the file at the run's head sha and plans the run's logic from it, records which source won (`definition_source`: `head_file`, `stored` or `default`), and falls back to the stored definition with a diagnostic when GitHub is briefly unreachable - a transient read failure must never stop a push running its own pipeline. Only a head file that really was fetched and is then unparseable or fatally invalid refuses the run. Protected **authority** is unaffected: it still resolves from the default branch's approved definition, never from the head file. A **re-run** re-plans from the *original* run's definition, so re-running an old run reproduces it rather than silently executing whatever the pipeline has become since.
* **Previews deploy the pipeline's own digest.** An application whose pipeline source is `ankra_pipeline` gets its pull-request preview from the `build` step's own digest for that head - by digest, never a mutable tag - on GitHub, GitLab and Bitbucket Cloud alike; the gateway also re-drives a stalled preview the moment a pipeline run concludes, on top of the existing poll fallback.
* **Fork pull requests run, restricted.** `checkout` and `build` clone the fork's own head anonymously - never the pipeline's own repository - `build` renders with no push target so nothing it produces can reach a registry, and every stage but `checkout`, `build` and `scan` runs with no network at all regardless of what the fork's own copy of the definition asks for. Such a run also resolves no shared cache and is held to fixed matrix, timeout, compute and artifact budgets (above). See [Forks](#what-a-step-runs-as).
* **Secrets and credentials delivered into steps** as one-time, per-step reveal grants collected by the agent at step start: a `secrets` binding sourced `app_env_secret`, `org_variable` or `registry` resolves, and a `credentials` binding sourced `git` or `registry` resolves; `secrets: [{from: credential}]` validates but is not deliverable yet, and `cloud` and `object_storage` credentials are refused by name until the run gets its own scoped identity (below).
* **Schedules fire.** The cron trigger dispatches through the same trigger every push and pull request uses, advancing from a stored watermark so a loop that was down for a while does not replay every occurrence it missed.
* **Protected authority is enforced, not only modelled.** Whichever definition supplied a run's *logic*, its *authority* resolves from the default branch's admin-approved definition; a pull request that changes a protected section (below) executes under the last approved authority instead, and the check run, commit status, the definition response and the pull request's own status comment all say so. The last-approved fallback only ever offers a definition that was itself, at some point, the default branch's own head - proved from the repository's run history, never from the approval columns on the definition row alone.
* **One approval route, whichever id you hold.** The application-addressed approval (`POST /org/applications/{id}/pipeline/approve-definition`) is now an alias for the definition-addressed one, so both run the same checks - a human actor rather than a service principal, the definition must be the repository's *current* default-branch definition, a second approval of an already-approved definition is a conflict rather than a silent yes - and both write the same audit row. Before this the application-addressed route had none of them: a caller holding that application's `pipelines.manage` could approve any definition row belonging to its repository, including one sourced from a pull request head that never was, and might never be, the default branch's own content.
* **A dispatch proves its commit belongs to the repository.** `POST …/pipeline-runs` resolves the `ref` it was given - or the repository's default branch - through the repository's own host before anything is written, and accepts a caller-supplied `head_sha` only when it is that reference's current tip or, on GitHub, a provable ancestor of it through a compare read. Anything else is refused by name, and so is a transport failure that leaves the question unanswered: an unanswerable question is not a yes. GitLab and Bitbucket Cloud have no compare read, so a commit named there is held to the exact tip. **Re-runs keep working** and are deliberately exempt - a re-run's commit is one Ankra itself recorded when the original run was created, not a claim arriving with this call, which is what lets a fork pull request's run be repeated at all.
* **A dispatch's own definition is what actually runs.** `--spec-file` (`spec_yaml` on the API) is persisted verbatim on the run, and both the planner and the dispatcher render every step from it, instead of shaping the plan and then silently re-rendering each step from the stored definition. Only the *logic* moves: an override is content nobody committed, so its protected sections are compared against the default branch's approved authority exactly as a pull request head's are.
* **Five more sections are protected authority.** `services`, `cache`, `resources.cpu` and `resources.memory`, `timeout` and a stage's `with:` block now hash, resolve in both directions and surface by name, so a head can no longer ask for far more compute than the organisation meant to grant, remove its own or the trusted definition's timeout, change which run's output a cache restores into the workspace, or rewrite a `gate` stage's own scan-tool configuration. **This moves every definition's protected hash** - see the re-approval note under [Logic is open, authority is closed](#logic-is-open-authority-is-closed).
* **A sidecar is held to the step's own boundary.** A named `services:` entry's image goes through the organisation's image policy and its `env` through the reserved-name check, both as a refusal of the whole step rather than a diagnostic that runs it anyway; `ankra pipeline validate` names the same violation at `services[<name>].image`. A sidecar could previously pull any image and set `ANKRA_*`, the loader and `PATH` variables, or the image builder's own `BUILDCTL`, `BUILDKIT_HOST` and `DOCKER_CONFIG`.
* **Two organisation ceilings that nothing could set now bite.** `ci_ignore_unfixed` (below) is an organisation-wide floor a `gate` stage's own `with:` may only tighten, and `max_cache_size` on the pipeline policy is stored and enforced - every declared cache had been held to it since the ceiling was written, with nothing able to set it, so every organisation silently resolved "no ceiling".
* **`egress-https` reaches the public internet, and nothing private.** The tier's 443 rule now excludes RFC1918 (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), the whole of link-local `169.254.0.0/16` rather than only the `169.254.169.254` endpoint that used to be its single exception (AWS ECS serves task metadata at `169.254.170.2`), and carrier-grade NAT `100.64.0.0/10` (Alibaba Cloud answers at `100.100.100.200`, inside it). There is an IPv6 rule at all now, excluding `fd00::/8`, `fe80::/10` and AWS's `fd00:ec2::254`. DNS stopped being "port 53 to any pod in the cluster": it is the `kube-system` namespace plus `169.254.0.0/16` for a cluster running NodeLocal DNSCache, and the `services` tier - which carried no DNS rule at all - gained the same one. **This breaks a pipeline that reaches a private HTTPS endpoint**, and the symptom is a connection timeout rather than a refusal, so name the range in `ci_egress_allowed_cidrs` (below) *before* the step runs: a `build` that pushes to a registry on a private address - an in-cluster registry, a Harbor inside your VPC - cannot reach it until that entry exists. The agent renders a step's NetworkPolicy itself, so the tightened tier arrives with the agent release of 5 September 2026; a cluster still on an older agent keeps the previous tier until the fleet roll reaches it.
* **An image policy prefix ending in a separator means that separator.** An entry ending in `/`, `:` or `@` used to match nothing at all, because the matcher requires one of those three characters *after* the prefix - the boundary check that stops `ghcr.io/my-org` admitting `ghcr.io/my-org-evil/api`. Each now admits exactly its own boundary: `ghcr.io/my-org/` admits `ghcr.io/my-org/api` and refuses `ghcr.io/my-org` and `ghcr.io/my-org:v1`, `ghcr.io/my-org:` admits a tag and not a path, `ghcr.io/my-org@` admits a digest, and `registry.example.com/` admits paths on that host and never `registry.example.com:5000/anything`, which is a different endpoint. Trimming the separator away would have widened each of those rather than narrowing it, so that is not what happens, and an entry that is only separators - or ends in two of them - matches nothing rather than becoming the empty prefix every image starts with. The settings API refuses a trailing separator at write time and always has, so a stored `ci_allowed_image_prefixes` cannot carry one: this is defence in depth for the prefixes Ankra sets in code and for the copy of the policy a step's payload carries, not a change to what an administrator can store.
* SCM feedback: one `Ankra pipeline` check run per run on GitHub with a real conclusion and a Cancel button, a commit status on GitLab and Bitbucket, a comment fallback when the GitHub App lacks `checks:write`, and - on a pull request - the same run state and authority sentence in the `pipeline` section of Ankra's one status comment.
* **The AI review reads your pipeline, and a human can say "merge when green".** See [What a pull request gets](#what-a-pull-request-gets) above: a bounded pipeline-facts block in the review prompt, a `merge when green` pull request comment gated on the run, its gate, both reviews and its authority, and a `watch_pipeline_run` chat tool whose unattended fix loop reacts to a failed `build` step.
* Step logs and declared artifacts stored in the organisation's oldest ready backup vault - or, for an organisation with none, in the Ankra-managed default vault - listed and downloaded through the API today; `ankra pipeline artifacts` and `artifacts download` speak the same routes and read the same way from the CLI's next release (see [Commands and API](#commands-and-api)). **A vault is no longer something to arrange first** - a `scan` stage's reports travel the same path, so a fresh organisation records findings and passes its gate without provisioning a bucket; bringing your own decides where the objects live, not whether they are kept (see [Before your first run](#before-your-first-run)).
* **Long runs stay alive.** Every settle pass re-stamps the run's heartbeat, so the platform's twenty-minute stale-run reaper no longer fails a pipeline that is still working. A run whose steps genuinely stopped reporting is still reaped, and the reason is recorded.
* **Run history is retained by policy, not forever.** `ci_run_retention_days` (default 90, 7 to 365, below) bounds how long a concluded run is kept, and an hourly sweep deletes past the window in batches. It never deletes a live run, never a repository's own newest concluded run, and never a run still carrying an artifact the artifact reaper has yet to remove from the vault.
* **Run outcomes reach your destinations.** `pipeline_run_failed`, `pipeline_run_succeeded`, `image_gate_blocked`, `preview_ready` and `preview_failed` are notification kinds like any other, produced once per run (or once per gate verdict, or when the preview row itself flips), so [notification routing](/guides/notification-routing) sends them to Slack, Teams, PagerDuty or a webhook alongside everything else Ankra reports.
* **A truncated log says so, and the failing step names its own error.** The agent reports how many log lines it had to drop to backpressure; that count is recorded on the step and shown as a notice under its row on both the check run and the pull request status comment, so a step whose output was silently cut no longer looks like one whose log arrived whole. The check run's step table also carries the failing step's own error message (truncated to 200 characters) in its Outcome cell, instead of only the run's error in one blockquote at the end.
* **The portal.** The application's **Pipelines** section shows Ankra pipeline runs with a timeline and an in-app log viewer beside the GitHub Actions view; organisation **Settings → Pipelines** lists connected repositories; the application's **Security** section reads a pipeline's own findings once a run has concluded for its repository, falling back to the GitHub-artifact reader until one has.

**Not in place yet**

* **The runner for `verify`.** No runner image exists, so a `probe`, `smoke`, `load_test`, `assert_promql` or `restore_verify` sub-block never runs. The stage is skipped with `kind_unavailable` rather than dispatched into an image pull that cannot succeed, so it no longer holds the run open - but it also verifies nothing, and a pipeline that relies on it is not being verified.
* The executors for the remaining stage kinds - `preview` (a per-pull-request environment deployed from *inside* the pipeline DAG, not to be confused with an Application's own pull-request preview, which already deploys a pipeline's digest, above), `agent`, `approval`, `webhook`, `automation`, `ankra` and `external`. Each validates with a warning and is skipped, so a run containing one concludes; none of them does the work its name promises. In particular an `approval` stage does **not** block a run on a human today - it is skipped, and everything downstream of it runs.
* The per-run identity `permissions` mints, so a step can call the `ankra` CLI with exactly the authority the default branch granted - a converted `github.token` reference already diagnoses itself as "the run-scoped `ANKRA_TOKEN`", naming what does not exist yet rather than resolving to nothing; `cloud` and `object_storage` credentials wait on the same identity.
* The built-in `ankra/*` step library behind `uses:`, organisation step templates, and `custom_tool/<name>` steps. Until it ships, any `uses:` is fatal at validate time with one sentence telling you to write the step as `run:`.
* **Nothing pins the step keys an expression names.** `${{ steps.<key>.outputs.<name> }}` resolves at dispatch against the run's real steps, but a key that does not exist - a typo, or a matrix leg the writer guessed at - interpolates to empty text rather than being refused. The validator declares expression *roots*, not key sets, and a step key is a matrix-expansion product it cannot know; closing this belongs in the planner, which does know the expanded keys.
* **The user-declared `retry` block is validated and carried to the agent, not applied.** A step's own `retry:` is parsed and stored on the plan, but nothing dispatches a second attempt from it - only Ankra's own infrastructure failure classes retry automatically (see [When something fails](#when-something-fails)); a script that exits non-zero is final today regardless of `retry.max_attempts`. Dynamic matrices (`matrix: ${{ fromJSON(steps.plan.outputs.legs) }}`, fanning out over a previous step's own output) are not available either - every axis must be written out in the file.
* **Attestations and SBOM referrers on the image you actually deploy.** `build`'s `provenance`/`sbom` flags attest the digest it pushes to the CI staging repository; `publish`'s re-tag copies that one image manifest, not the attestation manifests beside it, so they are not on the digest your application deploys. Trivy's SBOM is an artifact in the vault today, not an OCI referrer on any image.
* **Merge-when-green and automatic disposition re-evaluation are GitHub only.** A GitLab or Bitbucket Cloud `merge when green` request is accepted and then refused, because neither provider adapter reports the capability to merge yet; a push to a GitLab or Bitbucket Cloud default branch that adds or removes `.ankra/pipeline.yaml` answers `insufficient evidence` rather than re-evaluating the application's pipeline source, because the raw-file read that evaluation needs has no GitLab or Bitbucket equivalent wired in yet.
* **A dedicated log stream for pipeline output, on the agent side.** The platform half is in place: the `pipeline_output` JetStream stream exists with its own capacity and retention, the agent is granted publish on its own cluster's subject, dispatch renders that subject onto every step, and the log relay reads the dedicated stream first and falls back to the shared one. What has not shipped is the agent release that actually publishes there, so live output still rides the platform-wide `execution_output` stream until your cluster's agent is upgraded to a release carrying that change. Nothing about `ankra pipeline logs` or the check run changes when it does - the relay already reads either.
* **Planning from the committed file is GitHub-only.** A GitLab or Bitbucket Cloud run plans from the stored definition permanently, because the bounded raw-file read the planner uses has no equivalent wired in for those providers yet; the run records `definition_source: stored` and says so in a diagnostic rather than pretending it read your commit.
* **Annotations and metrics.** A step's stdout can already carry `$ANKRA_OUTPUT` key=value lines, read back onto the step; the equivalent for check-run annotations (`::ankra::notice file=…,line=…::msg`) and custom metrics (`::ankra::metric name=…,value=…`) is not ingested anywhere yet. Test reports are: see [Test results](#test-results).
* Environments hydrated from restore points, verification stages, promotions with approvals, and canary rollouts - see [What comes next](#what-comes-next).

## Test results

A stage that runs tests can declare the reports its test command writes, and Ankra reads every test's outcome from them:

```yaml theme={null}
  - name: "e2e"
    kind: "run"
    run: "pnpm test:e2e"
    artifacts:
      - name: "junit"
        paths:
          - "reports/junit"
    test_results:
      - format: "junit"
        path: "reports/junit"        # a file, or a directory of report files
```

After the step, the agent uploads each report to your organisation's [backup vault](/concepts/backup-vaults) like an artifact (named `ankra-tests.<n>.<format>` in the run's artifact list), and Ankra parses it. The step's own exit code stays its verdict: a report Ankra cannot read never fails or passes the step.

**Formats.**

| `format` | What to point it at |
| - | - |
| `junit`, `pytest` | JUnit XML: `go-junit-report` and `gotestsum --junitfile`, pytest `--junitxml`, Jest's `jest-junit`, Vitest's `junit` reporter, Maven Surefire, Playwright's `junit` reporter. A directory is read for every `.xml` file in it. |
| `playwright` | Playwright's JSON reporter (`reporter: [['json', { outputFile: 'results.json' }]]`). |
| `go-test` | `go test -json` output, or `gotestsum --jsonfile`. |

**Your command writes the report.** `test_results` only names where the report is; the stage's own command has to write it there, or there is nothing to read and the run's test summary lists the report as never uploaded. For example: `gotestsum --jsonfile test-results.json -- ./...` (or `go test -json ./... > test-results.json`, which leaves the step's log as raw JSON), `pytest --junitxml=reports/junit.xml`, `vitest run --reporter=junit --outputFile=reports/junit.xml`. A path is relative to the workspace, not to a directory the command `cd`s into or the stage's `working_directory`. A pipeline Ankra generates for you declares a report only when its test command writes it.

**Flaky tests.** A test that failed and then passed on a retry is recorded as `flaky`, not passed, with the number of attempts. Ankra reads retries from Playwright's JSON reporter, from a JUnit file's Surefire `flakyFailure`/`rerunFailure` elements, and from a test that appears more than once in one report (`gotestsum --rerun-fails`). Playwright's `junit` reporter only writes retries with `includeRetries: true` (or `PLAYWRIGHT_JUNIT_INCLUDE_RETRIES=1`); without it a flaky test reads as passed, so use the JSON reporter or turn that on.

**What you get.**

* The run page's **Tests** section: failed tests first, then flaky ones, then the slowest, each with its duration, attempts and failure message. A report that was declared but not uploaded or could not be read is listed with the reason.
* `GET …/pipeline-runs/{run_id}/tests`: the same summary over the API.
* `GET …/pipeline-tests/history?test_key=…`: one test's outcomes in the newest runs of your default branch (or `branch=`), with its flaky rate.
* `GET …/pipeline-tests/timings?stage=…&group_by=file|test`: each file's or test's mean recorded duration on the default branch, to balance shards by time. `runs_sampled: 0` means there is no data yet; fall back to an even split.

All three need `pipelines.read`, and each is addressed by repository or by application, for example `/api/v1/org/pipeline-repositories/{repository_id}/pipeline-tests/history` and `/api/v1/org/applications/{application_id}/pipeline-runs/{run_id}/tests`.

**When a report is missing.** Declaring `test_results` never fails a step that passed. Today Ankra uploads a declared report only when the stage also lists the same path under `artifacts:`, as the example above does: a path the stage already declares is one the step promised to write. A report that is declared only under `test_results` is not uploaded, and the run's test summary says so and why. If your test command never wrote the report (the suite crashed before its reporter ran), the summary says that too, rather than reading as a run with no tests.

### Quarantining a flaky test

A test that keeps failing on and off should not fail every run while someone fixes it. Each repository can **quarantine** such tests. A quarantined test still runs and is still reported; what changes is that a step whose **only** failed tests are quarantined passes. Quarantine is off on every repository until you turn it on, and only a member with `pipelines.manage` can change it.

**When a failure is forgiven.** A failing step passes because of the quarantine only when all of these hold. Otherwise it fails exactly as it would without one:

1. It is a `kind: run` step that failed on its own (`step_failed`). A timeout, an infrastructure error, a refusal, and any build, scan, publish, deploy or verify step always fail as before.
2. Quarantine is on for the repository.
3. The step declared at least one test report, and every one was uploaded and read whole.
4. The reports hold at least one failed test, and every failed test is quarantined. A test that passed on a retry counts as `flaky`, not failed.

A forgiven step reads as passed with a note of how many quarantined tests failed in it, its dependents run, and the run's test summary always lists the quarantined failures under **Quarantined failures**, with whether each one rescued its step. Nothing is hidden: the failed tests are still in the failed list too. Write test steps so that a failure after the tests (a `;` instead of `&&`) fails the step on its own, because the quarantine only reads the step's test reports.

**Which tests can be quarantined.** A test qualifies when, over your default branch's own runs in the last 30 days (never pull request checks), it ran in at least `min_samples` runs and was `flaky` in at least `min_flaky_rate` of them.

| Setting | Default | Range |
| - | - | - |
| `enabled` | `false` | |
| `min_flaky_rate` | `0.1` (10%) | above 0, up to 1 |
| `min_samples` | `20` | 3 to 1000 |
| `release_after_passes` | `10` | 1 to 100 |

**Leaving quarantine.** A quarantined test is released when someone releases it, or on its own after it passes `release_after_passes` default-branch runs in a row; a failure or a flake on the default branch starts the count again. Turning quarantine on or changing a setting, quarantining a test and releasing one are each recorded in the organisation's audit log, an automatic release under `system`.

**Commands.**

```bash theme={null}
ankra pipeline tests quarantine settings --enable           # turn it on for this repository
ankra pipeline tests quarantine candidates                  # the tests that qualify now
ankra pipeline tests quarantine add <test key> --reason "flaky since the cache change, ENG-123"
ankra pipeline tests quarantine                             # settings, quarantined and recently released tests
ankra pipeline tests quarantine release <quarantine id or test key> --reason "fixed in #42"
```

Over the API, on the same repository or application paths as the other test routes: `GET …/pipeline-tests/quarantine`, `PUT …/pipeline-tests/quarantine/settings`, `GET …/pipeline-tests/quarantine/candidates`, `POST …/pipeline-tests/quarantine` with `{"test_key", "reason"}`, and `POST …/pipeline-tests/quarantine/{id}/release`. Quarantining a test that does not qualify, or while quarantine is off, is refused with the reason, naming the test's flaky rate and runs against your settings.

**Limits.** A report is at most 32 MiB, and a directory at most 256 report files and 64 MiB unpacked. At most 100,000 tests are read from one report, and 20,000 per report and 50,000 per run are stored, failed and flaky ones first; the counts always cover every test read. Failure messages are kept to 2,000 characters, and anything that looks like a credential is redacted. A report with a `DOCTYPE` is refused. Test results are kept as long as the run they belong to.

## Organisation CI settings

`GET` and `PUT /api/v1/org/ci-settings` (and `/org/ci-settings` in the portal session) carry the organisation-level settings every pipeline runs under. Reading them is open to every member; changing them is an organisation administrator's act.

| Setting | Default | Meaning |
| - | - | - |
| `ci_cluster_id` | none | The cluster pipeline steps execute on. Unset, the organisation's AI staging cluster is used. |
| `ci_build_fallback` | `platform_builders` | Whether [Ankra platform builders](#ankra-platform-builders) may build when your own cluster cannot. `none` refuses the build instead, for source that may not leave your infrastructure. The setting is necessary but not sufficient: the fallback also needs the grant `platform_builds_enabled` reports. |
| `platform_builds_enabled` | `true` | Read-only, and not a setting: whether platform builds are on for your organisation. They are on for every organisation unless Ankra has switched them off for yours. `ankra org ci-settings get` prints it as `Platform builds enabled: yes` or `no` (CLI v0.17.0 or newer). While it reads `false`, a build `ci_build_fallback: platform_builders` would route to it is refused as `build_fallback_none` with a sentence saying the fallback is not enabled for this organisation yet. A `PUT` naming it is refused, because only Ankra can change it. |
| `ci_max_parallel_runs` | `16` | Runs of this organisation in flight at once (1 to 64). |
| `ci_max_parallel_steps` | `8` | Steps of **one run** in flight at once (1 to 256). It is not an organisation-wide total; see [Capacity and concurrency](#capacity-and-concurrency). |
| `ci_allowed_image_prefixes` | empty | Image prefixes a step may name, matched at a path boundary (up to 50 prefixes of up to 200 characters). Empty means images are not checked, and each run records that. |
| `ci_artifact_retention_days` | `30` | How long step logs and artifacts are kept (1 to 365). |
| `ci_cache_retention_days` | `14` | How long a cache nothing restored is kept (1 to 365). |
| `ci_run_retention_days` | `90` | How long a concluded run and its steps are kept (7 to 365 - a longer floor than artifacts and caches, because run history is what a person reads back after the fact). An hourly sweep deletes past the window; it never removes a live run, a repository's newest concluded run, or a run whose artifacts the vault still holds. |
| `ci_image_gate` | `app` | Which image findings block a `publish`: `app` blocks on fixable CRITICAL and HIGH findings in your own dependencies, `all` also on what the base image carries, `off` on nothing - the scan still runs and still reports either way. Only the built image is gated: what Trivy finds scanning the checkout itself (`trivy-fs.json`, a lockfile entry or a build tool) is recorded and reported but never blocks a publish, because it is not in the image. A `gate` stage's own `with:` may only move this stricter for its one pipeline, never looser. |
| `ci_ignore_unfixed` | `true` | Whether a finding with no published fix is excluded from blocking the gate - Trivy's own lenient default. Set it `false` and every unfixed finding keeps blocking whatever any pipeline asks for: like the two settings above, a `gate` stage's own `with.ignore_unfixed` may only move toward the strict direction from here, never back. |
| `ci_egress_allowed_cidrs` | empty | Private ranges a step on the `egress-https` tier may still reach on 443 (at most 32). Each entry is a CIDR written as its own network address - no host bits - sitting wholly inside `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` or `fd00::/8`, and covering no cloud metadata endpoint: AWS answers on `fd00:ec2::254`, which is inside `fd00::/8`, so `fd00::/8` itself is refused and you name your own pod or Service CIDR instead. Entries are trimmed and de-duplicated, and a refusal names which entry it refused by position. Empty - the default, and where every organisation starts - is strict. API only today; the portal has no field for it. |
| `ci_always_run_stages` | empty | Stages that run whatever their path filters, or their trigger's, say, together with every stage they need (at most 50 stage names). A pull request cannot filter them away, because this list lives here rather than in the repository. See [Setting path filters aside](/guides/pipeline-reference#setting-path-filters-aside). |
| `ci_full_run_on_default_branch` | `false` | Run every push to a repository's default branch in full: no path filter applies there, and each such run records `organisation_policy` as why. |
| `ci_skip_markers` | `except_default_branch` | Where a `[skip ci]` style marker in a pushed commit's message skips the run: `except_default_branch`, `everywhere` or `never`. A tag push, a pull request run and a merge train car never honour one. See [Skipping a push with \[skip ci\]](/guides/pipeline-reference#skipping-a-push-with-skip-ci). |

Only the members you send are changed, so re-opening one private range is a single call that leaves the rest of the table alone:

```bash theme={null}
curl -X PUT https://platform.ankra.app/api/v1/org/ci-settings \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"ci_egress_allowed_cidrs": ["10.42.0.0/16", "192.168.10.0/24"]}'
```

The pipeline *policy* (`/api/v1/org/pipeline-policy`, `pipelines.manage` for read and write) is the ceiling above these: allowed network tiers, credentials, node selectors, tolerations and runtime classes, maximum CPU, memory and GPU per step, the largest a declared cache volume may ask for (`max_cache_size`, which the route now stores and every declared cache is held to), the hosts a `webhook` stage may post to, and the external CI providers a pipeline may wait on.

### Capacity and concurrency

How much pipeline work runs at once is decided by two organisation limits and one property of the cluster the steps run on. The narrowest one wins.

| Limit | Bounds | Default | Range | Read it | Change it |
| - | - | - | - | - | - |
| `ci_max_parallel_runs` | Runs of the organisation in flight at once | `16` | 1 to 64 | `ankra org ci-settings get` | `ankra org ci-settings set --max-parallel-runs N` |
| `ci_max_parallel_steps` | Steps of **one run** in flight at once | `8` | 1 to 256 | `ankra org ci-settings get` | `ankra org ci-settings set --max-parallel-steps N` |
| `ci_worker_count` | CI slots: steps the CI cluster's agent runs at once, across every run on that cluster | `0` (pipelines off) | 0 to 128 (0 to 32 on older agents) | `ankra cluster agent ci get --cluster <name>` | `ankra cluster agent ci set --workers N --cluster <name>` |

The two organisation limits need an organisation administrator, and the portal's **Pipelines** settings page edits both. The same page edits the pipeline cluster's CI slots and workspace storage class in its **Workers and step placement** card. The run limit is the one that caps throughput: every run past it waits as `queued`. The step limit only shapes how wide one run fans out. It is not an organisation-wide total (it was until 14 September 2026), so raising it never drains a queue of other runs.

**A CI slot is not a node.** A slot is one step the agent on the CI cluster watches at once, from the moment it creates the step's Job until the step concludes. Nodes are a separate question, answered by the cluster's node-group autoscaler: when steps ask for more CPU and memory than the current nodes have free, it adds nodes, up to the group's autoscaling maximum. So the slot count is how many steps may be live, and the node group is whether there is room to place them. A cluster with plenty of slots and a node group at its maximum still queues, and so does a large node group behind a small slot count.

**Changing the slot count.** An agent new enough to resize live applies a new `ci_worker_count` within a few seconds, without a restart, and takes up to 128 slots; `ankra cluster agent ci set` says it was applied live. An older agent takes up to 32, and a change re-renders its release instead: at once when it is online, at its next upgrade otherwise, and the command says which happened. Turning pipelines on or off (to or from `0`) always re-renders the agent.

**Ankra does not over-fill a cluster.** Ankra stops handing a cluster steps once its agent has as many in flight as it has slots, so the extra steps wait in Ankra's own queue, where organisations are served fairly and the run can say why it is waiting. Time spent waiting for a slot is not time spent running: a step's timeout starts when the agent begins it, and the step's duration on the run page and in `ankra pipeline get` counts from the same moment. The run page shows the wait separately as the step's queue wait, and `ankra pipeline get` prints it beside the step.

**Steps of one run share a node.** A run's workspace is one `rwo` volume (see [Limits and defaults](#limits-and-defaults)), so every step of one run, and the helpers that restore and save its caches and upload its artifacts, is pinned to the node that volume is attached to. A step that cannot fit there waits for its siblings to finish and is then queued again, rather than landing on another node and waiting for the volume to detach and re-attach. When the node is gone, cordoned or not Ready the pin is dropped and the step log says so; when a step does wait on a volume held by another node, its log names that node. That node's free CPU and memory against what each step reserves is a physical limit of its own: more nodes elsewhere do not widen one run, while a larger node does, and so does a stage that declares what it needs rather than a round number. When a run fans out, its first step prefers the emptiest node so its siblings have room beside it.

A step reserves half of its `resources.cpu` and all of its `resources.memory` (250m and 1Gi when the stage sets no `resources`). The CPU figure is a ceiling the step grows into while its node has CPU free, so a lint step that declares two cores and uses a fraction of one does not keep a build off the node; when every step on a node is busy at once, the node's CPU is shared in proportion to what the stages declared and the steps run slower instead of waiting. Memory is different: a node cannot take memory back from a running step without killing it, so each step's memory is set aside in full, and on most nodes memory is what decides how many steps fit. A stage whose `memory` is padded costs you a step's worth of concurrency; one whose `memory` is too low is killed with exit status 137.

**Sizing a stage from what it used.** Ankra records, for every step the agent runs, what its container asked for and what it used: the highest memory the kernel charged it, how often it met its memory limit, whether a process was killed for memory, its CPU time and how long it was held back at its CPU limit. `ankra pipeline get <run> -o json` carries these per step (`memory_peak_bytes`, `cpu_usage_usec` and the rest), next to its requests (`memory_request_bytes`, `cpu_request_millicores`). The API's resource suggestions for a run (`GET .../pipeline-runs/<run>/resource-suggestions`) turn them into one suggestion per stage, from that stage's latest 20 successful attempts under the same pipeline definition: the 95th percentile plus 25% headroom, rounded up, and only once a stage has at least 5 attempts to go on. Each suggestion says how many attempts it rests on. Nothing is ever applied for you; change `resources` in your pipeline file if you agree.

Two readings need care. A memory peak counts page cache, which the kernel uses to fill whatever room a step has, so a stage whose peak reached its limit is reported `at_limit` with no suggestion: its peak says it used the room, not that it needed it. CPU has no peak the kernel keeps, so the CPU suggestion is the request a stage should reserve, sized from the cores it used on average, written as the `resources.cpu` that reserves it; a stage that spent a tenth or more of its demand held at its limit is `at_limit` instead. Lowering `resources.cpu` lowers the ceiling too, so a stage that uses its CPU in bursts may run slower on the suggestion.

**A step that cannot fit beside its run goes back to the queue.** When the node holding a run's workspace is full, a step that has to run there would otherwise sit waiting on that node while holding a CI slot. After a minute of that, the agent gives the slot back and Ankra returns the step to the queue; it is handed out again once the run's other live steps have finished and the node has room. The run page says how many times a step was returned to the queue, and `ankra pipeline get` prints the count.

**A run can reserve its room before it starts.** With the run reservation on for a pipeline cluster (`ankra cluster agent ci set --run-reservation on --cluster <name>`), Ankra works out from the plan how much CPU and memory the run's steps will need side by side at their peak. Before the first step starts, it asks the cluster to hold that much room on one node with a placeholder pod. The run's steps then take that room over as they start, so another run cannot fill the node between two steps. When no node has that much room free, the placeholder waits like any pod, and the cluster autoscaler can add a node for it. When the run concludes, the room is released.

That has a cost. While a reserved run is in progress it keeps its room on the node even between steps, and that can **add a node** or **keep one from scaling down** that an unreserved run would have let go. `shadow` works out and records each run's reservation without holding any room, so you can compare the estimate with what the steps used before you turn it on. `off` reserves nothing. Each run's reservation is on its detail as `reservation` (mode, the estimated CPU and memory, and the peak its steps were observed to use), and the run page shows it under **Reservation**.

**A step that can never be scheduled fails fast.** If no node the step may run on is large enough for what it asks for, and the autoscaler cannot add one that is, the step fails after about two minutes with the scheduler's own reason, instead of holding a slot until its timeout and reporting a timeout for a step that never ran. Lower the stage's `resources`, or add a node group with larger nodes.

#### Why a run is waiting

A queued run says which limit it is behind. The run page shows it under the run's status, `ankra pipeline get` prints a `Waiting:` line (CLI v0.17.0 or newer), and the run detail carries it as `queue_reason` with a sentence in `queue_reason_message`:

| `queue_reason` | What it means | What moves it |
| - | - | - |
| `planning` | Ankra has not planned the run's steps yet. Clears within a few seconds | Nothing to do |
| `waiting_on_concurrency_group` | Another run holds the run's concurrency group, and the message names it | `cancel_in_progress: true` (see [Newest commit wins](#newest-commit-wins)), or wait |
| `waiting_on_run_cap` | The organisation already has `ci_max_parallel_runs` runs in flight | Raise `ci_max_parallel_runs` |
| `waiting_on_step_cap` | The run already has `ci_max_parallel_steps` steps running | Raise `ci_max_parallel_steps` if one run should fan out wider |
| `waiting_on_ci_workers` | The CI cluster's agent runs no pipeline steps, is offline, or is missing | The message names the fix, usually `ankra cluster agent ci set --workers N` |
| `waiting_on_ci_slots` | Every CI slot on the cluster is taken; the message says how many slots it has and how many steps hold them | Raise `ci_worker_count`, and check the node group can grow to match |
| `waiting_for_room_on_cluster` | With the run reservation on, the cluster caps how many runs it admits at once while their reservations are still being placed, and it is at that cap. This run has not been admitted yet, so it is still queued | It is admitted as earlier runs' reservations are placed |
| `waiting_on_run_node` | The node the run's workspace lives on has no room for the run's next step | It starts when the run's other steps on that node finish |
| `waiting_on_capacity` | The run's steps are queued behind other work on the cluster | They start as slots free up |

Once a run's first step has started it shows no `Waiting:` line, whichever of these limits holds its next step back: its pending steps start as the limit frees up. A step that Ankra has handed to the agent and that is waiting for a free slot shows as waiting for a CI slot on the run page.

**A run waiting for room for its reservation** has been admitted and is already running, so it carries no `queue_reason`. It says so in its own field instead. While the run's first step waits for a node with room for the run's reservation, the run page shows **Waiting for a node with room for this run**, with the room it is holding out for, how long it has waited, and what the autoscaler is doing about it (adding a node, at its node group's maximum, refused by the provider). `ankra pipeline get` prints the same sentence on its `Waiting:` line and a `Reserving:` line with the room and the wait. The run detail carries it as `reservation_wait` (`state` `waiting` or `returned_to_queue`, `since`, `waited_seconds`, the reserved `cpu_millicores` and `memory_bytes`, and the `message`). If no node has room within 10 minutes, the first step goes back to the queue and is sent again, and the state reads `returned_to_queue` with the count. When Ankra could not read the cluster, `reservation_wait_unavailable` says so, and while it is set the wait is unknown: a missing `reservation_wait` then does not mean nothing is holding the run back. The step itself carries the diagnosis `run_reservation_pending` (see [Diagnosis codes](#diagnosis-codes)).

#### Seeing and raising capacity

The **Capacity** panel on the portal's **Pipelines** settings page shows, refreshed every 15 seconds: the CI slots on your pipeline cluster, the steps in flight there, your organisation's queued runs, its runs in flight against `ci_max_parallel_runs`, its pending steps, and how much of its work is waiting for a CI slot. It also names the limit that is full.

To raise capacity, change the limit that is full:

* **Runs queue as `waiting_on_run_cap`.** `ankra org ci-settings set --max-parallel-runs N` (up to 64).
* **Runs queue as `waiting_on_ci_slots`.** `ankra cluster agent ci set --workers N --cluster <name>` (up to 128 on current agents).
* **Steps are slow to start although slots are free.** The cluster has no room for the pods: raise the node group's autoscaling maximum (`ankra cluster node-group autoscaling get` shows it), or use larger nodes. More slots without more nodes only means more steps waiting for a node.

The panel also says what is stopping each CI cluster from running your waiting steps, as a code and the one thing to do about it: a node the cloud provider refused for a quota, a node group at its maximum, no node type big enough for the step, an image the registry refused. `ankra org ci-settings get -o json` carries the same list per pool member as `scale_up_blockers`, with `scale_up_blockers_state` saying whether an empty list means nothing is wrong (`none_observed`) or the cluster's events could not be read (`unknown`). The codes are listed in [Diagnosis codes](#diagnosis-codes).

Ankra also watches every pipeline cluster for you. When a cluster's steps in flight have stayed at or above its CI slots for fifteen minutes, Ankra raises a saturation alert for that cluster: pipelines there are queueing for slots while everything else reads healthy. The remedy is the same as above, more slots, or a larger node group maximum when the nodes are what is full.

### Step placement

By default a pipeline pod runs on any node of the CI cluster that will take it. To keep CI on nodes of its own, for example a dedicated node group tainted so nothing else lands there, give the cluster a **step placement**:

```bash theme={null}
ankra cluster agent ci set --cluster so-upcloud-infrastructure --node-group pipelines
```

Every pipeline pod of that cluster then carries it: the step pods, their cache restore and save helpers, the artifact uploader, and image builds in `ankra-ci-build`. Naming a node group is enough on a cluster Ankra built: the pods select the group's nodes by the `ankra.cloud/node-group` label every node Ankra spawns carries (or by the labels the group declares, on a group from before that label), and tolerate every taint the group has. A group the cluster does not have is refused, and the refusal lists the groups it does have. On a cluster without Ankra node groups, name the nodes yourself:

```bash theme={null}
ankra cluster agent ci set --node-selector pool=ci --toleration dedicated=ci:NoSchedule
```

`--node-selector key=value` and `--toleration key[=value]:Effect` repeat, and add to `--node-group` when you give both. A toleration without a value tolerates any value of the key; the effect is `NoSchedule`, `PreferNoSchedule` or `NoExecute`.

| Mode | What the pods do |
| - | - |
| `required` (default) | Run only on nodes carrying the selector. When none has room they wait, and the group's autoscaler adds a node if it can. |
| `preferred` | Favour those nodes, and run elsewhere when they have no room. The tolerations are carried either way, so the group's nodes stay open to them. |

Set the mode with `--placement required|preferred`, and remove the placement with `--clear-placement`. A placement flag replaces the whole placement; the worker count and storage class are left alone, and `--workers` is not needed to change only the placement. The change applies to the next step Ankra sends the cluster, with no agent restart. `ankra cluster agent ci get` prints the placement and how many Ready nodes it admits right now, so a placement no node matches is visible before a run waits on it. The portal's **Workers and step placement** card on the **Pipelines** settings page edits the same setting, with the cluster's node groups to choose from.

The placement is set by whoever may manage the cluster's agent, outside any pipeline definition, so it needs no [authority approval](#logic-is-open-authority-is-closed) and is not held to the pipeline policy's node selector and toleration allow-lists - those bound what a pipeline's own `runs_on` may ask for. A stage's `runs_on` still applies on top of it: its node selector is merged with a `required` placement's, and a stage asking for a different value of a key the placement sets is refused before it runs, naming both. On a cluster where a Kyverno or Gatekeeper policy mutated pipeline pods onto a dedicated group, the placement replaces that policy, and unlike it also covers the helper pods.

To create such a group, `ankra cluster node-group add <cluster> --name pipelines --instance-type <type> --taints dedicated=ci:NoSchedule` taints it from its first node.

An agent that predates the placement ignores it and places pods by each stage's own `runs_on` alone, so upgrade the cluster's agent (`ankra cluster agent upgrade`) before relying on it.

### Ankra platform builders

Ankra platform builders are the Ankra-operated build lane a `build` step falls back to when the pipeline cluster cannot build it. The fallback covers two causes, and nothing else:

* **The cluster's agent does not run pipeline steps.** It predates the capability, or no agent has checked in at all. Every stage of the run is affected. `build` runs on Ankra platform builders, the `checkout` in front of it is settled for that build, and the run's `scan` stages run on Ankra's platform scanner (below). Stages that need your cluster, such as your own tests and deploys, are still refused, with a sentence naming the agent to upgrade.
* **The cluster's node runtime confines the rootless image builder.** Typical for AppArmor on k3s or Ubuntu nodes, and for a kubelet that defaults seccomp to `RuntimeDefault`. Every other stage runs in-cluster as normal and only `build` is routed away; [`build_runtime_confined`](#when-something-fails) has the mechanics.

Three things have to hold for the fallback to build: `ci_build_fallback` reads `platform_builders` (the default), platform builds are on for the organisation (the default), and the stage is one the lane can accept (below). With platform builds switched off, the step concludes `build_fallback_none` with a sentence saying Ankra's platform-operated build fallback is not enabled for this organisation yet, whatever the setting says.

**Confirm the grant.** `ankra org ci-settings get` prints `Platform builds enabled: yes` or `no` (CLI v0.17.0 or newer; `-o json` carries it as `platform_builds_enabled`), and when the answer is `no` while the fallback reads `platform_builders`, the command says the grant is what is missing, not the setting. `GET /api/v1/org/ci-settings` returns the same field as `platform_builds_enabled`. Any member of the organisation can read it; nobody in the organisation can write it.

**If the grant reads no.** Platform builds are on for every organisation unless Ankra has switched them off for yours. [Open a support ticket](/platform/support) naming the organisation and the pipeline cluster (`ci_cluster_id`, or the cluster's name) whose builds should fall back, and the next run uses the grant once it is back on, with no change on your side.

**Sharing the pool.** Ankra platform builders are shared by every organisation, so one organisation runs at most three builds on them at a time. A fallback build beyond that waits in order and starts when one of your running builds finishes; it is not failed and does not use the step's retry. [Waiting for a builder](/concepts/applications#waiting-for-a-builder) has the details.

**Cost.** Platform builds carry no charge. Nothing about the grant or the setting changes your billing: no usage is metered for a build that runs on Ankra platform builders, and a build that runs in-cluster costs what your cluster already costs.

**What you see during a fallback build.** The step's `executor` records `platform_builders`, and the run's step table shows the step running on Ankra platform builders rather than on your cluster. There is no live log stream to tail, because the step was never dispatched to an agent: `ankra pipeline logs --follow` has nothing to attach to while the build runs, and the archived log appears when the build concludes. The image is pushed by digest to the organisation's CI staging repository, exactly where an in-cluster build pushes, so the pipeline's own `scan`, `gate` and `publish` steps still decide whether it is promoted.

**Scans of a run handed to the builders.** When the whole run went to Ankra platform builders because the cluster's agent does not run pipeline steps, its `scan` stages run on Ankra's platform scanner instead of being skipped. Each scanner (Semgrep, Checkov and Trivy) runs the same pinned image and the same script it runs in your cluster, against the commit and the image the platform builders built. Its reports are recorded exactly as an in-cluster scan's are. The `gate` then judges them under the same image gate policy and the same evidence rules, and `publish` proceeds on the gate's verdict alone. A fallback image is held to the same bar as one your cluster built. The scan step's `executor` records `platform_builders`, and its message says why it ran there.

A scan the platform scanner cannot run concludes `infra_error` with a sentence naming why. That happens when no scanner is available (`platform_scanner_unavailable`), when the scan stopped reporting, or when the organisation has nowhere to keep the reports. The scan is never skipped, so the gate never approves an image nobody scanned, nothing is published, and the run is not green. Start the run again once the scanner is back, or upgrade the cluster's agent with `ankra cluster agent upgrade --cluster <cluster>` so the whole pipeline runs in-cluster.

**What the lane refuses.** Ankra platform builders build what the in-cluster pod would have, from the same stage, but two things about a stage's layout have to be right, or the step concludes without a build and its sentence names the fix:

* In a multi-component (monorepo) application, a build stage must belong to a component the application records: either it declares `build.component`, or it is called `build-<component>` ([which component a build belongs to](#which-component-a-build-belongs-to)). A stage that does neither, or that declares a component the application does not record (a typo, or a component renamed since the run was planned), is refused as `platform_build_unavailable`, and the message lists the components the application knows. A single-component application's build stage may be called anything. A repository with no linked application is refused the same way, because it has nowhere to push whoever builds it.
* Every `build_args` entry must carry a literal value, written `NAME=value`. In-cluster, a bare `NAME` lets BuildKit read the argument from the build pod's own environment; the platform builder has no such environment, so a bare entry is refused as `build_fallback_unsupported` rather than built silently without the argument.

## Logic is open, authority is closed

Anyone who can push can change what a pipeline *does*: add stages, rewrite scripts, pick any image the organisation's policy allows, change conditions, matrices, `needs`, caches, artifacts and timeouts. What a run may *touch* is not the pull request's to decide. These sections are protected - they are resolved from the organisation's policy and the definition on the default branch, never from a pull request's copy of the file:

* `permissions` - the API scopes the run identity is minted with.
* `secrets` and `credentials` - each declared binding, by name, source and key.
* `on.pull_request.fork_policy`.
* `defaults.network` and a stage's `network` when it is above `egress-https`.
* `runs_on` on every stage - cluster, node selector, tolerations, runtime class - and the whole of `resources`: `gpu`, `cpu` and `memory`, so a head cannot ask for far more compute than the organisation meant to grant.
* A stage's `timeout`, so a head cannot remove its own or the trusted definition's and let a step run far past what was approved.
* A stage's `cache` block - `key`, `paths`, `size`, `restore_keys` and `fallback` - which decides whose earlier output is restored into this run's workspace.
* A stage's `with:` block, which is where a `gate` stage's own scan-tool configuration lives.
* The `services` block - each sidecar's image, environment and ports.
* A `gate` stage's approval roles and required stages, an `approval` stage's roles and minimum approvals, an `agent` stage in `agent` mode and its tool profile, a `webhook` stage's URL, an `external` stage's provider and workflow.
* The `environments` block - data policy, verification, rollout and gate per environment.

A stage the default-branch definition does not have gets no authority at all: adding a stage is free, adding a privileged stage is impossible.

Every run plans under one trusted authority, resolved in a fixed order: the default branch's own definition, once it declares no protected section at all (there is nothing to approve) or an administrator has approved that exact protected hash; failing that, the newest authority an administrator ever did approve on this repository; failing that, none. A pull request's *logic* always executes as written - its stages, scripts and images run - but its *authority* is whichever of those three the resolution landed on, never the pull request's own copy:

* **`approved`** - the head declares exactly the trusted authority. An ordinary pull request that changed no protected section reads this way.
* **`unapproved`** - a push to the default branch itself changed a protected section nobody has approved yet; the run executes under the last approved authority (or none) until an administrator does.
* **`changed_on_head`** - a pull request added a credential, widened its egress, or moved a step onto another node pool. The change is ignored for this run and surfaced, never silently granted because a commit landed.

The check run's summary and the commit status description lead with the authority sentence whenever a run is not `approved`, naming what changed and what to do about it; `GET /org/pipelines/definitions/{id}` reports the definition's `protected_hash` and whether it is the currently approved one. An administrator approves a repository's current protected sections with:

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/org/pipelines/definitions/<definition-id>/approve \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"
```

Needs `pipelines.manage` and a human actor - a service token cannot approve. Answers `409` rather than silently agreeing when the definition is no longer the repository's current default-branch definition (a later push replaced it) or is already approved. `POST /org/applications/{id}/pipeline/approve-definition` is the same act addressed by the application whose repository owns the definition, for a caller who holds the application's id and not the definition's; it resolves that address form and then runs exactly the checks above, mapping their three refusals onto the same `403` and `409`. `ankra pipeline definitions get <id>` and `ankra pipeline definitions approve <id>` are the CLI form of the same two acts, and are the ones the platform's own call to action names when a run executes under anything but plainly approved authority. The portal approves the same way, from **Settings → Pipelines → Pending approvals** or the run page, and so does the **Approve authority** button on the GitHub check run. Narrowing the image allow-list afterwards does not invalidate an approval, because the policy is applied at plan time and is not part of the hash.

> [!WARNING]
>
> **This release moves every definition's protected hash, so re-approve.** `services`, `cache`, `resources.cpu`/`resources.memory`, `timeout` and a stage's `with:` became protected in the same deploy, so the hash is now computed over more of the document and moves for every definition - including ones whose content did not change. Three consequences, all deliberate:
>
> * **Existing approvals keep applying, and still need re-approving.** A stored approval is read from the approval columns rather than re-derived, so it keeps granting authority and its own content supplies the trusted values for the newly protected sections too - an administrator did approve a committed file, and those sections were in the file they read. But the stored hash no longer describes what it fingerprints, and nothing backfills it, because re-stamping would assert an administrator reviewed five sections they have never seen. Approve the repository's current default-branch definition again to make the column true.
> * **A run planned before the deploy and dispatched after it refuses.** The dispatcher re-derives the trusted definition's hash and compares it against the hash the run recorded when it was planned, so a run whose steps were still pending across the restart concludes with an authority-hash mismatch and has to be re-run. The window is one restart wide; no compatibility shim carries the old form, deliberately, because the form will move again as more sections become authority.
> * **An old approval whose proving runs were pruned stops counting.** The last-approved fallback answers from the run history, so an approval with no surviving default-branch run to prove it is no longer a candidate. It fails closed and says so rather than silently: the run resolves to the baseline and its own status carries "No administrator has approved any authority for this repository yet" with the approve action beside it. Re-approving fixes it, because only the current default-branch definition can be approved and that definition is the newest default-branch run's own.

### What a step runs as

Every step is a hardened batch/v1 Job in the `ankra-ci` namespace, which enforces the Pod Security Standards' Restricted profile: uid and gid 65532, the `RuntimeDefault` seccomp profile, no privilege escalation, a read-only root filesystem, every capability dropped, no service account token, no service links, one attempt, an explicit deadline and a TTL. A pipeline cannot ask for host privilege, host namespaces, host paths or control-plane placement; the request is refused at plan time. The one relaxation is the rootless BuildKit pod a `build` stage runs, in its own `ankra-ci-build` namespace under the Baseline profile - never privileged, never root, and no pipeline can name its own build or checkout image: both are Ankra's own, pinned by digest. That build pod names no seccomp or AppArmor profile at all, which is the only spelling of "leave the builder alone" Baseline admits, and nothing can change it to `Unconfined`. On nodes whose runtime reads that as a confining default the builder cannot start, and the build is routed to Ankra's own builders instead ([`build_runtime_confined`](#when-something-fails)).

With the root filesystem read-only, a step can write to three places, and they differ in size and lifetime:

* **`/workspace`** is the run's shared volume: the checkout lands there, and it carries files from one step to the next. Anything large belongs here.
* **`/tmp`** is a 256 MiB memory-backed tmpfs, private to the step's pod and empty again at the next step. It counts against the step's memory, and a compiler or linker that stages intermediate files in `/tmp` runs out of space long before the workspace would. Point `TMPDIR` into the workspace for anything that writes big temporary files, with `export TMPDIR=/workspace/.tmp && mkdir -p "$TMPDIR"` at the top of the step's `run` script.
* **`/dev/shm`** is 64 MiB unless the stage sets `shm_size`.

uid 65532 has no `/etc/passwd` entry in most images, so every step gets `USER` and `LOGNAME` set to `ankra`, which is what lets `getpass.getuser()`, git and similar lookups resolve. `HOME` is `/tmp`, so a tool that writes a per-user config there works, but the 256 MiB limit above applies to it: point package caches and build output at `/workspace` instead. `HOME` and `TMPDIR` cannot be set in a stage's `env` (see reserved names below), so export them in the `run` script when a tool needs them elsewhere, where the change is visible in the step you wrote.

Beyond containment:

* **Network tiers.** `none` denies all egress, and is what a stage gets when neither it nor the pipeline's `defaults` names a tier - except for `checkout`, `build` and `scan`, whose only job is outside the cluster and which default to `egress-https` instead ([the tier a stage gets by default](/guides/pipeline-reference#the-tier-a-stage-gets-by-default)). `egress-https` permits 53/UDP and 53/TCP to the cluster's own DNS - the `kube-system` namespace, plus `169.254.0.0/16` for a cluster running NodeLocal DNSCache - and 443/TCP to public addresses only: RFC1918, `169.254.0.0/16`, `100.64.0.0/10`, `fd00::/8`, `fe80::/10` and AWS's `fd00:ec2::254` are all excluded, so a step on it reaches neither your private networks nor any cloud metadata endpoint that hands out the node's identity. A `checkout`, `build` or `scan` stage that explicitly declares `network: "none"` is honoured rather than widened back - the tier is clamped only on a restricted fork run (below) - but the validator warns what that stage loses, because a step with no way to reach its source, its base images or its vulnerability database is not one broken step, it is a pipeline that cannot run at all. `services` is deny-all plus the run's own pods and that same DNS rule; the sidecars a step declares are containers in its own pod, reached over loopback by name. A private destination a pipeline legitimately needs is named in [`ci_egress_allowed_cidrs`](#organisation-ci-settings), which renders as an extra peer on the 443 rule of the `egress-https` tier alone, is re-validated when the step is rendered rather than trusted from the settings row (an entry that fails that check is dropped and the rest of the list is still honoured), and rides on the step's payload so the agent renders the same policy. The **agent** is what renders that policy in your cluster, so until the agent release of 5 September 2026 reaches it, a step still gets the previous tier - 443 to every address but `169.254.169.254`, and 53 to any pod.
* **Image policy.** A `run` or `scan` stage's image is checked against `ci_allowed_image_prefixes` on the platform and again by the agent before anything runs; `checkout` and `build` always run Ankra's own pinned images regardless of the organisation's list. A named service's image goes through the same check, and a sidecar outside the policy refuses the whole step rather than running beside it. The **platform's** check is the one matched at a path boundary, and an entry ending in `/`, `:` or `@` admits exactly that boundary rather than matching nothing (above). The agent's own fallback check is still a plain textual prefix match, so a neighbouring registry path can satisfy it and a separator-terminated entry is read as plain text rather than as the boundary it names, until the agent release of 5 September 2026 reaches your cluster.
* **Resources.** A stage's `cpu` and `memory` are the step's limits. The step reserves half of the CPU (never under 100m, or the whole figure when the stage declares 100m or less) and all of the memory on its node, so it can use CPU up to its ceiling when the node has it free and can never take memory another step was given. It may ask for at most 8 CPU cores, 32 GiB of memory and 4 GPU devices, and a GPU step must name a `runs_on.node_selector`, so it is refused here rather than left Pending until it times out.
* **Reserved names.** A step may not set environment variables beginning `ANKRA_`, the loader and `PATH` variables, `HOME`, `TMPDIR`, `XDG_RUNTIME_DIR` and `XDG_CACHE_HOME`, or the image builder's own `BUILDKIT*`, `BUILDCTL`, `ROOTLESSKIT` and `DOCKER_CONFIG`. A service the step names may not set them either - those variables decide what a container actually executes, and a sidecar's process is no exception.
* **Secrets and credentials.** A declared binding is revealed once, to a file under `/run/agent-secrets` named after the binding, by the agent calling back with its own session token - never written into the step's payload or a log line. A `checkout` step's own git credential is granted the same way and read by a credential helper that answers only for the host it was minted for, so a malicious submodule URL cannot walk off with it.
* **Forks.** A pull request whose head lives in a fork - or whose provenance the delivery could not establish - runs with no secrets, no credentials and no identity beyond reading itself (`fork_policy: read_only`, the default). `checkout` and `build` both clone the fork's own head anonymously - never the pipeline's own repository - reading the head repository the trigger recorded on the run; `checkout` refuses outright, rather than guessing a remote, on the rare delivery whose fork head repository could not be established at all. `build` still runs (so a maintainer can see whether a contributor's change compiles) but renders with no push target, so nothing it produces can reach a registry; `scan` may still pull the image it built to report on, never a private one. Every stage but `checkout`, `build` and `scan` runs with no network at all, regardless of what the fork's own copy of the definition asks for - the tier is clamped, not merely left alone, so a fork-controlled `network: egress-https` on some other stage is not honoured just because these three need it. Beyond what such a run may *touch*, it is bounded in what it may *spend*: at most 8 matrix legs per stage, a 60-minute step timeout, 2 CPU and 4Gi per step, no sidecar services, no shared cache volumes, and 256 MiB of artifacts and logs for the whole run. The first four are imposed when the run is planned, so the plan a reviewer reads is the run that executes; caches are withheld at dispatch, and the artifact budget bounds what the run is granted from its declared sizes (the same ceiling on what actually arrived is in the artifact store, waiting on the settle lane that will call it). A `plan_fork_budget:` diagnostic names the ceilings, and one more diagnostic names each stage that hit one.
* **Permissions.** `pipelines.read` covers listing and reading runs, logs, artifacts, the stored definition, schedules and validation; `pipelines.operate` covers dispatch, cancel and re-run; `pipelines.manage` covers connecting a repository, replacing the stored definition, creating, changing and deleting schedules, the pipeline policy and its approvals, and a dispatch with a `--spec-file` override.

## When something fails

Every failed step carries an error class, and the class decides whose failure it is.

* **Yours, never retried automatically.** `step_failed` (the script exited non-zero), `step_refused` (the definition asked for something the policy or the renderer refuses - an image outside the allow-list, a missing script, too much compute, or a `build` step whose push target cannot be resolved: no application link, a component with no resolvable registry, or a stage that belongs to no component of the application), and `timeout`. A step that ran out of time did run; running it again is a retry policy to declare. The `retry:` block is validated and carried to the agent but not applied yet, so today a non-zero exit is final.
* **Ankra's, retried once.** `agent_infra` (the cluster could not create the namespace, bind the volume or pull the image), `worker_lost` (the agent claimed the step and stopped reporting), `result_malformed`, `agent_offline`, `agent_never_started` (no agent claimed the step inside its timeout - check that the cluster is connected and `ci_worker_count` is above zero), `build_runtime_confined` (below), `execution_vanished` and `stranded`. Each of these writes the next attempt instead of a conclusion, up to two attempts in total; the second failure concludes the step as `infra_error`, and the check run settles as `action_required` naming the class - Ankra failing never reads as your code failing.
* **`build_runtime_confined`: your nodes confine the image builder, and no setting relaxes it.** A `build` stage runs rootless BuildKit in a pod that deliberately names **no** seccomp or AppArmor profile, because the Pod Security Baseline profile the `ankra-ci-build` namespace enforces forbids `Unconfined` - naming it would leave the pod refused by the very namespace admitting it. On a node whose runtime resolves "names none" to a *confining* profile - containerd on an Ubuntu host applying its default AppArmor profile, or a kubelet with seccomp defaulting applying `RuntimeDefault` - rootlesskit cannot make its mount namespace private, and the builder dies before BuildKit starts and before anything in your Dockerfile is read. The pod exits non-zero, so the agent reports it as your failure; it is not, and the settle loop re-classes it. **There is no cluster, organisation or pipeline setting that renders the build pod `Unconfined`**, and that is by design rather than an omission - nothing about a pod spec can defeat the node's own default from inside Baseline. The supported answer is [Ankra platform builders](#ankra-platform-builders), which takes two things: `ci_build_fallback: platform_builders`, which is the default, and the platform builds grant, which Ankra makes per organisation on request (that section says how to confirm it and how to ask). With both, the retry, and every later build on that cluster, is routed to Ankra platform builders and the step's `executor` records it. The verdict is remembered per cluster against the agent version and builder image it was observed under, so a cluster pays this failure once rather than on every run - and re-probes by itself when either moves. With the fallback set to `none` the build is refused instead, naming the containment and telling you to set the fallback or run the pipeline on a cluster whose runtime leaves the builder unconfined. With the fallback already `platform_builders` but the grant not yet made, the retry concludes `build_fallback_none` with a sentence saying Ankra's platform-operated build fallback is not enabled for this organisation yet: no setting of yours changes that, so ask Ankra for the grant, then re-run. Every other stage kind is unaffected: `checkout`, `test`, `scan` and `gate` run in-cluster on a confining node exactly as anywhere else.
* **Ankra's, never retried.** `step_stranded` - a step still `pending` after its run has outlived the sum of every step's own `timeout` (capped at the same 6-hour ceiling one step is held to, plus a grace window). It concludes as `infra_error` with a sentence saying it never started and pointing at the cluster's agent and its `ci_worker_count`. A fresh attempt is not written, because it would face the identical exhausted budget; the value of the sweep is that the run concludes rather than sitting open forever. `report_unreadable` joins it: a `scan` step that concluded **successfully** but whose report Ankra could not download or parse is revised to `infra_error` carrying "Ankra could not read the *`<report>`* report this step produced, so its findings were not recorded." Ankra failing to read what a scanner said is not the same fact as the scanner having passed, so it is never recorded as clean. `report_unreadable` used to be what an organisation with no backup vault got on every scan step it ran; now that such an organisation's artifacts go to the [Ankra-managed default vault](#before-your-first-run), it means what it says - the object was never uploaded, or came back unparseable. The remaining causes are a run that had already spent its 2 GiB artifact budget before the report was due, and a vault whose bucket stopped answering. With no ready vault on either side, a `scan` step is refused before it runs instead, with error class `artifact_store_unavailable` and the sentence "This step's reports need a ready backup vault in the organisation, and there is none." A step that had already failed, timed out or hit `infra_error` keeps its own verdict - that is a more specific answer than this one.
* **Timeouts.** A stage runs under its `timeout`, or `defaults.timeout`, or 30 minutes; the ceiling is 6 hours and a longer value is clamped and recorded. The agent stops a step at its deadline with a 60-second grace, and a reaper on the platform sweeps every 30 seconds for steps two watchdogs missed - a step five minutes past its deadline, an agent that has not checked in for ten. The run itself is heartbeated while any of this is going on, so a long pipeline is not failed by the platform's own stale-run reaper for taking longer than twenty minutes.
* **Cancel.** `ankra pipeline cancel <run>`, `POST …/pipeline-runs/{run_id}/cancel`, or the **Cancel** button on the check run while the run is live. A run that is cancelled concludes with outcome `cancelled`.
* **Re-run.** `ankra pipeline rerun <run>` (add `--failed-only` to re-run only the steps that did not succeed, whatever depends on them, and the steps they build on), `POST …/pipeline-runs/{run_id}/rerun`, or GitHub's own **Re-run** button on the check. A re-run is a new run with `rerun_of_run_id` pointing at the old one; the old run's outcome stays the record of what happened. It re-plans from the **original run's own definition**, not from whatever the pipeline has become since, so re-running a month-old run reproduces it rather than quietly executing a different pipeline.
* **Failed-only re-runs start from an empty workspace.** A re-run gets a workspace of its own - the original's is removed once it concludes - so `--failed-only` re-runs the checkout and every upstream step whose output a repeated step reads (through `needs`, and for a `gate` the stages in its `require_stages`) together with the failed steps and their dependents. Steps that succeeded and that nothing repeated needs, such as a publish after the failure, are not repeated. A failed-only re-run that could not run a step that failed - a stage limited by `when.events` to `push`, which a re-run's `rerun` trigger filters out - is refused with the reason for each such step, rather than queued to pass without it.

### Diagnosis codes

A step that failed for a reason Ankra recognises, or that has waited more than two minutes for its pod to start, carries a `diagnosis`: a stable `code`, a `title`, a `next_step` and, where there is one, the cluster's or the provider's own words in `detail` (cleaned of hidden characters and anything that looks like a credential, and cut to 300 characters). The run carries the one a reader should act on first in its own `diagnosis`, and the run page shows it above the steps. A step that failed in its own script has no diagnosis, because its log is the answer. A running step whose cluster events could not be read says so in `diagnosis_unavailable` rather than showing nothing.

Ankra reads the evidence it already has, so nothing extra runs on your cluster: the step's error class and the agent's message, the Kubernetes events on the step's pod and its workspace volume, the Cluster Autoscaler's events, and, for node groups Ankra scales, its own record of the node create the provider refused. It reads only events of clusters your organisation owns.

**Why a step, or a CI cluster, is waiting**

| `code` | What it means | What to do |
| - | - | - |
| `provider_quota_exceeded` | The cloud provider refused a new node for a project or account limit, such as Hetzner's `403 resource_limit_exceeded: shared core limit exceeded`, an AWS vCPU limit or a GCP or Azure quota | Raise the limit with the provider. On Hetzner, open the Cloud console, the account menu, **Limits**, **Request change**; the `next_step` field names the shared or dedicated vCPU or server limit. Or add another CI cluster to the pool with `ankra org ci-settings pool add <cluster>` |
| `provider_volume_quota_exceeded` | The provider refused the step's workspace or cache volume for a volume limit | Delete detached volumes nothing uses, raise the volume limit, or add a pool member |
| `scale_up_failed` | The autoscaler asked for a node and it was not added, for a reason that is not a known quota | Check the CI cluster's node groups; the autoscaler tries again after its back-off. Or add a pool member |
| `node_group_at_max` | Every node group that could run the step is at its maximum size | Raise the node group's autoscaling maximum, or add a pool member |
| `no_node_group_fits` | No node group's node type has enough CPU or memory for the step, so adding nodes would not help | Lower the stage's `resources`, or add a node group with a larger node type |
| `insufficient_capacity` | No node has room for the step and nothing is adding one | Enable autoscaling on the CI node group, add nodes, or add a pool member |
| `run_node_full` | The step shares the run's workspace volume, so it must run on the node that holds it, and that node is full | It starts when the run's other steps finish. Lower the stage's `resources` to fit more steps on one node |
| `image_pull_auth` | The registry refused the step's image to the cluster's credentials | Check the image name, then add the registry's credential to the organisation, or use a public image |
| `image_pull_failed` | The cluster could not pull the image for another reason | Check that the image name and tag exist and that the registry is reachable from the cluster |
| `volume_unavailable` | The step's volume could not be provisioned, attached or mounted | Check the CI cluster's StorageClass and CSI driver. A volume still detaching from another node clears on its own |
| `scale_up_in_progress` | The autoscaler is adding a node for the step | Nothing; a new node usually joins in one to three minutes |
| `run_reservation_pending` | The run's first step is waiting for a node with room for the whole run's reservation (the run reservation is on for the cluster); the `next_step` names the room and says whether a node is being added | Nothing while a node is being added. If the node group is at its maximum or the provider refused a node, the same remedy as `node_group_at_max` or the quota codes. To stop holding room, `ankra cluster agent ci set --run-reservation off` |

**Why a step or run failed**

| `code` | What it means | What to do |
| - | - | - |
| `out_of_memory` | The kernel killed the step at its memory limit; the `next_step` field names the limit | Raise the stage's `resources.memory`, or make the step use less. When the run did not take the stage's resources because the definition is not approved, approve it instead |
| `stage_exceeds_node_size` | The stage asks for more CPU or memory than any node of the CI cluster offers, so it can never start | Lower the stage's `resources`, or add a node group with a larger node type |
| `build_runtime_confined` | The cluster's node runtime stops the rootless image builder (see [When something fails](#when-something-fails)) | Keep `--build-fallback platform_builders`, or build on a cluster whose runtime allows the builder |
| `image_pull_auth`, `image_pull_failed` | As above, for a step that gave up on its image | As above |
| `deadline_exceeded` | The step ran longer than its `timeout` | Raise the stage's `timeout`, or make the step faster; caches help most |
| `deadline_exceeded_waiting` | The step's whole time budget went on waiting for its pod to start; when the agent's message quotes the cluster's reason, the `next_step` field names what held it | Fix that (see the waiting codes), then run the pipeline again |
| `no_ci_cluster` | The organisation has no CI cluster | `ankra org ci-settings set --cluster <cluster>`, then run again |
| `definition_needs_approval` | An administrator has not approved the pipeline definition, so the run did not execute its protected sections as written | Approve it on the run page or with `ankra pipeline definitions approve <id>`, then run again |

**A notice on a passing step**

| `code` | What it means | What to do |
| - | - | - |
| `cache_volume_fallback` | The step's caches ran without a persistent volume, so the next run starts cold. Its `category` is `notice`, not `failure` | Give the CI cluster a default StorageClass. Runs from forks and tags never share caches, by design |

The codes are a fixed vocabulary that monitoring and scripts can key on; the sentences may be reworded.

### Status is the lifecycle, outcome is the verdict

A run and each of its steps carry two fields, and only one of them says how the work ended. `status` is where the work is in its life; `outcome` is how it finished, and it is `null` until `status` is `concluded`. This is the same split as GitHub Actions' `status` / `conclusion`: a monitor that filters steps on `status == "failure"` matches nothing, because every finished step is `concluded` - read `outcome` for the verdict.

| Field | On a run | On a step |
| - | - | - |
| `status` | `queued` (created, no step has started), `running` (work in flight), `concluded` (finished; always carries an outcome) | `blocked` (waiting on its dependencies), `pending` (dependencies satisfied, not yet claimed by a worker), `running` (claimed and started), `concluded` (finished; always carries an outcome) |
| `outcome` | `null` until `concluded`, then one of the values below | `null` until `concluded`, then one of the same values |

The outcome vocabulary is one set for runs and steps alike:

| `outcome` | Meaning |
| - | - |
| `success` | The work did what was asked |
| `failure` | Your own work failed - a non-zero exit, a refused definition, a gate that blocked. The error class says which |
| `cancelled` | Stopped on purpose - `ankra pipeline cancel`, the API, or the check run's **Cancel** button |
| `timed_out` | The work exceeded its `timeout` |
| `skipped` | The work never ran: a dependency did not succeed, an `if:` excluded it, or - for a run - the trigger's branch, tag or path filter excluded every stage |
| `infra_error` | Ankra failed, not your work - a retried `agent_infra` or `worker_lost` that failed twice, a `step_stranded`, a `report_unreadable` |

A run's outcome folds its steps' outcomes: `success` when every step succeeded or was skipped, otherwise the worst of what its steps reported. `ankra pipeline get <run>` prints the outcome in place of the status once there is one, with a glyph per state - `✓ success`, `✗ failure` / `timed_out` / `infra_error`, `⊘ cancelled`, `○ skipped`, and `⟳` only for a run or step that has not concluded (`○` for a blocked step) - and `-o json` carries both fields verbatim.

A run also records the protected authority it executed under, as `authority_state` (the `Authority:` line in `ankra pipeline get`):

| `authority_state` | Meaning |
| - | - |
| `approved` | The run executes the authority its head declares: the default-branch definition either declares no protected section, or an administrator approved exactly what it declares, and the head changes nothing |
| `unapproved` | A run of the default branch whose definition changed protected authority no administrator has approved yet. It executes under the last approved authority - or under none, when nothing was ever approved - until one does |
| `changed_on_head` | A run of a head that is not the default branch (a pull request, another branch) whose definition declares different authority. It executes under the default branch's; the head's change is ignored and surfaced on the check run and the pull request comment |
| `null` | The planner never resolved authority for this run: it is still `queued`, it concluded `skipped` because the trigger filter excluded every stage before planning ever ran, or it was planned before authority tracking existed. `null` means "not recorded", never "no authority" |

`authority_hash` and `authority_definition_id` sit beside it and are `null` in the same cases. See [Logic is open, authority is closed](#logic-is-open-authority-is-closed) for what each state means for the run's protected sections.

## Limits and defaults

| Limit | Value |
| - | - |
| Step timeout | 30 minutes when neither the stage nor `defaults` sets one; at most 6 hours, longer values are clamped |
| Automatic retry | One, for Ankra's own failure classes only; two attempts in total |
| User-declared retry | `retry.max_attempts` at most 5; not applied yet |
| Matrix | At most 64 legs per stage after exclusions; a larger matrix is refused, not truncated |
| Step compute | Default 500m CPU and 1Gi memory; at most 8 cores, 32 GiB and 4 GPUs. A step reserves half its CPU (at least 100m, or the whole figure when that is 100m or less) and all of its memory, and may use CPU up to the declared figure |
| `shm_size` | 64Mi unless the stage sets it |
| Workspace | One volume per run, shared by every step; `rwo` pins every step of the run to the node its volume is attached to. `rwx` is refused at dispatch today: the claim must name a StorageClass that serves it, and nothing sets one yet |
| Caches | Each cache path is kept per repository and trust scope, restored before a step and saved after it succeeds; at most 4 GiB per saved path and 10 GiB per repository, least recently used first. On an agent without cache archives, one 5Gi volume per path, or nothing with `fallback: none`. A restricted fork run and a tag run get none. See [Caches](/guides/pipeline-reference#caches) |
| Fork budgets | A restricted fork run: at most 8 matrix legs per stage, a 60-minute step timeout, 2 CPU and 4Gi per step, no sidecar services, no shared caches, and 256 MiB of artifacts and logs for the whole run |
| Parallelism | 16 runs per organisation and 8 steps per run at once by default, up to 64 and 256; the CI cluster's agent runs at most `ci_worker_count` steps at once (0 to 128, or 0 to 32 on older agents); org-fair claiming; a step waiting for a CI slot does not use up its timeout |
| Artifacts | 512 MiB per object, 2 GiB per run, 20 uploads per step; download links are valid for 5 minutes |
| Retention | Artifacts and step logs 30 days by default (1 to 365), caches 14 days (1 to 365), concluded runs 90 days (7 to 365) |
| Run budget | A `pending` step is reaped once its run outlives the sum of every step's `timeout`, capped at 6 hours plus a grace window; it concludes `infra_error` / `step_stranded` and is not retried |
| Secret and credential grants | At most 32 bindings per step; each revealed once, alive for the step's own timeout plus 15 minutes, capped at 7 hours |
| Step outputs | `$ANKRA_OUTPUT` takes `key=value` lines, at most 64 KiB, recorded on the step |
| Live log | 1,024 lines are queued; when the reader falls behind the agent blocks for 250 ms and then drops, writing a `… N lines dropped` marker where the loss happened; the uploaded log keeps the last 8 MiB. The dropped count is recorded on the step and shown under its row on the check run and the status comment |
| Log history | The live stream has no replay: a live connection shows output from the moment it connects; the complete log is the `step.log` artifact, which `ankra pipeline logs` reads automatically for a step that has already concluded, from the CLI's next release. `step.log` is an object in the organisation's ready backup vault, or in the Ankra-managed default vault when it has none, so history is kept either way; only with no ready vault on either side is there none - just what a live connection caught |
| Expressions | A template of at most 8,192 bytes with at most 64 expressions, each at most 2,048 bytes and 24 levels deep |

## Bring your own CI (GitHub Actions)

You do not have to delete your existing CI to try Ankra Pipelines - the [generated GitHub Actions workflow](/guides/cicd-pipeline) keeps building, scanning and publishing images to your registry, and a pipeline run on the same commit is a second, independent check, `Ankra pipeline` beside the workflow's own. But connecting the repository is not inert: the moment `.ankra/pipeline.yaml` is the definition of record and the organisation has a CI cluster, the application is read as pipeline-sourced and its pull-request **previews** switch to the pipeline's own digest from then on - not when you decide you trust it. A merge to your default branch is more forgiving, because your own CI's build observation always outranks the pipeline's for it, so the workflow stays what actually deploys production until the pipeline's `publish` catches up or you retire the workflow. Retirement is deliberate either way: Ankra will not delete a workflow for you; when it does propose one, it will be a reviewable pull request.

`build` and `publish` now run in the cluster, so a pipeline can publish your image on its own once you trust it - review [what to check after conversion](/guides/migrate-from-github-actions#what-to-review-after-conversion) first, and keep the workflow live until you have watched the pipeline publish correctly a few times. [Migrate from GitHub Actions](/guides/migrate-from-github-actions) explains how a converted pipeline maps onto it and what to review; an application already connected to Ankra can skip the manual conversion entirely and [migrate with one call](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call).

## Commands and API

Every command addresses one pipeline with `--application <name-or-id>` or `--repository <repository-id>`. Run from inside a checkout, both are optional: the CLI resolves the application from the repository your `origin` remote points at, and says which one it used. It asks for the flag when the working directory answers nothing, or names the candidates when the repository carries more than one application. `ankra application pipeline …` is the same set of commands with a leading `<application-id>` argument. Tables by default, `-o json` for the wire shape.

| Command | What it does |
| - | - |
| `ankra pipeline run [--sha <sha>] [--ref <ref>] [--input k=v] [--reason <text>] [--wait]` | Dispatch a manual run at a commit the repository owns - the sha is resolved against the repository's own host and refused when it is neither a reference's tip nor a provable ancestor of one. `--spec-file` runs a definition of your own (`pipelines.manage`): it is stored on the run and both the planner and the dispatcher render from it, while the run's authority still comes from the default branch's approved definition |
| `ankra pipeline list [--status queued\|running\|concluded] [--trigger …] [--branch …] [--head-sha …] [--limit N] [--cursor …]` | List runs, newest first, keyset paginated |
| `ankra pipeline get <run>` | A run and its step table |
| `ankra pipeline logs <run> --step <key> [--follow]` | A running step's live output, reconnecting through a dropped stream with `--follow` until it concludes; a concluded step's complete output from the CLI's next release, before that only what a live connection happened to catch |
| `ankra pipeline cancel <run>` | Stop a run that has not concluded |
| `ankra pipeline rerun <run> [--failed-only] [--wait]` | Open a new run from a concluded one |
| `ankra pipeline artifacts <run>` and `artifacts download <artifact-id> [--out <file>]` | List a run's stored logs and artifacts, and fetch one through its presigned URL |
| `ankra pipeline findings <run>` | List a run's persisted scan findings by tool and severity (CLI's next release) |
| `ankra pipeline validate [file]` | Validate and dry-run a definition without writing anything |
| `ankra pipeline definition get\|put <file>` | Read or replace the stored definition of record |
| `ankra pipeline schedules list\|create\|update\|delete` | Manage cron schedules (`--cron`, `--timezone`, `--ref`, `--input`, `--enabled`) - stored, validated and now fired |
| `ankra pipeline train list\|add <pull request>\|remove <entry>\|enable [--max-cars N]\|disable` | The repository's [merge train](#the-merge-train-test-every-pull-request-as-it-will-merge): test each pull request as it will merge, then merge it |

`ankra pipeline repositories connect|list|get|disconnect`, `ankra pipeline definitions get|approve`, `ankra pipeline findings`, the concluded-step behaviour of `logs` and artifact listings that carry a status have all merged and ship in v0.15.0, which is a pre-release today - enable the [beta channel](/integrations/ankra-cli#beta-pre-release-channel) to get them, or use the API and the portal until v0.15.0 is stable. `ankra cluster agent ci get|set`, which turns a cluster's pipeline-step workers on, lands in `v0.15.0-rc3`; until then that setting is `PUT /api/v1/org/clusters/{cluster_id}/agent/ci-settings` on the API.

The same run and repository operations are on the API under `/api/v1/org/applications/{application_id}/pipeline-runs`, `/api/v1/org/pipeline-repositories/{repository_id}/pipeline-runs` and `/api/v1/org/pipelines/repositories` with a bearer [token](/reference/tokens): list and create runs, `…/{run_id}`, `…/{run_id}/rerun`, `…/{run_id}/cancel`, `…/{run_id}/steps/{step_id}/logs` (server-sent events, resumable with `from_seq`), `…/{run_id}/artifacts`, `…/artifacts/{artifact_id}/download` (a `302` to a presigned URL), and beside them `…/pipeline` (`GET`, `PUT`), `…/pipeline/validate`, `…/pipeline/schedules`, `…/merge-train` (`GET`), `…/merge-train/settings` (`PUT`), `…/merge-train/entries` (`POST`) and `…/merge-train/entries/{entry_id}` (`DELETE`), and `…/pipelines/definitions/{id}[/approve]`. Creating a run answers `202` with the run id and its number; connecting a repository answers `201` with the repository and what happened to its committed definition, or `409` naming the one that already exists.

## What comes next

These are on the plan of record and not available yet. None of them is usable today, and this page will say so when that changes.

* The runner for `verify` (HTTP probes, smoke scripts, k6 load tests, PromQL assertions, restore verification).
* The per-run identity that `permissions` mints, so a step can call the `ankra` CLI with exactly the authority the default branch granted; `cloud` and `object_storage` credentials once it exists.
* The built-in `ankra/*` step library behind `uses:`, organisation step templates, and `custom_tool/<name>` steps.
* The executors for the `preview` (inside the pipeline DAG), `agent`, `approval`, `webhook`, `automation`, `ankra` and `external` stage kinds; `on.webhook` inbound dispatch tokens. Each of those stages validates with a warning and is skipped today, so declaring one costs you the stage, not the run.
* The user-declared `retry` block being applied; dynamic matrices that fan out over a previous step's output; a dedicated run page in the portal (the Pipelines section shows runs today; a standalone page with more depth is still to come).
* Attestations and SBOM referrers carried onto the digest `publish` re-tags into your real repository, not only the one `build` pushes to staging.
* Merge-when-green, automatic disposition re-evaluation, and planning from the committed file at a run's own commit, on GitLab and Bitbucket Cloud (GitHub only today).
* The agent release that publishes live step output on the dedicated `pipeline_output` stream the platform already reads. (The narrower `egress-https` with its `ci_egress_allowed_cidrs` allow-list, and the image-prefix boundary check, were listed here and have since shipped on both the platform and the agent - see [What is in place today](#what-is-in-place-today).)
* Environments hydrated from restore points, verification stages, promotions with approvals, and canary rollouts through Traefik weighted traffic.

## Next steps

> [card] [pipeline.yaml reference](/guides/pipeline-reference)
>
> Every key, the expression language, the trigger table and the diagnostics the validator reports.

> [card] [Migrate from GitHub Actions](/guides/migrate-from-github-actions)
>
> Convert a workflow, GitLab CI file, Bitbucket pipeline or CircleCI config and review what changed.

> [card] [Application CI/CD](/guides/cicd-pipeline)
>
> The generated GitHub Actions workflow, registry authentication and image retention.

> [card] [Backup vaults](/concepts/backup-vaults)
>
> Where pipeline logs, artifacts and scan reports are kept - a ready one is a precondition for a run.


# Run tests and lint in Ankra Workspaces
Source: https://docs.ankra.ai/guides/ankra-workspaces

Send the heavy commands of your development loop - go test, golangci-lint, pnpm typecheck and test, Playwright - to a warm pod on your organisation's CI pool instead of your laptop, by hand with ankra exec or automatically for you and your coding agents with ankra dev install.

An **Ankra Workspace** is your own long-lived pod on the organisation's CI pool, one per repository (and per kind, such as `node` or `e2e`). `ankra exec` runs a command for your current checkout in it: your uncommitted changes go with it, the output streams back live, and the exit code is the remote command's own. `ankra dev install` puts small shims in front of `go`, `golangci-lint`, `pnpm` and friends so that the heavy commands you, your editor, git hooks and coding agents already run go to the workspace without anyone typing anything different.

The point is your laptop's CPU and memory: five coding agents each running `go test ./...` or a full typecheck stop fighting over one machine.

## Prerequisites

* **The Ankra CLI**, logged in to the organisation that owns the repository:

  ```bash theme={null}
  brew install ankraio/tap/ankra    # or: brew upgrade ankra
  ankra login
  ankra org current
  ```

* **The `workspaces.use` permission.** Organisation admins have it; ask an admin to grant it otherwise. A workspace you cannot reach answers "not found", like one that does not exist.

* **A git checkout whose `origin` remote is a repository connected to Ankra Pipelines** in that organisation. If it is not connected yet, see [Connect a repository for Workspaces](#connect-a-repository-for-workspaces).

## Run your first command

From anywhere inside the checkout:

```bash theme={null}
ankra exec --check && echo "this checkout can use a workspace"
ankra exec -- go test ./...
```

The first command in a repository brings its workspace up, which takes a few minutes while the pod is scheduled, the image is pulled and the profile's tools are installed. `ankra exec` says what it is waiting for (`still provisioning: Pulling image ...`). Later commands reuse the warm pod and start in a second or two.

The command runs in the same relative directory as your shell, against your worktree exactly as it is: tracked files plus untracked files that git does not ignore. Your branch, index and working tree are never touched, and only what the workspace does not already hold is uploaded.

## Route commands automatically

```bash theme={null}
ankra dev install
ankra dev status
```

`ankra dev install` writes the shims to `~/.ankra/dev/shims` and links them into `~/.local/bin`, so every new shell, editor, git hook and coding agent session picks them up. If `~/.local/bin` is not on your `PATH`, or a real tool comes before it, the command prints the exact `PATH` line to add to your shell profile; it never edits a profile for you.

Each shim decides per invocation:

| Where it runs | Commands |
| - | - |
| In the workspace | `go test`, `go vet`, `go build` (without `-o`, `-c`, coverage or profile files), `golangci-lint run`, `gofmt -l` / `-d`, `pnpm` / `npm` `typecheck`, `test`, `test:ci`, `test:unit`, `lint`, `lint:*`, `format-check`, `knip`, `vitest run`, `tsc --noEmit` |
| In the workspace, changes applied to your worktree | `go generate`, `go mod tidy`, `go get`, `go fmt`, `go tool ...`, `gofmt -w`, `golangci-lint run --fix` |
| In the workspace, results copied back | Playwright runs (`pnpm test:e2e*`, `npx playwright test`): `test-results` and reports |
| On your machine | Everything else: `go run`, `go install`, dev servers, builds with output, `pnpm install` / `add`, anything interactive (`--ui`, `--debug`, `--headed`) |

A routed command behaves exactly like `ankra exec`: same output, same exit code. When a checkout cannot use a workspace - its repository is not connected, you are not logged in, you are offline - or the workspace could not run the command, the real tool runs on your machine instead, so nothing ever blocks on the platform.

```bash theme={null}
ANKRA_EXEC_EXPLAIN=1 go test ./...   # prints route or local, runs nothing
ankra dev mode local                 # stop routing (ankra dev mode auto to resume)
ANKRA_EXEC=local go test ./...       # run one command locally
ankra dev install --uninstall        # remove the shims and their links
```

## Commands that write files or produce results

```bash theme={null}
ankra exec --apply -- gofmt -w ./cmd
ankra exec --kind e2e --fetch test-results -- pnpm test:e2e
```

* `--apply` brings the files the command changed in the workspace back as a patch applied to your worktree. A patch that no longer applies (you edited the same lines meanwhile) is kept under `.git/ankra-exec-unapplied-<run>.patch`.
* `--fetch DIR` copies a directory back after the run, replacing your local one, whatever the exit code.

Only an allowlisted environment is forwarded (`GOFLAGS`, `NODE_OPTIONS`, `TZ` and similar). Add your own variable names, never secrets, with `ANKRA_EXEC_FORWARD_ENV=MY_FLAG,OTHER_FLAG`.

## Manage your workspaces

```bash theme={null}
ankra workspace status
ankra workspace up --wait            # bring it up ahead of the first command
ankra workspace down --yes           # tear it down; the next command brings a fresh one
ankra workspace down --yes --kind e2e
```

A workspace that has not been used for 24 hours is torn down for you. Changing the repository's workspace profile replaces the workspace at the new size the next time it is brought up.

## Connect a repository for Workspaces

A repository has to be connected to Ankra Pipelines in your organisation before anyone can use a workspace for it. If the repository's pipeline runs somewhere else - in another organisation or another CI - connect it for Workspaces only, so Ankra never reads its pipeline file, starts a run or posts a check on its pull requests:

```bash theme={null}
ankra pipeline repositories connect --provider github --owner my-org --name my-repo \
  --credential <github-credential-name> --workspaces-only
ankra pipeline repositories set-mode <repository-id> workspaces-only   # or: pipelines
```

Connecting needs the `pipelines.manage` permission.

## Give a repository a workspace profile

Without a profile, the workspace uses the image of the repository's pipeline. A **workspace profile** says exactly what the pod needs: its image, CPU and memory, disk, service containers (a database the tests reach by name), pinned tools to install and setup commands to run once. A repository can have several kinds, such as `default`, `node` and `e2e`; `ankra dev` uses the `go` kind for Go tools, `node` for pnpm, npm and npx, and `e2e` (or `playwright`) for Playwright runs when the profile has them, and `default` otherwise.

```json theme={null}
{
  "profiles": {
    "default": {
      "image": "golang:1.26.3-bookworm",
      "resources": { "cpu": "6", "memory": "16Gi" },
      "volume_size": "40Gi",
      "services": [
        {
          "name": "postgres",
          "image": "postgres:17",
          "env": { "POSTGRES_HOST_AUTH_METHOD": "trust", "PGDATA": "/tmp/pgdata" },
          "ports": [5432],
          "ready": { "tcp": "5432" }
        }
      ],
      "tools": [
        {
          "name": "golangci-lint",
          "url": "https://github.com/golangci/golangci-lint/releases/download/v2.12.2/golangci-lint-2.12.2-linux-amd64.tar.gz",
          "sha256": "8df580d2670fed8fa984aac0507099af8df275e665215f5c7a2ae3943893a553",
          "strip_components": 1
        }
      ],
      "setup": ["golangci-lint version"]
    }
  }
}
```

* **`tools`** are downloaded once, checked against their `sha256` and put first on the `PATH` of every command. A `.tar.gz` or `.tgz` URL is unpacked; anything else is the executable itself.
* **`setup`** runs once per workspace, before the first command, in the checkout.
* **Services and commands run as uid 65534.** An image that writes where only its own user may, such as postgres, needs pointing at a writable directory (`PGDATA` above).
* **`resources.memory` is the limit for every command in the workspace together.** Heavy commands queue for a share of it, so several agents can run at once without the kernel killing the pod. If a command still runs it out of memory, `ankra exec` says so and names the limit to raise.
* The image must match one of the organisation's allowed CI image prefixes.

Store the profile with the API, which needs `workspaces.manage`:

```bash theme={null}
curl -fsS -X PUT \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" -H "Content-Type: application/json" \
  --data @workspace-profile.json \
  "https://platform.ankra.app/api/v1/org/pipeline-repositories/<repository-id>/workspace-profiles"
```

Find the repository id with `ankra pipeline repositories list`.

## Troubleshooting

| What you see | What it means | Fix |
| - | - | - |
| `ankra exec` exits `196`, or a routed command quietly runs on your laptop | The checkout cannot use a workspace: not logged in, the `origin` repository is not connected in the selected organisation, or you lack `workspaces.use` | `ankra login`, `ankra org current`, `ankra exec --check`; connect the repository |
| `still provisioning: Waiting for a node ...` | The CI pool is adding a node for your workspace | Wait; the first workspace on a fresh node takes a few minutes |
| `[devbox] got a run slot after Ns` | Other heavy commands were using the workspace's memory; yours waited its turn | Nothing; raise `resources.memory` if waits are long and frequent |
| `The command ran out of memory ...`, exit `137` | The command (or several together) exceeded the workspace's memory limit | Raise `resources.memory` in the profile |
| A test passes locally but fails only in the workspace | The image or tools differ from your machine | Pin the same tool versions in the profile's `tools` |

Every run appends one line to `~/.claude/logs/ankra-exec.log` (or `ANKRA_EXEC_LOG`) with the repository, exit code, duration and command, which is the first place to look when a routed command behaved unexpectedly.

See also the CLI reference for [`ankra exec`](/reference/cli/exec), [`ankra workspace`](/reference/cli/workspace) and [`ankra dev`](/reference/cli/dev).


# Environments and Branch Rules
Source: https://docs.ankra.ai/guides/application-environments

Deploy one application to production, staging and development, and choose which branches' pushes reach each environment.

An application can run in several environments. Each environment is a cluster and a namespace with a name, such as `production`, `staging` or `development`. A **branch rule** on an environment lists the branches whose pushes deploy to it. With rules in place, a merge to `main` reaches production, a push to `develop` reaches development, and a `release/*` branch reaches staging, from one application and one pipeline.

This page builds on [push to deploy](/guides/deliver-your-app#how-a-merge-redeploys). Push to deploy has to be on for an environment before its rule deploys anything.

***

## What a branch rule is

A branch rule is a list of branch patterns. A push to a branch the list matches deploys to the environment.

An environment with **no rule** follows the application's tracked branch, which is how every environment behaves until you give it a rule.

Pull requests never deploy to an environment, whatever the rule says. They get [PR preview environments](/guides/pr-preview-environments) instead.

### Typical setups

| Environment | Rule | Deploys pushes to |
| - | - | - |
| `production` | `main` | `main` only |
| `staging` | `release/*` | Release branches such as `release/2.4` |
| `development` | `develop` | `develop` only |
| `development` | `**`, `!main` | Every branch except `main` |

### Pattern syntax

Patterns use the same matching as a pipeline stage's [`when.branches`](/guides/pipeline-reference#fields-common-to-every-stage), so a pattern means the same thing in a pipeline and in an environment.

| Pattern | Matches | Does not match |
| - | - | - |
| `main` | `main` | `main-v2`, `feature/main` |
| `release/*` | `release/2.4` | `release/2.4/hotfix`, `release` |
| `release/**` | `release/2.4`, `release/2.4/hotfix` | `releases/2.4` |
| `**` | Every branch | Nothing |
| `!main` | Every branch except `main` | `main` |

* `*` matches within one path segment. It never crosses `/`.
* `**` matches across `/`.
* `!pattern` removes the branches the pattern matches.
* Patterns are evaluated in order, and the last pattern that matches a branch decides. So `**`, `!main` is every branch except `main`, while `!main`, `**` is every branch.
* A list whose first pattern is negated starts from every branch. `!main` on its own therefore means every branch except `main`.

An invalid pattern is refused when you save the rule, with a sentence that names the problem.

***

## How a build reaches an environment

1. **A push builds.** The pipeline runs for the pushed branch. When its `publish` stage succeeds, Ankra records the image it published, `sha-<7>`, as that branch's newest build.
2. **Each environment picks its build.** An environment deploys the published build whose push came last, of any branch its rule matches. An environment with no rule deploys the newest build of the tracked branch, as before.
3. **Older builds never win.** A build of an older commit that finishes late never moves a branch back to that commit.

Only a push run whose `publish` stage succeeded records a build. A run that fails, is skipped, or never reaches `publish` deploys nothing anywhere.

> [!NOTE]
>
> The [generated pipeline](/pipelines/generated-pipelines#what-the-generated-pipeline-contains) triggers pushes on the tracked branch only. Before another branch can reach an environment, add it to `on.push.branches` in `.ankra/pipeline.yaml`, for example `branches: [main, develop, "release/*"]`, so its pushes run and publish.

**Changing a rule is never a deploy.** Neither is turning push to deploy on. Ankra notes the newest build the rule already matches, and the environment moves on the next matching push. To deploy right away, deploy a tag by hand.

**Deploying by hand still works.** A person can promote or roll back an environment to any tag with `ankra application deploy`, as before. The next matching push moves the environment on again.

***

## Set it up

### From the CLI

List the application's environments. The `FOLLOWS` column shows each environment's rule, `<branch> (tracked)` when it has none, or `manual` when pushes do not deploy to it:

```bash theme={null}
ankra application environments my-app
```

Give an environment a rule, remove it, or turn push to deploy on or off for that environment alone. `--branches` takes a comma-separated list, and the environment is named by its name or its id:

```bash theme={null}
ankra application environments set my-app production --branches main
ankra application environments set my-app development --branches '**,!main'
ankra application environments set my-app staging --branches 'release/*'
ankra application environments set my-app staging --clear
ankra application environments set my-app staging --enable
ankra application environments set my-app production --disable
```

`--clear` removes the rule, so the environment follows the tracked branch again. Without `--enable` or `--disable`, the environment keeps its current push to deploy setting.

Create a new environment that follows a branch from its first deploy:

```bash theme={null}
ankra application deploy my-app \
  --cluster my-cluster \
  --namespace my-app-dev \
  --environment development \
  --follow-branches develop
```

### In the portal

In the new Ankra portal (`/next` on your portal's address), each environment card on the application's **Overview** shows what it follows, such as **Follows pushes to main** or **Follows pushes to every branch except main**. To change a rule, pick the environment in the application's environment menu and open **Settings** → **Deploys**. The **Deploy on every push** card there holds that environment's **Branches it follows** editor, with presets for the common setups, a field for your own patterns and a **Save branches** button.

### From the API

Set a rule on one environment with `PUT /org/applications/{application_id}/auto-deploy`:

```json theme={null}
{
  "enabled": true,
  "environment_id": "<environment-id>",
  "branches": ["develop"]
}
```

* `enabled` is required, and it sets the environment's own push to deploy switch, so send its current value to change only the rule.
* `branches` needs `environment_id`.
* `"branches": []` removes the rule.
* Leaving `branches` out leaves the rule as it is.
* An invalid pattern returns `422` with a sentence that names the problem.

`GET /org/applications/{application_id}/auto-deploy` lists every environment with its `branches`. `null` means the environment follows the tracked branch, unless `branches_mixed` is `true`: then the environment's deployments do not all carry the same rule, and setting or removing its rule makes them agree.

`POST /org/applications/{application_id}/deploy` accepts `environment_name` and `follow_branches`, to create a named environment that follows those branches from the start.

Changing a rule needs permission to deploy applications. Reading it does not.

***

## Add an environment on another cluster

In the new Ankra portal, **Add** beside the environments on the application's **Overview** offers:

* **On a new cluster…** opens **Add a cluster**, set to copy every stack of the cluster the environment in view runs on and to deploy the application there as a new environment. It needs `clusters.create` and `applications.deploy`.
* **On a cluster you have…** opens the deploy form for a new environment. It needs `applications.deploy`.

On a new cluster, **Review** shows the copy under **Application to deploy**, with the new environment's name and branches:

* **Copied:** the source environment's image and deploy settings (replicas, resources, ports), and every stack of its cluster except the application's own, the backup stack and the provider-managed stacks. A stack that needs secrets the new cluster lacks stays a [draft](/guides/clone-cluster#stacks-that-need-your-input).
* **Not copied:** hostnames (the new environment gets its own address), data and backup policy. Databases start empty.
* **Secret overrides** come along with **Copy secret overrides**, which needs `applications.write` and starts on only when the new cluster's purpose matches the source environment's. Without it the environment uses the application's shared secrets.

The application deploys once the cluster is online and its copied stacks have deployed; after an hour Ankra stops waiting and says so on the **Overview**.

From the API, `POST /org/applications/{application_id}/environments/{environment_id}/clone` with `target_cluster_id` copies an environment onto a cluster you have: one the application does not run on gets a new environment, one it runs on is overwritten in place, the source's own is refused with `409`. `include_secrets: true` copies the overrides and needs `applications.write`; `environment_name` and `follow_branches` name the environment and its rule. A [cluster clone](/guides/clone-cluster#clone-a-whole-cluster) request takes the same copy as `application_environment` and checks it before creating anything.

***

## Adjust a pipeline to where a push is going

A pipeline can ask which environments the current push deploys to. [`ankra.environments`](/guides/pipeline-reference#where-a-push-deploys) is the sorted list, by name, of the environments with push to deploy on whose rule matches the run's branch, or that have no rule when the run's branch is the tracked branch:

```yaml theme={null}
stages:
  - name: smoke-production
    kind: run
    if: "'production' in ankra.environments"
    run: ./scripts/smoke.sh https://app.example.com
  - name: seed-demo-data
    kind: run
    if: "'development' in ankra.environments"
    run: ./scripts/seed.sh
```

Use `ankra.environments` for steps that depend on where the image is going. To change steps by branch, keep using `when.branches`.

***

## FAQ

**I pushed to `develop` and development did not move.**
Check the push's pipeline run. Development moves only when that run's `publish` stage succeeded and pushed a `sha-<7>` image. A failed or skipped `publish` records no build for `develop`, and neither does a pipeline whose `on.push.branches` leaves `develop` out, which is how the generated pipeline starts. Then check that push to deploy is on for development, and that its rule matches `develop`: `ankra application environments my-app` shows `manual` for an environment that pushes do not deploy to.

**An environment has no rule. What does it deploy?**
The newest build of the application's tracked branch, exactly as before branch rules existed.

**I changed a rule and nothing deployed.**
That is expected. Changing a rule is never a deploy. The next push that the rule matches deploys, or you can deploy a tag by hand.

**Does a pull request deploy to development if its branch matches?**
No. Pull requests never deploy to environments. They get a [PR preview](/guides/pr-preview-environments).

**Two branches match one rule. Which build wins?**
The published build whose push came last, of any matching branch, even if another build finished publishing after it.

***

## Related

> [card] [Ship your app](/guides/deliver-your-app)
>
> Register an application and turn on push to deploy.

> [card] [Pipeline reference](/guides/pipeline-reference#expressions)
>
> The expression context, including `ankra.environments`.


# Audit Log
Source: https://docs.ankra.ai/guides/audit-log

Review the append-only record of every administrative change in your organisation - who did what, when, and from where.

Every administrative change in Ankra is recorded in the organisation **Audit Log**. It is the platform's system of record for governance questions: who invited that member, who approved that deployment, who accepted that CVE as risk, and when.

***

## What is recorded

Each entry captures:

* **Who** - the actor (a member, or a token acting on their behalf)
* **What** - the action and the resource it touched, with structured details of the change
* **When** - the timestamp
* **Where from** - the source IP

Administrative changes across the platform write entries: invitations and role assignments, cluster-group edits, credential changes, cluster lifecycle operations, security disposition changes, and organisation settings edits.

Changes to a cluster agent's settings are recorded with the value they replaced: turning automatic agent upgrades on or off for a cluster (`set_agent_auto_upgrade`), the agent's memory and CPU (`set_agent_resources`) and its pipeline settings (`set_agent_ci_settings`) each record every setting they moved as `changes: {<setting>: {from, to}}`, and the person's reason when they gave one. Turning automatic agent upgrades on or off for the whole organisation is recorded on the `update_organisation` entry, with the earlier value under `previous`.

Kubernetes access is recorded too: cluster access grants and their changes, every kube token minted (including the one behind each generated kubeconfig), every [pod terminal](/platform/pod-terminal) session, whose entry links to a recording of the session, and every reveal of a Kubernetes Secret's values (action `reveal`, resource type `kubernetes_secret`, naming the cluster, namespace, Secret and key names, never the values). Other individual Kubernetes API calls are not in this log; your cluster's own audit policy records those.

Cluster access grants are recorded as `cluster_access_grant_created`, `cluster_access_grant_extended` and `cluster_access_grant_deleted`, and each grant entry records the `authority`: the permission the grant was made under, `kube_access.manage` or, for a [break-glass elevation](/guides/cluster-access#break-glass-elevation) by a caller that holds only the break-glass permission, `kube_access.elevate`. Every change to the [organisation access policy](/guides/cluster-access#organisation-access-policy) is recorded as `cluster_access_policy_updated`.

Entries are **append-only** - nobody in your organisation can edit or delete them, and only the [retention](#retention) job removes them - and they are written for every change regardless of who can view the log.

***

## Who can see it

Viewing the audit log requires the `audit.read` permission, held by **owners** and **admins** by default. It can also be granted to [custom roles](/guides/roles-and-access#permission-matrix), so a compliance or security function can review the log without broader administrative access.

***

## Reading and filtering

Open **Organisation → Audit log**. From there you can:

* **Search** entries by keyword
* **Filter** by user, action type, cluster, resource type, and date range
* **Expand** an entry to see the structured details of the change

Every entry names the **cluster** it belongs to, and the name links straight to that cluster's own Audit tab. Organisation-level events - sign-ins, invitations, role changes - show no cluster. A cluster you have since deleted keeps its name in the trail, marked deleted: the record outlives the cluster, which is exactly what makes the deletion itself auditable.

The cluster filter is carried in the page URL, so a view narrowed to one cluster can be bookmarked or shared as a link.

***

## Per-cluster view

Each cluster carries its own slice of the trail: the **Audit** tab in cluster **Settings** shows only the manual actions performed on that cluster - lifecycle operations, scaling, node restarts, and stack changes - with the same permission gate and entry format. See [Cluster Settings → Audit](/platform/cluster-settings#audit).

The two views are connected in both directions. From the organisation log, a row's cluster takes you into that cluster's tab; from the tab, **View in organisation audit log** takes you back to the full trail with that cluster preselected as the filter - the same entries, alongside the organisation-level events the tab leaves out.

***

## Standard changes

Entries for changes Ankra makes to a cluster also record which kind of change they were. A change that matches the [standard-change catalogue](/security/change-management#the-standard-change-catalogue) - an add-on upgrade that fixes a published security advisory, a Kubernetes patch upgrade, autoscaling within your limits, a scheduled power action, access expiry - is marked as a pre-approved standard change, with the catalogue entry and the reason it qualified. The cluster **Audit** tab shows it as **Pre-approved SC-01** (or the matching ID) beside the action; the full record is under `change_classification` in the entry's details.

Entries without that record are normal changes, or events that are not changes at all. See [Change Management](/security/change-management) for the catalogue and for how to require approval for every change instead.

***

## Exporting

Export the current filtered view to CSV or JSON from the portal.

The download honours the filters on screen, including the cluster filter, and the export rows carry the cluster alongside the actor and action. A cluster's **Audit** tab exports through the same path, so a per-cluster download and the organisation view filtered to that cluster contain the same entries.

A single export returns up to 100,000 rows and signals truncation when more rows match. See [Audit Export](/security/audit-export) for the full column list and how to get the trail into a SIEM.

***

## Retention

Audit entries are retained for **365 days**, after which older rows are removed by a background retention job. Entries inside the window are immutable.

If your framework requires a longer trail, [export](/security/audit-export) on a schedule into storage you control - the platform is not intended to be your long-term system of record.

***

## Relationship to Git history

Ankra gives you two complementary trails:

* The **audit log** records platform actions - who signed in, assigned a role, approved a plan, or changed a disposition.
* **Git history** records desired-state changes as attributed commits - exactly what changed in your cluster definitions and Stacks, and when it was deployed.

Together they answer both "who did what in the platform" and "what actually changed in the cluster". For how commits are produced and attributed, see [GitOps](/concepts/gitops).

***

## Related

> [card] [Roles & Access](/guides/roles-and-access)
>
> Grant the `audit.read` permission via custom roles.

> [card] [Change Management](/security/change-management)
>
> Pre-approved standard changes and how they are recorded.

> [card] [GitOps](/concepts/gitops)
>
> The attributed commit trail for desired-state changes.

> [card] [Security at Ankra](/security/overview)
>
> How the audit log fits the wider control set.

> [card] [Cluster Security](/guides/cluster-security)
>
> Disposition changes that land in the audit log.


# Use Avura domains with Ankra
Source: https://docs.ankra.ai/guides/avura-domains

Connect an Avura workspace to its Ankra organisation, choose which Avura domains Ankra may use, then publish cluster hostnames, manage records and root generated cluster domains on those domains.

If your domains live in Avura, Ankra can use them directly: clusters publish Ingress hostnames into them, you edit their records from the Ankra dashboard, and one of them can become the root every generated cluster domain nests under. You connect once from Avura and choose, domain by domain, which ones Ankra may touch.

> [!NOTE]
>
> This integration arrives with the Avura connection release of both products. If **Organisation** → **Settings** in Ankra has no **Avura** entry, or Avura's **Admin** → **General** page has no **Ankra Platform** card, it has not reached your organisation yet.

## Prerequisites

* **One login for both.** You sign in to Avura with **Continue with Ankra**, using the same account you use for Ankra. If you already have an Avura password account, link Ankra to it from **Settings** → **Security** → **Link Ankra account**. The Ankra email has to match your Avura email, and both have to be verified.
* **An Avura workspace linked to the Ankra organisation.** When an Ankra organisation owner or admin signs in to Avura with Ankra for the first time, Avura creates a workspace for each organisation they administer and links it. An existing workspace is linked by its Avura owner from **Admin** → **General** → **Ankra Platform organisation**, which lists the Ankra organisations you administer that are not linked anywhere else. One workspace links to one organisation.
* **Admin rights on both sides.** Connecting needs an Avura owner or admin who is also an admin of the linked Ankra organisation. Managing records, custom DNS zones and the root domain in Ankra needs an Ankra organisation admin; any member can view them.

## Connect from Avura

The connection is always made from Avura, never from Ankra.

**1. Open the Ankra Platform card**

In Avura, go to **Admin** → **General** → **Ankra Platform**. The card shows which Ankra organisation the workspace is linked to.

**2. Connect**

Click **Connect**. Avura creates a platform token for the workspace and hands it to the linked Ankra organisation, which checks it against Avura before saving it. If Ankra refuses, Avura discards the new token and shows why; a connection that was already working is left as it was.

**3. Check it from Ankra**

In Ankra, **Organisation** → **Settings** → **Avura** now shows the linked Avura organisation, the status **connected**, how many domains are shared and when the connection was last verified. **Open Avura** takes you back to Avura's admin page.

**Rotate connection** on the same Avura card replaces the platform token. Clusters already publishing through the connection keep working through a rotation.

## Choose which domains Ankra can use

Connecting shares nothing on its own. Every domain starts closed, and an Avura owner or admin opens each one:

* In Avura's **Domains** list, turn on the **Ankra Platform** switch for the domain, or open the domain and use the **Use with Ankra Platform** card on its **Overview** tab.
* Subdomains inherit the setting from the nearest parent that has it on, and show it as locked on.
* Turning a domain off cuts Ankra off on its very next request, including the tokens clusters are already using to publish records in it. Anything in Ankra that relies on that domain stops updating until you turn it back on.
* Moving a domain to another Avura organisation turns the setting off, so it never arrives already shared with that organisation's Ankra.

## What Ankra can and cannot do

The platform token Avura issues belongs to the workspace, not to a person. It holds no Avura role, so it keeps working when the admin who connected leaves, and it never appears in anyone's token list.

On the domains you opened, and their subdomains, Ankra can:

* list the domains and read their records
* create, edit and delete records, and ask Avura to re-sync a zone
* create subzones, and delete any subzone inside a shared domain (but never the shared domain itself)
* mint tokens pinned to a single shared domain, which is what a cluster's external-dns receives

Ankra cannot see any domain you did not open, delete a shared domain itself, add root domains, change a domain's sharing, or reach grants, mail, DNSSEC or Avura's own settings.

The platform token itself stays in Ankra's secret store and is never sent to a cluster. Clusters receive tokens pinned to one domain: a domain you serve from a single cluster gets a token for that cluster, and a domain declared for the whole organisation gets one token shared by every cluster that serves it. Revoking the connection revokes every token minted from it.

## Serve an Avura domain from your clusters

A shared Avura domain works as a [custom DNS zone](/concepts/applications#serving-a-zone-in-your-own-dns-account-from-every-cluster): Ankra runs an external-dns pinned to that zone on each cluster, and an Ingress on a hostname under it is published by the cluster that serves it. The certificate follows once the name resolves.

**1. Add the domain**

Go to **Organisation** → **Settings** → **DNS records** → **Custom domains** and click **Add domain**.

**2. Pick Avura**

Choose **Avura** as the provider. The domains Avura shares with Ankra appear as a list; pick one.

**3. Choose the scope**

**All clusters** serves the zone from every cluster in the organisation, including clusters created later. **One cluster** serves it from the cluster you pick.

The CLI does the same with the connection's credential, which is always named `avura`:

```bash theme={null}
ankra org custom-dns-zones add --zone example.dev --credential avura
ankra cluster custom-dns-zones add my-cluster --zone example.dev --credential avura
```

A zone that Avura does not share with Ankra is refused, and so is a zone that overlaps the organisation's Custom Ankra domain (use a domain either as a custom DNS zone or as the root below, not both). **Remove** on the zone card (or `ankra org custom-dns-zones remove --zone example.dev`) withdraws the zone and revokes the token its clusters used. The records already in the zone are yours and stay where they are.

## Manage records from Settings > Avura

**Organisation** → **Settings** → **Avura** lists the shared domains. Select one to see its records; admins can add, edit and delete them.

| Field | Rule |
| - | - |
| **Type** | A, AAAA, CAA, CNAME, MX, NS, SRV or TXT |
| **Name** and **Value** | Required |
| **TTL** | Blank for Avura's default, or a whole number of seconds from 60 to 604800 |

A record's name and type are fixed once it exists, so editing changes its value and TTL only. If Avura refuses a change (a conflicting record, or Avura being briefly unavailable), the dialog stays open with the reason so you can fix it or retry.

The changes are made in Avura, so Avura's own record list shows them straight away.

## Root generated cluster domains on an Avura domain

Every hostname Ankra generates, including each cluster's domain and the preview URLs built from it, nests under the organisation's [Custom Ankra domain](/platform/ai-workspaces#custom-ankra-domain), which is `ankra.cc` until you set one. A domain Avura shares with Ankra can be that root.

Go to **AI** → **Settings** → **Workspaces**. With Avura connected, the **Custom Ankra domain** field suggests the top-level domains your Avura workspace shares with Ankra; click one to fill it in, or type a domain yourself, then save. From the CLI:

```bash theme={null}
ankra org domain set example.dev
```

Ankra first asks your Avura organisation whether it shares the domain. When it does, Ankra provisions the organisation's zone and every cluster's zone in your Avura account, with your connection, and skips the nameserver check a root hosted by Ankra needs: Avura's own listing is the proof you hold the domain. The saved field then carries a **Hosted in your Avura** badge and says no nameserver change is needed. When Avura does not share the domain, it is treated as an ordinary custom Ankra domain and has to be delegated to Ankra's nameservers.

* Ankra adopts the domain as the zone apex and never creates or deletes it. It creates a subzone per cluster under it and deletes only those subzones when a cluster domain is removed.
* If Avura cannot be asked at that moment (it is unreachable, or the connection token was rejected), the change is refused and nothing is saved. Try again once the connection shows **connected**.
* Switching from one root to another follows the same checklist as any root change: cluster domains and DNS records under the old root have to be removed first. See [the preview URL](/concepts/applications#the-preview-url) for the procedure. Zones under the old root are torn down in the account that created them.

## Disconnect

You can disconnect from either side. In Avura, **Disconnect** on the **Ankra Platform** card asks Ankra to drop the connection and then revokes the platform token and every token minted from it. In Ankra, admins can use **Disconnect** on **Organisation** → **Settings** → **Avura**.

Ankra refuses to disconnect while something still depends on the connection:

* a custom DNS zone still uses the `avura` credential, or
* the Custom Ankra domain is an Avura domain from this connection.

While generated cluster domains are rooted on an Avura domain, **Disconnect** on **Settings** → **Avura** is disabled and says why; move the Custom Ankra domain off Avura to enable it. When a custom DNS zone is what blocks it, the refusal points you to the DNS records page. Remove what depends on the connection first, then disconnect again. The same rule refuses reconnecting the organisation to a *different* Avura organisation while either is true; rotating the token within the same Avura organisation is always allowed.

> [!WARNING]
>
> When Ankra refuses or cannot be reached, Avura keeps the connection working and offers **Revoke anyway**. That revokes every platform token in Avura immediately, whatever Ankra says. Clusters stop publishing to your Avura domains and generated cluster domains on an Avura root stop updating until you connect again. Use it when you need to cut Ankra off now, not as the normal way out.

Unlinking the workspace from its Ankra organisation also revokes the platform tokens first.

> [!NOTE]
>
> Deleting the `avura` credential on the **Credentials** page, with `ankra credentials delete` or through Ankra AI is the same as **Disconnect**: it runs the checks above and is refused with the same message while something still depends on the connection.

## Troubleshooting

**Avura says your Ankra session expired.** Avura connects and disconnects with the Ankra sign-in stored from your last **Continue with Ankra**, and that sign-in expires. Sign out of Avura, sign in again with **Continue with Ankra**, and retry.

**Avura refuses with a permission error, or the Ankra organisation is not offered.** You have to be an admin (or owner) of the linked Ankra organisation, and the membership has to be active. Ankra also refuses when your organisation requires multi-factor authentication and your account has not enrolled. Check the organisation on the **Ankra Platform organisation** card is the one you administer; linking an existing workspace lists only organisations where you are owner or admin and that are not linked to another workspace.

**Link Ankra account fails.** The Ankra email and the Avura email must be the same address, and both must be verified. If signing in with Ankra sends you back with "an account already exists", sign in with your Avura password and link Ankra from **Settings** → **Security**.

**Settings > Avura shows token rejected.** The platform token was revoked in Avura, or the workspace was unlinked. Connect again from Avura's **Ankra Platform** card.

**Settings > Avura shows unavailable, or the shared domain count is Unknown.** Ankra could not reach Avura. Nothing is changed while it is unreachable: record changes and root domain changes are refused rather than half applied. When a record change reports that Avura's DNS server is unavailable, Ankra has already asked for a zone re-sync; refresh the page before retrying.

**Avura says the Ankra Platform is unavailable.** Avura could not reach Ankra within its time limit. The previous connection state is kept, so retry later.

**A domain is missing from the Avura list in Ankra.** Only domains with **Use with Ankra Platform** turned on are shared. Turn it on in Avura and refresh.


# AWS Clusters
Source: https://docs.ankra.ai/guides/aws-clusters

Create a self-managed kubeadm or k3s cluster on EC2 instances in your AWS account, in a VPC Ankra creates or one you already own, with Ankra installing and operating Kubernetes.

Choose self-managed EC2 over [Amazon EKS](/guides/eks-clusters) when you want the control plane on instances you own, with no EKS control-plane fee, or when the cluster has to join a VPC you already run. Ankra creates the network (or adopts yours), a bastion, the control plane and worker instances, installs Kubernetes with the AWS cloud controller manager and EBS CSI driver, and then operates the cluster - this is an **Ankra Managed** cluster. The [comparison table](/guides/managed-kubernetes#cloud-managed-or-ankra-managed) sets the two side by side.

## Before you start

* An **AWS credential** whose role carries the **Provisioning** scope (the one write role for EKS and self-managed clusters) or the EC2-only **Self-managed** scope; access keys with the equivalent policy also work. A provisioning stack launched before the self-managed statements were added must be updated. See [AWS Credentials](/platform/credentials/aws#provisioning).
* An **SSH key credential** - your own public key, or one Ankra generates. See [SSH Key Credentials](/platform/credentials/ssh-key).
* A decision on the **network**. Nothing needs to exist in the account beforehand unless you adopt a VPC.

### Created or adopted VPC

* **Created VPC** (the default; leave out `vpc_id`). Ankra creates a VPC from `network_ip_range` (default `10.0.0.0/16`, any `/16` to `/20`) with, per availability zone, a private `/20` for the nodes and a public `/24` for the bastion and NAT gateway, an internet gateway and route tables. It uses one zone when the control plane has fewer than three nodes and three zones otherwise, or the `availability_zones` you name; more than one zone needs at least three control planes, so etcd keeps quorum when a zone is lost. Teardown removes all of it.
* **Adopted VPC** (`vpc_id`). Ankra builds inside a VPC you already run: private `node_subnet_ids` for the control plane and workers (spread them across zones for a multi-AZ cluster) and a public `bastion_subnet_id`. Ankra never creates, modifies or deletes your VPC, subnets, internet gateway, NAT gateways, DHCP options or existing route tables. `network_ip_range`, `availability_zones` and `nat_gateway_single_zone` are refused alongside `vpc_id`, and the subnet fields without it.

Nodes never get a public IP, so they need an egress path (`egress_mode`):

| Mode | Where | What it is | Cost |
| - | - | - | - |
| `nat_gateway` | Created VPC (the default there) | An Ankra-created NAT gateway per zone, so egress survives a zone outage; `nat_gateway_single_zone: true` shares one | About USD 32 a month per gateway plus per-GB processing ([VPC pricing](https://aws.amazon.com/vpc/pricing/)) |
| `bastion_nat` | Either | The bastion forwards node traffic. Egress is capped by the bastion's network performance, and stops while it restarts or resizes | The bastion and its Elastic IP only |
| `existing` | Adopted VPC | Your NAT gateway, NAT instance or transit path already on the node subnets' route table; Ankra changes nothing | What you already pay |

For an adopted VPC, preflight picks the mode when you leave it out: subnets that already have egress get `existing`, empty subnets without it get `bastion_nat`. `bastion_nat` is always refused when a node subnet holds an instance Ankra did not create, because re-pointing that subnet's default route would take over its egress; create a NAT gateway and use `existing` instead. [Egress modes](/reference/aws#egress-modes) has the full rules.

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **AWS** under **Ankra Managed** (the **AWS** card under **Cloud Managed** creates [EKS](/guides/eks-clusters)).
>
> **2. Basics**
>
> Name the cluster and pick the AWS credential, the SSH key and the region. A read-only (cost) credential, or a provisioning role whose stack predates the self-managed statements, is listed but refused at preflight with the missing permission named.
>
> **3. Network**
>
> Keep **Create a new VPC (recommended)** - optionally with your own network range and availability zones - or switch to **Use an existing VPC** and pick the VPC, the node subnets and a public bastion subnet; the wizard shows each subnet's zone and route. Choose the egress. **Bastion allowed IPs** starts as `0.0.0.0/0`: SSH is key-only, password login is off and sshd is rate-limited on the host, but replace it with your own CIDRs to close the port to everyone else. Ankra's own addresses stay admitted.
>
> **4. Compute**
>
> Pick the control plane count (1, 3 or 5) and instance type, one or more worker node groups, the bastion instance type (a burstable type such as `t3.small` is enough, unless it is the NAT), the root volume size (an encrypted gp3 volume, 40 GiB by default), the Ubuntu series (24.04 by default) and what happens to EBS volumes on teardown. Instance types load live with prices; only `amd64` types are offered.
>
> **5. Kubernetes**
>
> Keep **kubeadm** (the default, Cilium only) or pick **k3s**, the version, and the etcd topology or CNI. The CNI defaults to Cilium; a k3s cluster can pick Calico or flannel, but only Cilium and Calico enforce the [IMDS guard](/reference/aws#imds-guard), so flannel gets a preflight warning. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time).
>
> **6. GitOps**
>
> Optionally connect a Git repository. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind a Network Load Balancer the AWS cloud controller creates.
> * **Include DNS Integration** - a delegated subdomain on `ankra.cc` with external-dns wired, so Ingress hostnames publish their DNS records automatically.
>
> **7. Review**
>
> Click **Run preflight**. It reports the network ownership, the zones it resolved, the egress mode, the AMI, and the vCPU, VPC, NAT gateway, Elastic IP and security-group quotas. Once nothing is an error, click **Create cluster** and follow the progress view.

> [tab] CLI
>
> ```bash theme={null}
> # Provisioning role: print the external ID and CloudFormation link, launch the stack, then store the role
> ankra credentials aws onboarding --scope provisioning      # or --scope self_managed for the EC2-only role
> ankra credentials aws create-role --name my-aws --role-arn <role-arn> --external-id <external-id> \
>   --region eu-north-1 --scope provisioning
> # Or access keys (the secret is asked for on a masked prompt)
> ankra credentials aws create-keys --name my-aws-keys --access-key-id <access-key-id> --region eu-north-1
>
> ankra credentials hetzner ssh-key create --name my-ssh-key --generate   # any SSH key credential works
> ```
>
> The external ID must be the one `onboarding` printed and the stack was launched with; a role stored at the `cost` scope is refused at create. Look up what the credential can reach with `ankra cluster aws regions`, `availability-zones`, `instance-types`, `images` and `pricing` (all take `--credential-id` and `--region`), and `vpcs` and `subnets --vpc-id <vpc-id>` when you adopt a VPC.
>
> `preflight` takes the same flags as `create` and creates nothing. A three-zone cluster in a created VPC:
>
> ```bash theme={null}
> ankra cluster aws preflight \
>   --name my-cluster \
>   --credential-id <aws-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --region eu-north-1 \
>   --bastion-allowed-ips 203.0.113.10/32 \
>   --control-plane-count 3 \
>   --control-plane-type t3.medium \
>   --worker-count 3 \
>   --worker-type t3.large
> # When it reports no errors, run the same command with create instead of preflight
> ```
>
> `--network-ip-range`, `--availability-zones`, `--egress-mode nat_gateway|bastion_nat` and `--nat-gateway-single-zone` shape a created network. To adopt a VPC instead:
>
> ```bash theme={null}
> ankra cluster aws create \
>   --name my-cluster \
>   --credential-id <aws-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --region eu-north-1 \
>   --vpc-id <vpc-id> \
>   --node-subnet-ids <subnet-a>,<subnet-b>,<subnet-c> \
>   --bastion-subnet-id <public-subnet> \
>   --egress-mode existing \
>   --bastion-allowed-ips 203.0.113.10/32 \
>   --control-plane-count 3 \
>   --worker-count 3
> ```
>
> `--distribution k3s`, `--cni`, `--cni-features`, `--retention-policy retain|delete`, `--environment`, `--criticality` and the `--gitops-*` flags cover the other choices. Every flag is in the [CLI reference](/reference/cli/cluster).

> [tab] API
>
> Preflight takes the same body as create and answers with findings - `can_proceed`, `network_ownership`, `resolved_availability_zones` and `resolved_egress_mode` - instead of a cluster:
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/aws/preflight \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<aws-credential-id>",
>     "ssh_key_credential_id": "<ssh-key-credential-id>",
>     "region": "eu-north-1",
>     "availability_zones": ["eu-north-1a", "eu-north-1b", "eu-north-1c"],
>     "egress_mode": "nat_gateway",
>     "bastion_allowed_ips": ["203.0.113.10/32"],
>     "control_plane_count": 3,
>     "control_plane_type": "t3.medium",
>     "node_groups": [
>       {"name": "default", "instance_type": "t3.large", "count": 3}
>     ],
>     "retention_policy": "retain"
>   }'
> ```
>
> Send the same body to `POST /api/v1/clusters/aws` to create the cluster. It answers `cluster_id`, `kind: "aws"`, `state: "creating"` and an `operation_id` that tracks provisioning. To adopt a VPC, replace the network fields with `"vpc_id"`, `"node_subnet_ids"`, `"bastion_subnet_id"` and `"egress_mode": "existing"` or `"bastion_nat"`; the created-network fields are then refused with `422`. Every field and default is in the [AWS Reference](/reference/aws). Ankra's AI can create the cluster in chat too, running the preflight for you.

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created in your account

* **The network**, in a created VPC: the VPC, subnets, internet gateway, route tables and, in `nat_gateway` mode, NAT gateways with their Elastic IPs. In an adopted VPC, at most one route table (`bastion_nat` mode).
* **Two security groups** (nodes and bastion), an imported **key pair**, one **Elastic IP** for the bastion, and the **bastion**, control plane and worker instances with encrypted gp3 root volumes and no public IPs on the nodes.
* **Two IAM roles with instance profiles**, `ankra-k3s-<cluster>-cp` and `ankra-k3s-<cluster>-node`, that the cloud controller manager and EBS CSI driver use. The credential you gave Ankra is never copied into the cluster.
* **The AWS cloud-provider stack**: the cloud controller manager (load balancers for `LoadBalancer` Services), the EBS CSI driver (encrypted gp3 volumes by default) and the IMDS guard.

Everything carries `ankra.cloud/cluster-id=<id>`, `ankra.cloud/managed=true` and `kubernetes.io/cluster/<id>=owned`, and the credential's write permissions are scoped to those tags. [What Ankra creates](/reference/aws#what-ankra-creates) has the full list and the network diagram.

## AWS specifics

* **Node groups follow the node subnets.** New nodes are balanced across the cluster's zones - each takes the zone with the fewest instances - unless the group is pinned with `--availability-zone` (API `availability_zone`). Pin a group that runs zonal storage: an EBS volume cannot attach from another zone. Every node carries `topology.kubernetes.io/zone` and `topology.kubernetes.io/region`, so `topologySpreadConstraints` work as they are.
* **An instance type change replaces nodes.** EC2 cannot resize a running instance, so each node of the group is drained, terminated and recreated on the new type, one at a time.
* **Control plane.** A cluster whose nodes span more than one zone needs three control planes and cannot go below three. `ankra cluster aws control-plane get|set-count|set-instance-type` manage it.
* **Restart** is an EC2 reboot; if the instance does not respond it falls back to a stop and start, which keeps the private IP. `ankra cluster aws nodes cloud-init-log` reads a node's cloud-init status over the bastion. OS-level diagnosis and repair over SSH run through Ankra's AI (`ssh_diagnose_node`, `ssh_repair_node`).
* **Bastion.** Resize it from **Nodes → Bastion & VMs** or with `PUT /api/v1/clusters/aws/{cluster_id}/bastion/instance-type`; there is no CLI verb on AWS. The instance is stopped, changed and started, keeping its Elastic IP. SSH as `ubuntu` through it (`ankra cluster aws access-info`); only `bastion_allowed_ips` and Ankra's addresses reach it.
* **Upgrades** move the AWS cloud controller manager with the nodes: its minor version is pinned to the cluster's Kubernetes minor.

> [!WARNING]
>
> In `bastion_nat` mode the bastion is every node's default route, so a bastion resize or restart stops image pulls, the Ankra Agent connection and the cloud controller's AWS calls until it is back.

### Stopping and starting

A stop stops every node and the bastion rather than terminating them, so the instances keep their root volumes and private IPs, and the bastion keeps its Elastic IP. Start brings the same instances back and etcd rejoins on the same addresses, so the cluster returns with its state, not as a rebuild. Ankra records each instance's private IP at create and checks it after every start; a difference is reported as drift. While stopped, compute is not billed, but EBS storage, the Elastic IP, load balancers and - in a created VPC - the NAT gateways are, so a cluster parked for weeks on `nat_gateway` egress is cheaper to terminate. A stop never deletes the volumes the CSI driver provisioned, whatever the `retention_policy`.

### Terminating

A terminate terminates the instances, releases the bastion's Elastic IP, and deletes the security groups, key pair and IAM roles. In a created VPC it then removes the network in reverse order - NAT gateways with their Elastic IPs, route tables, subnets, internet gateway, VPC - by the tags Ankra set. In an adopted VPC it restores each node subnet's previous route table association before deleting the one route table it created, and leaves the rest of your network alone.

EBS volumes the CSI driver provisioned, and load balancers the cloud controller created, follow the cluster's `retention_policy`, chosen at create:

* **`retain`** (the default) keeps them in your account, where they keep billing. The teardown result lists their IDs, and they carry the cluster ID tag. `--force` still deletes the load balancers, never the volumes, and no volume question is asked.
* **`delete`** removes those tagged `ankra.cloud/managed=true` for this cluster - the EBS volumes only once you accept it.

With a created VPC, load balancers are always deleted, because they cannot outlive the VPC; volumes still follow the policy.

```bash theme={null}
ankra cluster aws deprovision <cluster>                            # names the EBS volumes a delete cluster loses, and asks
ankra cluster aws deprovision <cluster> --accept-volume-data-loss  # for scripts
```

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `aws`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Preflight refuses the credential | It is read-only (cost scope), or its provisioning stack predates the self-managed statements. Add a [provisioning credential](/platform/credentials/aws#provisioning) or update the stack to the published template |
| The preflight `cidr` item is an error | `network_ip_range` does not hold a private `/20` and a public `/24` per zone - a `/20` VPC fits one zone. Widen the range (up to `/16`) or use fewer zones |
| Preflight refuses the zones | A named zone does not exist or is not available, or several zones were given with fewer than three control planes. Check `ankra cluster aws availability-zones` |
| Preflight reports the VPC or NAT gateway quota | The account is at its VPCs-per-region (`L-F678F1CE`) or NAT-gateways-per-zone (`L-FE5A380F`) limit. Request an increase, remove unused clusters, or use `bastion_nat` or `nat_gateway_single_zone` |
| Preflight refuses `bastion_nat` (adopted VPC) | A node subnet holds an instance Ankra did not create. Pick an empty subnet, or create a NAT gateway and use `existing` |
| Preflight refuses `existing` (adopted VPC) | The node subnets have no `0.0.0.0/0` route to a NAT gateway, NAT instance or transit path. Add one, or use empty subnets with `bastion_nat` |
| `node_subnet_ids` or `network_ip_range` refused with `422` | Subnet fields belong to an adopted VPC and network fields to a created one - send `vpc_id` with subnets, or neither |
| `bastion_allowed_ips` refused | An entry is not an IPv4 CIDR. `0.0.0.0/0` and `::/0` are accepted, and an empty list means `0.0.0.0/0` |
| Cluster stuck in provisioning | Check the vCPU quota for the instance family, the Elastic IP and NAT gateway quotas, and - in an adopted VPC - that the bastion subnet routes to the internet gateway |
| Nodes stay `NotReady` with the `node.cloudprovider.kubernetes.io/uninitialized` taint | The cloud controller cannot match the node to its instance - see below |
| `LoadBalancer` Service stuck in `Pending` | Check the cloud controller pods in `kube-system`. On a fresh account the first load balancer also creates the Elastic Load Balancing service-linked role, which the credential allows |
| PVC stuck in `Pending` | Check the EBS CSI controller pods; a pod pinned to a zone with no volume there needs a node group in that zone |
| Cannot SSH to the bastion | Your address is not in `bastion_allowed_ips`, or the security group was edited outside Ankra |
| Nodes lost egress after a bastion resize | Expected in `bastion_nat` mode while the bastion restarts |
| Create result reports `imds_guard: unavailable` | The cluster runs flannel, which cannot enforce the IMDS guard - see below |

**Cloud controller cluster ID and node names.** The cloud controller finds a cluster's instances by the `kubernetes.io/cluster/<id>=owned` tag and matches each node to an instance by name. Ankra sets both: the tag on every instance, and each node name to the instance's EC2 private DNS name as `DescribeInstances` reports it (k3s gets `--node-name`), so a VPC whose DHCP options set carries a custom `domain-name` does not break the match, and changing the DHCP options later affects no node. Removing or editing the tag in the console makes the controller treat the instance as foreign until the tag is back. If a node was renamed or re-registered by hand, delete its Kubernetes node object and restart the node from **Nodes**; it registers again under the right name.

**Instance metadata (IMDS).** Every instance requires IMDSv2, so tools that use IMDSv1 fail on the nodes. Workers and the bastion have a hop limit of 1, so pods cannot reach the instance role. Control planes have a hop limit of 3 so the EBS CSI controller can use the control-plane role; the IMDS guard, a network policy rendered for Cilium and Calico, blocks every other pod from `169.254.169.254`. On flannel there is no policy engine, so a pod scheduled onto a control plane can read that role's credentials: prefer Cilium or Calico, or keep the control planes tainted. Give a workload that needs AWS access its own credentials; do not raise the hop limits or re-enable IMDSv1 - Ankra restores the hardening on reconciliation.

**AWS service quotas.** Preflight checks the quotas that most often block a create, but a quota can be used up between preflight and create, and the per-cluster quota report answers `404` for AWS. If provisioning fails with a quota error, check the [Service Quotas console](https://console.aws.amazon.com/servicequotas/) for the region - On-Demand vCPUs for the instance family, VPCs per region, NAT gateways per zone, Elastic IPs (one for the bastion plus one per NAT gateway), security groups per interface and rules per group, and Network Load Balancers - then create again. A failed create leaves only tagged objects, which Ankra removes on the next attempt.


# Backups and Restore Points
Source: https://docs.ankra.ai/guides/backups

Register an S3-compatible bucket as a backup vault, protect a stack on a schedule, take and inspect restore points, restore a stack in place, and follow the runs that move the data.

> [!NOTE]
>
> A **backup vault** is an object-storage bucket your organisation owns that Ankra writes cluster backups to, and a **restore point** is one immutable copy of a stack's data inside it. Register a vault once, protect a stack, and every backup, restore and clone is a verb over the restore points that land there.

## Why a vault first

Ankra's answer to "copy this database to another cluster" is the industry one: take a backup, then restore it on the target. That keeps data off the platform entirely - the source cluster writes to the bucket, the target reads from it over HTTPS - and it means a disaster-recovery copy exists as a side effect of every clone.

That only works with somewhere to write to, which is what a vault is. Registering one is a one-time, organisation-level step.

> [!NOTE]
>
> **Pipelines are the exception, and they do not wait for this.** A pipeline step's log, a `scan` stage's reports and every declared artifact are kept in an Ankra-managed default vault for an organisation that has no ready vault of its own, under a key prefix of that organisation, so a first [Ankra Pipelines](/guides/ankra-pipelines#before-your-first-run) run works before anybody registers a bucket. Backups, restore points, cloning a stack with its data and `ankra migrate` data never use it - those are organisation-scoped and are what a vault of your own is for. Register one and it takes precedence for pipeline artifacts too, from the next step onward; objects already written stay where they are.

## What a vault records

| Field | What it is |
| - | - |
| Name | How the vault is referred to in policies and the CLI |
| Provider | The object-storage service, or `other` for any S3-compatible endpoint |
| Endpoint | The S3 endpoint URL |
| Bucket | The bucket backups are written to |
| Region | Only needed when the endpoint does not imply it |
| Path style | `https://endpoint/bucket` addressing - required by most self-hosted S3 services |
| Status | `ready`, `error` (with the failure excerpt), or `provisioning` while Ankra is still creating the bucket or checking the keys |
| Kind | `ankra_provisioned` when Ankra created the bucket from one of your provider credentials, `customer_s3` when you registered a bucket you already had |

The access key ID and secret you provide are written to Ankra's secret store and never returned by the API, the dashboard, or the CLI. Rotating keys means creating a new vault or re-verifying after updating the bucket policy.

## Let Ankra create the bucket

The quickest path: pick one of your organisation's provider credentials and a region, and Ankra creates the bucket, mints or stores the access keys, verifies the bucket and registers the vault. The vault shows **Provisioning** until that has finished, then **Ready** - or **Failed** with the excerpt of what the provider refused.

| Credential | What Ankra does with it | What you still supply |
| - | - | - |
| UpCloud | Creates a Managed Object Storage service in the region, a user with the `ECSS3FullAccess` policy and an access key, then the bucket | Nothing - the region is checked against your account's list |
| DigitalOcean | Mints a Spaces access key with the API token and creates the Space | Nothing |
| Scaleway | Uses the credential's own IAM key pair (Scaleway API keys are S3 keys) and creates the bucket in the credential's project | Nothing |
| Hetzner | Creates the bucket at the chosen location with the Object Storage key pair you provide | The key pair: Hetzner issues it in the Cloud Console (**Object Storage > Manage credentials**), and its Cloud API cannot mint one - so neither can Ankra |

Other credential kinds (OVH, AWS, GCP, Azure, Proxmox, Morpheus) cannot provision a bucket yet - register a bucket you own instead, below.

> [tab] Dashboard
>
> **1. Open Backups**
>
> Go to your organisation's **Settings** and choose **Backups**, then **Add vault** and **Let Ankra create the bucket**.
>
> **2. Press the button**
>
> The dialog opens ready: a credential Ankra can complete on its own is already selected, the vault is named for you, and the region is that provider's usual one. It says what it is about to do - "Ankra will create a bucket in europe-1 on UpCloud Object Storage and register it as 'backups'." - so pressing **Create bucket and vault** is the whole flow.
>
> **3. Hetzner: paste the Object Storage keys**
>
> A Hetzner credential is the one that cannot be a single click, and the picker labels it **(needs keys)**: the form asks for the access key and secret key from the Cloud Console. They are stored in Ankra's secret store and never shown again.
>
> **4. Only if you want to change something**
>
> **Advanced** opens the name, region and bucket for editing. Everything there already has a value; you never have to touch it.
>
> **5. Watch it come up**
>
> The row shows **Provisioning** with "Creating the bucket on ..."; the page refreshes on its own until it reads **Ready**. A **Failed** vault shows what the provider answered - a region your account cannot use, a bucket name someone else holds, a token without the right scope - and can be deleted and re-added once that is fixed.

> [tab] CLI
>
> ```bash theme={null}
> ankra backup vaults provision
> ```
>
> That is the whole command. The vault is named `backups` (then `backups-2` and so on), the credential is the only one Ankra can provision from, and the region is that provider's usual one - and the command prints all three before it creates anything. If the organisation has several usable credentials it asks which, naming them.
>
> Every default is an override, not a prerequisite:
>
> ```bash theme={null}
> ankra backup vaults provision offsite --credential upcloud-main --region europe-1 --bucket my-backups --wait
> ```
>
> `--credential` takes a credential name or id. `--wait` blocks until the vault is `ready` (or exits non-zero with the failure excerpt); without it the command returns as soon as the platform has accepted the request, and `ankra backup vaults get offsite` shows progress.
>
> For a Hetzner credential the command prompts for the Object Storage access key and (hidden) secret key when they are not passed with `--access-key-id` / `--secret-access-key`.

> [!NOTE]
>
> Ankra records the provider-side handle it created (the UpCloud service, the DigitalOcean key) on the vault, so it can clean them up later if you ask it to - see [Deleting a vault](#deleting-a-vault).

## Bring your own bucket

> [tab] Dashboard
>
> **1. Open Backups**
>
> Go to your organisation's **Settings** and choose **Backups**.
>
> **2. Add a vault**
>
> Click **Add vault** and pick the provider first: the dialog fills in the endpoint and region shapes that provider uses, sets **Path-style addressing** to what it expects (off for Amazon S3, on everywhere else), and says where its access keys are issued. Then enter the endpoint, bucket, region (if needed) and the keys.
>
> **3. Watch the verification**
>
> Ankra immediately checks the credentials against the bucket. A vault that passes shows **Ready**; one that does not shows **Failed** with the excerpt of what the bucket answered and a **Verify again** action - see [When verification fails](#when-verification-fails).

> [tab] CLI
>
> ```bash theme={null}
> ankra backup vaults create production-backups \
>   --provider upcloud \
>   --endpoint https://fi-hel2.upcloudobjects.com \
>   --bucket ankra-prod-backups \
>   --region fi-hel2
> ```
>
> The access key ID and secret are prompted for when not passed as flags - the secret hidden - so they stay out of your shell history. Prefer the prompt over `--access-key-id` / `--secret-access-key`.
>
> A vault that fails its first verification exits non-zero with the failure excerpt instead of a green create.

## Provider notes

| Provider | Endpoint shape | Notes |
| - | - | - |
| UpCloud Object Storage | `https://<region>.upcloudobjects.com` | Region is the endpoint prefix, for example `fi-hel2`. Note that *provisioning* takes a Managed Object Storage region instead - `europe-1`, `us-1` - which Ankra checks against your account |
| DigitalOcean Spaces | `https://<region>.digitaloceanspaces.com` | Spaces keys are separate from API tokens |
| Scaleway Object Storage | `https://s3.<region>.scw.cloud` | Uses the same key pair as the API |
| Hetzner Object Storage | `https://<region>.your-objectstorage.com` | Keys are issued in the console, not the cloud API |
| Amazon S3 | `https://s3.<region>.amazonaws.com` | Turn **path style** off |
| Other | Anything S3-compatible | MinIO, Garage, Ceph RGW; keep path style on |

## When provisioning fails or stalls

A vault Ankra provisions shows **Provisioning** until the bucket exists and its keys verify. Two things can go wrong, and both are recoverable the same way.

**It reads Failed with an excerpt.** The excerpt is what the provider answered - a region your account cannot use, a bucket name someone else holds, a token without the right scope. There is nothing to re-verify: the run never minted keys, so **Verify** is not offered and the API refuses it. Delete the vault - tick **Also destroy the bucket Ankra created**, or pass `--destroy-provider-resources`, so anything the run got as far as creating goes with it - and provision again with the excerpt's cause fixed.

**It stays on Provisioning.** Nothing retries a provisioning run, so a row that has not moved for quarter of an hour is stuck rather than slow, and the dashboard says so. Delete it the same way and try again.

## When verification fails

A **Failed** vault is still registered - nothing has to be redone from scratch - but the keys you gave it are never read back, so they cannot be edited in place. The recovery depends on what the excerpt says:

| Excerpt | Cause | Fix |
| - | - | - |
| `403 Forbidden` / `AccessDenied` | The key is valid but cannot reach this bucket | Fix the bucket policy or the key's permissions, then **Verify again** (`ankra backup vaults verify <name>`) |
| `InvalidAccessKeyId` / `SignatureDoesNotMatch` | The key pair is wrong | Delete the vault and add it again with the corrected keys |
| `NoSuchBucket` | The bucket name or region is wrong | Delete and re-add with the right bucket; on providers whose region is part of the endpoint, check the endpoint too |
| Connection or DNS errors | The endpoint is wrong or unreachable from Ankra | Check the endpoint URL (it must start with `https://`) and re-add, or fix the network path and **Verify again** |

**Verify again** re-runs the same check the create ran; the row updates in place with the new status and the time it last verified.

## Manage vaults

```bash theme={null}
ankra backup vaults list                       # every vault with status and last verification
ankra backup vaults get production-backups     # details, including a failure excerpt
ankra backup vaults verify production-backups  # re-run the credential check
ankra backup vaults delete production-backups  # confirms first; --yes to skip
```

`get`, `verify` and `delete` accept a vault name or id, and `list` / `get` support `-o json|yaml`. `verify` on a vault that is still provisioning answers that it is still being provisioned rather than recording a failed check.

## Deleting a vault

Deleting a vault removes Ankra's record of it and the access keys it stored. **By default the bucket is left exactly as it is** - with every restore point in it - along with anything Ankra created for it, so a deletion can never lose data on its own.

> [!WARNING]
>
> Nothing stops you deleting a vault that is still in use: Ankra does not yet refuse a delete on the grounds that something references the vault. Check before deleting one.

One exception, and it is deliberate: deleting a vault that is **still provisioning** always tears down the provider side, whether or not you ask for it. Such a vault has no restore points to lose, but the run may already have created a bucket or a provider resource - and once the record is gone nothing else can find them.

For a vault **Ankra provisioned**, you can ask for the cloud side to be cleaned up in the same step. Ankra then empties and deletes the bucket and removes what it minted for the vault - the UpCloud Managed Object Storage service, the DigitalOcean Spaces key. Scaleway and Hetzner vaults use your own credential's keys, which are never touched.

> [!WARNING]
>
> **This destroys data.** Every restore point in the bucket is gone, and nothing restores from that vault afterwards. Ankra refuses it for a bucket you registered yourself: that one is yours, and only you should delete it.

> [tab] Dashboard
>
> In the delete dialog, tick **Also destroy the bucket Ankra created**. The box is unchecked every time the dialog opens, names the bucket and its provider, and the confirm button becomes **Delete and destroy bucket**. A bring-your-own vault shows no such box.

> [tab] CLI
>
> ```bash theme={null}
> # Forget the vault; the bucket stays in your cloud account
> ankra backup vaults delete offsite
>
> # Forget the vault and destroy the bucket Ankra created for it
> ankra backup vaults delete offsite --destroy-provider-resources
> ```
>
> The confirmation prompt names the bucket before anything is destroyed. `--yes` skips it, so use that only in scripts that already know what they are deleting.

The teardown runs as a background job: the vault disappears from the list immediately and the bucket is removed shortly after. Each of its steps is written to be repeatable - a bucket already gone, a service already deleted and keys already removed all count as done - but nothing retries it automatically today. If the teardown fails, the provider resources stay and have to be removed in the provider console.

## Protect a stack

A vault is where restore points land; a stack's backup policy is what puts them there. Protection is a property of the stack, not a separate object: it is stored as the stack's own `backup` block, and the platform converges on it by installing the [backup data plane](/concepts/backup-vaults#the-backup-data-plane) on the cluster.

Look at what a backup would have to carry first:

```bash theme={null}
ankra cluster stacks data list shop
```

That lists the stack's data assets - standalone persistent volume claims, and the databases an operator runs - under the names the selection uses.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster stacks protect shop \
>   --vault production-backups \
>   --schedule daily \
>   --retention daily=7,weekly=4,monthly=6 \
>   --include-pvc shop/data \
>   --backup-now --wait
> ```
>
> The command prints the policy it stored and then `Backup stack: installing` until the data plane is actually on the cluster, so nothing is called protected while the Velero that would do the protecting is still arriving. A capture started before then waits rather than failing.
>
> A policy that cannot work is refused with every field-level reason at once, so a bad schedule and a bad retention are fixed in one edit:
>
> ```
> The backup policy is not valid.
>   - backup.schedule: 'evry day' is neither a five-field cron expression nor one of hourly, daily, weekly.
> ```

> [tab] Cluster file
>
> The same policy in your cluster file, applied with `ankra cluster apply -f cluster.yaml`:
>
> ```yaml theme={null}
> stacks:
>   - name: shop
>     backup:
>       enabled: true
>       vault: production-backups
>       schedule: daily
>       retention:
>         hourly: 0
>         daily: 7
>         weekly: 4
>         monthly: 6
>         yearly: 0
>         minimum_count: 3
>         minimum_age: 24h
>       selection:
>         databases: true
>         persistent_volume_claims:
>           - shop/data
>         confirm_exclude_databases: false
> ```
>
> Every field, with its default, is in the [`backup` block reference](/reference/importcluster#spec-stacks-backup).

What `protect` takes:

| Flag | Meaning |
| - | - |
| `--vault` | **Required.** The vault restore points are written to, by name or id. A protected stack with nowhere to write to is not protected |
| `--schedule` | `hourly`, `daily`, `weekly`, or a five-field cron expression. Default `daily` |
| `--retention` | `key=value` pairs from `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `minimum-count`, `minimum-age` |
| `--include-pvc` | Repeatable, `namespace/name`. Volumes are captured only where named |
| `--exclude-databases` | Leave the stack's databases out. Needs `--confirm-exclude-databases` beside it |
| `--backup-now` | Take the first restore point immediately instead of waiting for the schedule |
| `--wait` | Follow the first capture's run until the restore point is sealed |

Ankra takes the scheduled restore points itself, on the schedule the block names, through the same capture as **Back up now** - so every scheduled backup is a restore point you can list, restore and let retention expire. Nothing is scheduled inside the cluster for any engine: no Velero `Schedule`, no CloudNativePG `ScheduledBackup`, no schedule entry inside a Percona cluster. A Percona cluster is captured into the backup storage its own spec already declares.

For a CloudNativePG cluster, protecting the stack writes two things into it, because CloudNativePG writes a backup wherever the `Cluster` itself says: the barman-cloud archiver goes into the member that declares the `Cluster` (the manifest body, or `cluster.plugins` in the `cloudnative-pg/cluster` chart's values), and a stack member named `ankra-backup-policy-<stack>` holds the object store it archives into. Both are Ankra's: `unprotect` removes them, and a clone or a profile capture leaves them out of the copy while the source stack keeps them. An archiver you configured yourself - your own object store, an in-tree `spec.backup.barmanObjectStore`, the chart's own `backups` section - is left exactly as you wrote it, and Ankra reports that it cannot take restore points of that cluster into the vault: a restore point you take yourself is refused with the reason, and a scheduled backup is skipped with `archiver_unavailable` (as opposed to `archiver_not_wired` below, which means Ankra's own archiver is missing and a protect or manual restore point puts it back).

Four behaviours worth knowing before you rely on it:

* **Databases are in by default; volumes are not.** Protecting a stack does not start copying every claim in its namespaces. Name the volumes you want with `--include-pvc` or `selection.persistent_volume_claims`. Excluding databases from a stack that runs them needs an explicit acknowledgement, and leaves the stack carrying a standing warning.
* **An omitted block preserves protection.** A cluster file that does not mention `backup` leaves the stored policy alone, so an older CLI or a partial file cannot unprotect a stack. Removing protection is an explicit `enabled: false` or `ankra cluster stacks unprotect`, and the write warns about what stops being covered.
* **Protecting a CloudNativePG cluster restarts its instances once.** Ankra adds the barman-cloud archiver to the `Cluster`, and CloudNativePG reconciles that by rolling the instances one at a time - a brief primary failover. Only `protect`, `unprotect` and a restore point you take yourself do this; a scheduled backup never changes a database. If a stack's clusters lost the archiver (an `ankra cluster apply` that replaced the stack from a file without it, say), scheduled backups are skipped with `archiver_not_wired` until you protect the stack again or take a restore point by hand, and the restore point's answer says the instances restart.
* **A CloudNativePG restore point needs the stack protected, and lands in the stack's own vault.** The cluster archives into the object store its policy wired, so a restore point of it cannot be written anywhere else: `restore-points create` on an unprotected stack, or into another vault, is refused with the reason, and nothing is created. A restore point taken in the same minute as the first protect can fail while the instances restart; the next one succeeds.
* **Retention counts the schedule's restore points, not the ones you take by hand.** `daily=7` keeps the newest scheduled restore point of each of the last seven days. A restore point you take yourself - **Back up now**, or `restore-points create` - is kept for the policy's longest period (seven days under `daily=7`), and the safety restore point Ankra takes before an in-place restore is kept for seven days, so a restore stays undoable for a week. Neither one replaces that day's scheduled restore point, and taking another does not delete the one before it.

Per-add-on overrides ride the add-on's settings, for the case where one add-on in a protected stack should be captured differently (or not at all):

```bash theme={null}
ankra cluster addons settings get cnpg-cluster
ankra cluster addons settings set cnpg-cluster --backup-enabled=false
```

## Take a restore point now

```bash theme={null}
ankra cluster stacks restore-points create shop --note "before the 3.2 upgrade" --wait
```

The capture is dispatched by the platform, so without `--wait` the command answers with the restore point in `creating` and the run that will seal it. `--wait` follows that run and prints the sealed restore point.

The vault is resolved in order: `--vault`, then the stack's own policy, then the organisation's single ready vault. With more than one ready vault and nothing naming which, the request is refused rather than chosen for.

The selection resolves the same way - the request's own `--include-pvc` / `--exclude-databases`, then the stack's stored selection, then the default of databases in and volumes only where named. A request that carried no selection never widens to everything.

## See what a restore point holds

```bash theme={null}
ankra cluster stacks restore-points list shop                      # newest first
ankra cluster stacks restore-points list shop --status complete
ankra cluster stacks restore-points list shop --trigger scheduled --limit 10
ankra cluster stacks restore-points get shop 0b2f                  # an unambiguous id prefix is enough
ankra backup restore-points list --cluster production              # across every cluster
```

`get` adds the manifest, every asset in it, and the run that produced it. `list` pages with `--cursor`; `--vault` narrows to one vault, and `ankra backup restore-points list` takes `--cluster` and `--stack`.

> [!WARNING]
>
> **Read the `Not carried` list before you rely on a restore point.** Every listing and every detail read prints it, next to what the restore point does contain - a volume outside the selection, a data engine no adapter covers, an external service that lives outside the cluster - each with the reason and the remedy. An omission nobody read is the same as an omission nobody was told about.

An id prefix is resolved against the stack's 200 most recent restore points, so it is checked for ambiguity only within that window. The full id is what addresses an older restore point with certainty.

## Restore a stack in place

> [!WARNING]
>
> **This destroys before it replaces.** The restore removes the stack's current volumes before it writes the restore point's. Confirmation is typing the stack's own name, not `y/N`.

```bash theme={null}
ankra cluster stacks restore-points restore shop 0b2f --wait
```

The platform accepts the restore and answers with the sequence it will follow, which the command prints before any of it runs:

1. Scale down the workloads in the stack that own the data being restored.
2. Remove the volumes the restore point replaces, so the restored data is not written beside the old data.
3. Restore the restore point's assets onto the cluster through the backup data plane.
4. Scale the workloads back up over the restored data.

`--yes` skips the typed confirmation for scripts. `--force` is needed when the stack's data has changed since the restore point was taken: the refusal compares the restore point's assets against the stack's current inventory, and **an inventory whose live database scan did not run counts as drift**, because "we could not read it" is not "it is unchanged".

> [!WARNING]
>
> **CloudNativePG and Percona databases cannot be restored in place yet.** A restore point carrying one is refused with `Restoring this restore point in place is not supported yet: it carries a database this platform cannot yet recreate in place.` The ordinary restore path would report success over unchanged data, which is worse than refusing - see [Restoring in place](/concepts/backup-vaults#restoring-in-place). Volumes captured by Velero and databases captured as logical dumps, including every `ankra migrate` import, restore in place today.

A restore is also refused against a cluster that is offline or stopped - the sequence destroys before it replaces, so it must not start against a cluster nobody can reach - and against a restore point that is not `complete`.

## Unprotect a stack

```bash theme={null}
ankra cluster stacks unprotect shop
```

Confirmation is the typed stack name again; `--yes` skips it. Turning protection off stops future backups and removes the rendered schedules on the next render. **Every restore point already taken is kept and stays restorable** - removing protection is a decision about the future, not about the past. The `ankra-backup` system stack is not removed either, because those restore points are restored through it.

## Follow a run

Every capture and every restore is a run, and a run has a step for each thing it does. Runs are organisation-scoped, so one listing covers every cluster.

```bash theme={null}
ankra runs list --kind backup --cluster production
ankra runs list --status failed
ankra runs get <run-id>            # the plan, and every attempt of every step
ankra runs cancel <run-id>
ankra runs retry <run-id>          # opens a NEW run from the step that failed
```

`retry` answers with the new run, not the old one: the failed row will never move again. `list` takes `--stack`, `--cursor` and `--limit`, and every command supports `-o json|yaml`.

## Backup posture

Posture is the answer to "is this data protected, and if not, why", rendered wherever someone could lose data: a **Protected** / **Unprotected** / **Protection unknown** pill on stack headers, stack cards and the Stack Builder, a backup posture card on the cluster overview, a fleet widget on the organisation dashboard, and a **Protect your stateful stacks** milestone on the setup checklist once the organisation runs something stateful.

| State | What it means | What to do |
| - | - | - |
| **Protected** | An enabled policy naming a vault that is ready | Nothing. Check the restore points are actually landing |
| **Unprotected** | No policy; or the vault it names is missing, provisioning or in error; or databases are excluded from a stack that runs them; or the stack holds no data at all | The reason says which. A stack with no data assets is unprotected but not a finding |
| **Unknown** | The `backup` block did not decode, the vault lookup could not be answered, or the cluster's inventory has not landed | Check the cluster is online and reporting; an unknown is never reported as unprotected |

An organisation with no vault at all gets a call to action rather than a report that everything is exposed, and a posture that has not loaded renders nothing rather than flashing a verdict it does not have.

## Troubleshooting

| What you see | Cause | Remedy |
| - | - | - |
| `Backups are not enabled for this organisation.` | The **backups** feature is switched off for the organisation the CLI is acting on | Check `ankra org current` first, then [contact support](/platform/support). See [Not enabled yet?](#not-enabled-yet) |
| `This backup vault has not verified; re-verify it before taking a restore point.` | The vault's last credential check failed or never ran | `ankra backup vaults verify <name>`, and [When verification fails](#when-verification-fails) for what the excerpt means |
| `This organisation has more than one ready backup vault; name the one to write to.` | The request named no vault, the stack has no policy, and there is more than one candidate | Pass `--vault <name>`, or protect the stack so its policy names one |
| `This organisation has no ready backup vault to write a restore point to.` | No vault is `ready` | Register or provision one, above |
| `This selection covers none of the stack's data, so the restore point would carry nothing.` | The selection excluded everything the stack holds | `ankra cluster stacks data list <stack>` to see the asset names, then widen the selection |
| `This stack's data has changed since the restore point was taken` | Drift between the restore point and the live inventory, **or** an inventory whose database scan did not run | Take a fresh restore point, or restore with `--force` if the drift is expected |
| `Restoring this restore point in place is not supported yet` | The restore point carries a CloudNativePG or Percona database | Not yet available. The capture is still good and the databases are still in the vault |
| `Only a complete restore point can be restored.` | The restore point is `creating` or `failed` | `ankra runs get <run-id>` on the run that was sealing it |
| `This cluster is not online, so its data cannot be restored right now.` | The target cluster is stopped or its agent is not connected | Bring the cluster back, then retry |
| `A backup, restore or clone is using this restore point` | A delete raced a run that is reading the restore point | Wait for the run to finish, or `ankra runs cancel <run-id>` |
| `Backup stack: installing` never becomes `ready` | The cluster's agent is too old to run the backup jobs, or a resource name the backup stack needs is already taken by a user-authored resource | Upgrade the [cluster agent](/concepts/cluster-agent); rename the colliding resource. `ankra runs list --cluster <name>` shows steps that never got claimed |
| `Its objects were left in the bucket: ...` after a delete | No sweep could be dispatched - the source cluster is gone, the vault is gone, or the agent does not carry the object-delete job | The restore point row is removed either way. Remove the objects from the bucket yourself so you stop paying for them, or upgrade the agent and let the retention sweep take them |

> [!NOTE]
>
> Diagnose all of this with the Ankra CLI, not `kubectl`. The backup data plane is a stack Ankra owns and reconciles, so a change made against the cluster directly is reverted on the next render.

## Permissions

| Permission | Allows |
| - | - |
| `backups.read` | Seeing vaults, policies, restore points, runs and posture |
| `backups.operate` | Verifying a vault; taking restore points and running restores |
| `backups.manage` | Creating and deleting vaults; protecting and unprotecting stacks; deleting restore points |

Organisation admins hold all three. A member with only `backups.read` sees the vault list read-only; the page says so and names the permission an admin has to grant for adding, verifying or deleting a vault. Both gates - the organisation's **backups** feature and the permission - are checked in that order, so an organisation without the feature answers the same way whatever the caller may do.

## Not enabled yet?

Backups are on for every organisation unless the **backups** feature has been switched off for yours. While it is off:

* The **Backups** settings page renders an explanation instead of the vault list, and no protection pill, posture card or fleet widget appears anywhere.
* `ankra backup …`, `ankra cluster stacks protect|unprotect|restore-points|data …` exit non-zero with `Backups are not enabled for this organisation.` followed by what to do about it. A real permission refusal on the same commands keeps its own wording, so the two are never confused.
* The API answers `403` with that same text on every backups route, browser and token alike - a personal access token cannot reach the lane in an organisation where it is dark.
* A `backup` block in a cluster file is rejected on apply with the same sentence.

Two things to check before asking for it to be enabled:

1. **The right organisation is selected.** The CLI acts on the current organisation - `ankra org current` shows which, and `ankra org switch <name>` changes it.
2. **The account is in the organisation that was enabled.** Enablement is per organisation, not per user.

Then [contact support](/platform/support) to have the **backups** feature enabled for the organisation.

## Command reference

The generated CLI reference carries every flag and default of these families:

| Family | Reference |
| - | - |
| `ankra backup vaults`, `ankra backup restore-points` | [ankra backup](/reference/cli/backup) |
| `ankra cluster stacks data`, `protect`, `unprotect`, `restore-points` | [ankra cluster](/reference/cli/cluster) |
| `ankra runs` | [CLI command reference](/reference/cli/index) |

> [!NOTE]
>
> The reference is regenerated from the CLI source on each release, so the restore-point families appear there from **v0.17.0**. Until then `ankra <command> --help` is the authority on a flag.

## Next steps

> [card] [Backup vault concepts](/concepts/backup-vaults)
>
> How vaults, policies, restore points, runs and posture fit together.

> [card] [The backup block](/reference/importcluster#spec-stacks-backup)
>
> Every field and default of a stack's backup policy, in the cluster file.

> [card] [Clone stacks between clusters](/guides/clone-stack)
>
> Clone a stack's configuration today - data follows via restore points.

> [card] [Move a Docker deployment in](/guides/migrate-from-docker)
>
> `ankra migrate` carries databases through the same vault.


# Build a Bazel Repository with Ankra Pipelines
Source: https://docs.ankra.ai/guides/bazel-pipelines

Run Bazel builds and tests on Ankra Pipelines - Bazelisk and the Bazel output tree on the shared workspace, a disk and repository cache that survives between runs, JUnit test results from bazel-testlogs, an optional remote cache, and how a Bazel-built binary gets into an image.

Bazel runs on Ankra Pipelines as an ordinary `run` stage. Ankra brings what Bazel itself leaves to the CI system: a cluster to run on, caches kept between runs, test results in the run's check, and an image build that is scanned and gated before it is published. Bazel brings hermetic builds and an action cache, so a run with a warm cache only rebuilds what changed.

This guide assumes the repository is already connected to Ankra Pipelines. If it is not, start with [Get started with Ankra CI](/get-started/ankra-ci).

## What Bazel needs from a pipeline step

A pipeline step differs from a laptop or a hosted CI runner in a few ways, and each one matters for Bazel. The [three rules](/guides/ankra-ci-starter-pipelines#three-rules-every-step-follows) apply to every step; this is what they mean here:

* **The Bazel output tree goes under `/workspace`.** `HOME` is `/tmp`, which is 256 MiB and held in memory. Bazel's default output root is under `HOME` and outgrows that within one build, so pass `--output_user_root=/workspace/.ankra-bazel/root` on every Bazel command.
* **Bazel comes from Bazelisk.** The root filesystem is read-only, so nothing can be installed into the image. The step installs Bazelisk into the workspace, and Bazelisk downloads the Bazel version pinned in `.bazelversion`.
* **Downloads need network.** A `run` stage has no network by default. `defaults.network: "egress-https"` lets Bazel fetch toolchains and external dependencies from public hosts.
* **Bazel needs more than the default size.** A step gets 500m of CPU and 1Gi of memory unless it asks for more. Give the Bazel stage a few cores and several gigabytes, and a longer timeout for the first cold build.

## Add a CI config to `.bazelrc`

Keep the CI flags in a named config, so the pipeline only says `--config=ci` and you can run the same build locally:

```bash theme={null}
# .bazelrc
build:ci --disk_cache=/workspace/.ankra-bazel/disk-cache
build:ci --repository_cache=/workspace/.ankra-bazel/repository-cache
build:ci --color=no
build:ci --curses=no
build:ci --show_progress_rate_limit=10
test:ci --test_output=errors
```

`test` inherits every `build` flag, so the caches apply to tests too. On Bazel 7.4 or later, add `build:ci --experimental_disk_cache_gc_max_size=20G` to keep the disk cache from growing without limit.

The caches, Bazel's output root and the Go tools all sit under `/workspace`, which is also the root of the checkout, so `bazel test //...` would walk into them. List them in a `.bazelignore` at the repository root:

```text theme={null}
.ankra-bazel
.ankra-go
```

## The pipeline

This `.ankra/pipeline.yaml` tests every target on each pull request and push to `main`, and reports each test in the run:

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "my-repo"
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  manual: {}
workspace:
  size: "30Gi"
defaults:
  network: "egress-https"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "test"
    kind: "run"
    image: "golang:1.26"
    needs: ["checkout"]
    resources:
      cpu: "4"
      memory: "8Gi"
    timeout: "90m"
    env:
      GOPATH: "/workspace/.ankra-go"
      GOCACHE: "/workspace/.ankra-go/cache"
      GOFLAGS: "-buildvcs=false"
      BAZELISK_HOME: "/workspace/.ankra-bazel/bazelisk"
    cache:
      - key: "bazel-${{ hashFiles('MODULE.bazel.lock', '.bazelversion') }}"
        paths:
          - ".ankra-bazel/disk-cache"
          - ".ankra-bazel/repository-cache"
          - ".ankra-bazel/bazelisk"
          - ".ankra-go/bin"
        restore_keys: ["bazel-"]
    test_results:
      - format: "junit"
        path: "test-results"
    run: |
      go install github.com/bazelbuild/bazelisk@v1.25.0
      bazel() { /workspace/.ankra-go/bin/bazelisk --output_user_root=/workspace/.ankra-bazel/root "$@"; }

      status=0
      bazel test --config=ci //... || status=$?

      mkdir -p /workspace/test-results
      cd "$(bazel info --config=ci bazel-testlogs)"
      find . -name test.xml | while read -r report; do
        cp "$report" "/workspace/test-results/$(echo "${report#./}" | tr / _)"
      done
      exit "$status"
```

What each part does:

* **`golang:1.26`** is the image because it has the C toolchain Bazel's default rules expect and lets `go install` fetch Bazelisk. Any image your organisation's image policy allows works the same way, as long as it has a shell and a compiler.
* **The cache** keeps Bazel's disk cache, repository cache and downloaded Bazel binary between runs, keyed on the module lock file and the Bazel version. A repository still on `WORKSPACE` keys on the files that pin its external dependencies instead. Bazel's own cache decides what to rebuild, so a run where little changed finishes in a fraction of the cold time.
* **`test_results`** reads the JUnit `test.xml` Bazel writes for every test target. The script copies them out of `bazel-testlogs` into one directory before the step ends, flattening each path into a file name so two targets never overwrite each other's report.
* **`status`** holds Bazel's exit code while the reports are copied, so a failing test still reports its results and still fails the step.

> [!NOTE]
>
> `cache`, `resources` and `timeout` are protected settings. They take effect once an administrator approves the pipeline on the default branch, so the first run before that approval is cold and uses the default size. A large repository can run out of memory or time on that first run - approve the definition and run it again.

## Use a remote cache

Bazel's remote cache shares results between runs, branches and developers' machines. Ankra does not host one, but a step can reach any cache that speaks Bazel's remote cache protocol over HTTPS on port 443. Store the cache's API key as an organisation variable, which the CLI reads from standard input:

```bash theme={null}
ankra org variables set BAZEL_REMOTE_CACHE_KEY -
```

Declare it in the pipeline and name it on the stage. The value arrives as a file under `/run/agent-secrets`:

```yaml theme={null}
secrets:
  - name: "bazel_remote_cache_key"
    from: "org_variable"
    key: "BAZEL_REMOTE_CACHE_KEY"
stages:
  - name: "test"
    kind: "run"
    secrets: ["bazel_remote_cache_key"]
    run: |
      bazel() { /workspace/.ankra-go/bin/bazelisk --output_user_root=/workspace/.ankra-bazel/root "$@"; }
      bazel test --config=ci \
        --remote_cache=grpcs://<your-remote-cache-host> \
        --remote_header="<your-cache-header>=$(cat /run/agent-secrets/bazel_remote_cache_key)" \
        //...
```

The header name depends on the cache you use. `secrets` is a protected section too, so the binding reaches the step once the definition that declares it is approved on the default branch.

## Build an image from a Bazel target

A `kind: "build"` stage cannot use a binary that an earlier `run` stage built. It does not read the workspace the other stages share: it runs in its own namespace and fetches the commit itself, so it sees only what is in the repository at that commit. See [where a build's paths are resolved from](/guides/pipeline-reference#where-a-builds-paths-are-resolved-from).

To ship a Bazel-built binary as an image, build the binary inside the image build: a multi-stage Dockerfile whose first stage installs Bazelisk and runs `bazel build`, and whose final stage copies the binary out of the first one. The build stage then needs nothing from earlier stages. A `build` stage has `egress-https` by default, so Bazel can fetch its dependencies there, but it does not see the caches under `/workspace`.

To ship the binary to machines outside Kubernetes instead, a `build` stage with `build.bundle` packs a directory an earlier stage left in the workspace into a release bundle rather than building an image. The `deploy` row of [kind-specific blocks](/guides/pipeline-reference#kind-specific-blocks) describes it.

## Make it faster

* **Let Bazel skip unchanged work.** With the cache warm, `bazel test //...` reruns only the tests whose inputs changed. That is usually faster than narrowing the target list by hand.
* **Skip runs that touch nothing Bazel builds.** `affected:` reads Go and pnpm import graphs, not Bazel's, so use path filters instead: `on.pull_request.paths: ["!docs/**", "!*.md"]` records a docs-only change as skipped. See [Fast CI](/pipelines/fast-ci).
* **Split slow suites onto a schedule.** Tag long tests `slow`, leave them out with `--test_tag_filters=-slow` on pull requests and pushes, and run them from an `on.schedule` stage at night.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| `No space left on device` early in the build | Bazel's output root is still under `HOME` (`/tmp`) | Pass `--output_user_root=/workspace/.ankra-bazel/root` before the command, on every Bazel call |
| The step fails with the diagnosis `out_of_memory` | Bazel and its workers outgrew the step's memory | Raise `resources.memory`, or run fewer actions at once with `build:ci --jobs=4` |
| `fetching ... failed` or a download times out | The stage has no network, or the host is private | Set `defaults.network: "egress-https"`; a private mirror needs an administrator to allow its address range |
| Every run is cold | The pipeline definition is not approved yet, or the cache key changes on every run | Approve the definition on the default branch; check the step's **CACHE** column in `ankra pipeline get` |
| A sandbox error such as `linux-sandbox failed` | The step's container does not allow the namespaces Bazel's Linux sandbox uses | Add `build:ci --spawn_strategy=processwrapper-sandbox,local` to `.bazelrc` |
| Tests pass but the run shows no test results | The reports were not copied before the step ended | Keep the copy loop after `bazel test`, and point `test_results.path` at the directory it writes |

[Caches](/pipelines/caching) explains keys, trust scopes and retention, and the [pipeline reference](/guides/pipeline-reference) lists every field used here.


# Work the AI Board with Your Own Agent
Source: https://docs.ankra.ai/guides/board-own-agent

Connect Claude Code, Cursor, Codex or your own agent to Ankra over MCP and have it pick up board tickets, investigate, draft a plan for human approval, carry it out, and close the ticket with evidence.

The [AI board](/platform/ai-board) is not only for Ankra's agents. Any MCP client you connect - Claude Code, Cursor, Codex, or an agent you wrote - can read the board, file tickets, investigate, draft a plan, and carry it out once a person approves it. The ticket keeps one timeline whoever does the work, so your team sees the same history, Slack or Teams thread and [Jira or Linear issue](/guides/ticket-sync) either way.

There are four ways to combine Ankra's AI with your own. This guide covers the first.

| You want | Where it is covered |
| - | - |
| Your own agent works board tickets | This guide |
| Ankra's agents run on your own model (Anthropic, OpenRouter, an OpenAI-compatible endpoint) | [Models and Cost](/platform/ai-provider) |
| Ankra's agents call your own tools | [AI Connections - MCP Tool Servers](/platform/ai-connections#mcp-tool-servers) |
| Board tickets show up in your own tracker or automation | [Sync board tickets to Jira, Linear, or a webhook](/guides/ticket-sync) |

## How your agent fits the board

Your agent acts **as you**. Every comment, status change and plan it writes is recorded on the timeline under the user who owns the token or the OAuth connection, stamped as written by a model. The same gates apply to it as to Ankra's own agents, and one applies more strictly:

* **It can** list and read tickets, file new ones, comment, move a ticket through its statuses, draft and revise the plan, ask for review, request changes on a plan, answer a blocked ticket's question, and close a ticket with a resolution.
* **It cannot approve a plan.** Plan approval is a human action in the product or a Slack or Teams thread, and an MCP token cannot reach it by any route. Until a person approves, the ticket cannot move to **Executing**.
* **It cannot be the assignee.** `ticket_assign` hands a ticket to one of Ankra's agents, which then starts working it. Your agent owns a ticket by working it, and you show the board it is yours by assigning the ticket to yourself.
* **Its comments do not wake Ankra's agents.** Only a person's comment re-admits a parked ticket to Ankra's dispatcher, so a model cannot keep an Ankra agent spinning.

```mermaid theme={null}
flowchart LR
  T[Triage] --> I[Investigating]
  I --> P[Planning]
  P --> R[Awaiting review]
  P --> A[Awaiting approval]
  R --> A
  A -->|a person approves| E[Executing]
  E --> V[Verifying]
  V --> D[Done]
```

**Awaiting review** applies only when a reviewer agent is configured in the ticket desk settings; otherwise a plan goes straight to **Awaiting approval**.

## Prerequisites

* The AI board is available in your organisation (**AI** → **Board** in the sidebar). The ticket tools do not appear over MCP while it is not.
* Your role includes the `ai.execute` permission - the built-in **owner**, **admin**, **operator** and **member** roles do, **viewer** does not. See [Roles and Access](/guides/roles-and-access).
* An MCP client connected to Ankra with **write** access. Reading the board needs `mcp:read`; every ticket change needs `mcp:write`. See [MCP Server](/platform/mcp-server).
* Someone who can approve the plans your agent drafts.

## Step 1: Connect your agent

Follow [MCP Server](/platform/mcp-server) for your client. Claude connects over OAuth and asks you to approve `mcp:read` or `mcp:write` access; Cursor and other clients take a token:

```bash theme={null}
ankra tokens create my-board-agent --scopes mcp:read,mcp:write
```

To confirm the board is reachable, ask the agent to list the open tickets. It should call `ticket_list` and return them with their numbers, such as `T-412`.

> [!TIP]
>
> When the agent runs unattended, create the token for a dedicated member account rather than your own. Its comments and status changes are then attributed to that account rather than to a person.

## Step 2: Pick up a ticket

Find work with `ticket_list`, which filters by `status`, `kind`, `priority`, `cluster_id`, `resolution` and free-text `search`. Then read one in full with `ticket_get`, which takes a `ticket_number` (`412` for `T-412`) or a `ticket_id` and returns its body, plan, review state, links and newest timeline events.

To file a ticket instead, call `file_ticket` with a `title` and a `body`, and optionally:

| Parameter | Values | Default |
| - | - | - |
| `kind` | `incident`, `insight`, `gap`, `automation`, `request`, `chore` | `request` |
| `priority` | `urgent`, `high`, `medium`, `low` | `medium` |
| `cluster_id` | The cluster the work targets | none |

Filing the same `condition` again is folded into the open ticket rather than creating a second one.

**Move the ticket out of Triage as soon as your agent takes it.** Ankra's dispatcher assigns unowned **Triage** tickets to its own board workers, so a ticket left there can be claimed by an Ankra agent while yours is reading it. Ask your agent to call `ticket_update_status` with `status: investigating`; the dispatcher does not claim tickets outside **Triage**. Then assign the ticket to yourself from its assign menu (`a` on the board), so the board shows a person owns it rather than escalating it as unstaffed.

Example prompt:

```text theme={null}
Take T-412 off the Ankra board: move it to investigating and comment that I'm working it from Claude Code.
```

## Step 3: Investigate and record findings

Your agent investigates with Ankra's read tools - `get_pods`, `get_pod_logs`, `get_events`, `query_prometheus`, `get_stack_details` and the rest in the [MCP Tool Reference](/platform/mcp-tools) - and with whatever else it can reach, such as your repository checkout.

Have it post what it finds with `ticket_comment`. The timeline is what the approver reads, and it is relayed as comments to any [sync connection](/guides/ticket-sync), so findings written there reach Jira, Linear and the ticket's Slack or Teams thread too.

If the ticket names no cluster, or the wrong one, `ticket_set_cluster` binds it.

## Step 4: Draft the plan and send it for approval

**1. Move to Planning**

`ticket_update_status` with `status: planning`.

**2. Write the plan**

`ticket_draft_plan` stores the plan as markdown on the ticket. Write it for the person who approves it: what will change, on which cluster and stack, how to verify it, and how to roll it back. Calling it again revises the plan.

**3. Ask for review**

`ticket_request_review` moves the ticket to **Awaiting review** when your organisation has a reviewer agent, and straight to **Awaiting approval** when it does not. A reviewer that requests changes sends the ticket back to **Planning** with its rationale on the timeline.

At **Awaiting approval** Ankra raises **Plan awaits your approval** for the people who decide, and the ticket appears in the **Needs a human** view.

## Step 5: A person approves

Approve the plan on the ticket's page - the decision panel at the top offers **Approve** and **Reject** - or with **Approve plan** on the escalation card in the ticket's Slack or Teams thread. Approving moves the ticket to **Executing**. Rejecting asks for a reason and sends it back to **Planning**, where your agent reads the reason and revises the plan.

Your agent can wait by polling `ticket_get` until `plan_status` reads `human_approved` and `status` reads `executing`. A rejection shows as `status: planning` with your reason as the newest timeline event.

> [!NOTE]
>
> Approval is a gate on the ticket, not a grant of access. Your agent carries out the plan with its own token, so what it may change is whatever that token and your role allow - an `mcp:write` client runs a write as soon as it calls the tool, with no second confirmation from Ankra. Grant write access only to an agent you trust to stay inside the approved plan.

## Step 6: Carry out the plan, verify, and close

**1. Execute**

The agent carries out the approved plan with Ankra's write tools. Writes that start platform work answer at once with an `operation_id`; `wait_for_execution` blocks until it settles. Have it comment each step it runs, so the timeline shows what changed: the gated writes it makes over MCP are recorded on a separate `chat-fix` receipt that stays off the board, not under this ticket's **Changes**.

**2. Verify**

`ticket_update_status` with `status: verifying`, then check the fix held against live state - the pod is ready, the alert stopped firing, the error rate dropped.

**3. Close**

`ticket_update_status` with `status: done` and a `resolution`: `fixed`, `no_action`, `duplicate`, `wont_fix` or `escalated`.

`fixed` needs evidence: an `evidence_kind` and an `evidence_reference` together. From your own agent that is normally `observation` (the tool it called and the values it read, quoted so a reader can re-check them) or `link` (a URL to a dashboard, a CI run or a pull request).

Example prompt:

```text theme={null}
The fix for T-412 is applied. Verify the payments-api pods are ready and have not restarted in 10 minutes, then close T-412 as fixed with what you observed as evidence.
```

## When a ticket is blocked on a choice

When an Ankra agent parks a ticket at **Blocked** with a question and options, `ticket_get` shows it under `decision_request`, and `ticket_decide` records the answer - an `option_key`, an `answer` in your own words, or both - and resumes the agent.

> [!WARNING]
>
> Ankra records a decision made through `ticket_decide` as relayed from the token's user, and does not check that a person chose it. Have your agent relay only decisions you made, never pick an option on its own.

## Start your agent from new tickets

To have new tickets reach your agent without anyone asking, add a **webhook** [sync connection](/guides/ticket-sync) that points at a receiver you run. Each matching ticket arrives first as a signed `ticket.created` request carrying the full ticket - its number, kind, priority, cluster and body. Your receiver verifies the signature and starts your agent on that ticket number; from there the agent works it through the steps above. Narrow the connection's **Kinds** and **Minimum priority** filters to the tickets you want your agent on.

A new connection picks up the tickets that are live when you add it and everything that changes afterwards. It never writes back to the board: everything your agent does goes through MCP.

## Limits

* Each token may make 120 read calls and 20 write calls per minute. A rate-limited call says so; wait a minute and retry.
* Every tool call has a 55-second deadline. A write that timed out may still have run, so read the ticket before repeating it.
* A human gate that times out closes the ticket as `expired`. Nothing is executed and nothing is recorded as fixed.

## Troubleshooting

| What your agent sees | What it means |
| - | - |
| `Plan approval is a human action: ask the user to approve the plan on the AI board ...` | An MCP client tried to approve its own plan. A person approves it on the ticket page or in its thread. |
| `A human must approve the ticket's plan on the AI board before execution begins ...` | The agent tried to move a ticket to **Executing** before approval. Wait for the approval to move it there. |
| `The ticket has no plan to approve. Draft one with ticket_draft_plan ...` | **Awaiting approval** needs a plan. Draft one first. |
| `This desk requires a peer review before the human gate ...` | Your organisation requires the reviewer agent's verdict. Call `ticket_request_review` and wait for it. |
| `Cannot move a ticket from 'triage' to 'verifying'.` | Statuses move one hop at a time along the board's lifecycle. Go through the statuses in between. |
| `This ticket is not waiting on a decision.` | `ticket_decide` only answers a ticket at **Blocked** with a pending question. |
| `No ticket with that ticket_number exists in this organisation.` | The number is wrong, or the client is connected to another organisation. MCP access is bound to the organisation chosen when the token or connection was created. |
| No ticket tools in the client's tool list | The AI board is not available in the organisation, or the token has no MCP scope. Ticket changes also need `mcp:write`. |
| A tool reports that it needs `mcp:write` | The client holds read-only access. Reconnect with write access. |
| An Ankra agent started working the same ticket | The ticket was still in **Triage** when the dispatcher swept it, or someone assigned it to that agent. Move tickets out of **Triage** as soon as your agent takes them. |

## Related pages

* [AI Board](/platform/ai-board) - statuses, plans, review and approval
* [MCP Server](/platform/mcp-server) - connecting a client, scopes and how calls behave
* [MCP Tool Reference](/platform/mcp-tools) - every ticket tool, under **Tickets & Collaboration**, and the scope it needs
* [`ankra tickets`](/reference/cli/tickets) - work the board from a terminal
* [Sync board tickets to Jira, Linear, or a webhook](/guides/ticket-sync) - mirror tickets out to your tracker


# Branch Demos
Source: https://docs.ankra.ai/guides/branch-demos

Launch a throwaway demo of any branch build on your staging cluster - with environment variables, an optional Postgres, and an automatic teardown timer

> [!NOTE]
>
> A branch demo runs a branch's already-built container images in their own isolated namespace on your organisation's staging cluster, and stops itself when the timer runs out. Use it to show work in progress, reproduce a bug against a specific build, or hand a reviewer a live URL instead of a screenshot.

Pull requests get [previews automatically](/guides/pr-preview-environments). This guide covers the manual path: the **Launch a branch demo** dialog in an application's **Previews** section, and its CLI and MCP equivalents.

***

## Prerequisites

**1. Connect the repository as an application**

The branch must belong to a [connected application](/concepts/applications). Application setup adds the CI definition that builds its images - `.ankra/pipeline.yaml` for a new application, or the generated GitHub Actions workflow.

**2. Set the organisation's staging cluster**

An admin sets it under **AI** → **Settings** → **Workspaces**. Every demo lands there. Without it, there is nowhere to launch.

**3. Build the branch at least once**

A demo deploys an image, it does not build one, so the branch needs a tag in the application's registry. The generated pipeline and the generated workflow publish only the tracked branch: for any other branch, see [Which image a demo finds](#which-image-a-demo-finds). If nothing was ever published, the dialog offers [Fix the build](#no-built-image-for-this-branch).

**4. Optional: a demo base domain for HTTPS**

Without one, demos are served over the staging cluster's own Ankra zone (`*.ankra.cc` by default, or the [Ankra domain your organisation selected](/concepts/applications#the-preview-url)) on plain HTTP, or stay in-cluster-only.

***

## Launch a demo

Open the application, open the **Previews** section, and choose **Launch preview**.

### Staging cluster capacity

The panel at the top of the dialog reports the staging cluster's live headroom - nodes ready, CPU and memory in use, pod count, and how many demos are already running - and highlights a figure in amber once it passes 90% of capacity. It is informational: a busy cluster does not block the launch, but it tells you whether your pods will actually get scheduled.

Each demo namespace carries its own hard `ResourceQuota`, so one demo can never exhaust the cluster:

| Demo type | Pods | CPU limit | Memory limit |
| - | - | - | - |
| Single service | 5 | 2 | 2 Gi |
| Full stack (stack profile attached) | 20 | 8 | 16 Gi |

### Branch

Pick the branch to demo. The list marks the application's configured **build branch** and the repository **default** branch. As soon as you pick one, Ankra checks the registry for a matching image and reports the verdict inline:

| Verdict | Meaning |
| - | - |
| ✅ **Build found** | The resolved image tag is shown and will be deployed. |
| ⚠️ **No built image was found** | Nothing was published for this branch yet. See [below](#no-built-image-for-this-branch). |
| ❌ An error message | The registry or the repository could not be read - the message names the cause. |

### Which image a demo finds

Ankra looks in the application's registry repository for these tags, in this order, and deploys the first one it finds:

1. `sha-<7>` - the first seven characters of the branch's head commit, the only tag that is provably this head's build,
2. for each open pull request from the branch, `sha-<7>` of its merge commit, then `pr-<number>`,
3. the branch name, with every character other than letters, digits, `.`, `_` and `-` replaced by `-` (`feature/login` becomes `feature-login`).

A pull request tag is built from merging the branch into its base, not from the branch head, and the dialog says so when it picks one.

What publishes these tags depends on what builds the application (see [Ship Your App](/guides/deliver-your-app#where-the-image-is-built)):

| Builder | Tags it publishes |
| - | - |
| Ankra Pipelines, as generated | `sha-<7>` for commits on the tracked branch only: the `publish` stage runs on a push to that branch, not on a pull request |
| Generated GitHub Actions workflow | `sha-<7>` and the branch name for commits on the tracked branch only. A pull request is built and scanned but never pushed |
| Your own workflow | Whatever it pushes |
| Ankra platform builders | `sha-<7>` of any commit you ask for, where Ankra has enabled platform builders for your organisation |

So a demo of any branch other than the tracked one needs an image from somewhere else. Build the branch's head on Ankra platform builders:

```bash theme={null}
ankra application build start <application-id> --commit <full-sha> --ref feature/login --reason demo --wait
```

Or push a `sha-<7>` tag from your own CI, or pick an existing tag with the [image tag override](#advanced-options).

### Components (monorepos only)

A single-app repository has nothing to choose. A monorepo shows every deployable component with its own build status and tag, and **all of them deploy by default** - each as its own pod in the one namespace, so a frontend and its API come up wired together instead of half an application answering where the other half belonged.

* **Untick a component** to leave it out of this launch. At least one must stay ticked.
* **The web entry** owns the demo's URL root. Ankra marks the component its heuristic picked; **set as entry** moves the badge to another one.
* **Path badges** on the remaining components show where they are published under the same host, so in-cluster callers and the browser reach the same demo.

The container port prefill follows the web entry, and the launch is blocked until every ticked component has an image (or you supply an [image tag override](#advanced-options), which applies to all of them).

### Stop automatically after (hours)

The teardown timer. It is pre-filled with the organisation's default demo TTL and capped by your role's limit, which admins set per role (admin, operator, member) under **AI** → **Settings** → **Workspaces**. The field states your own ceiling. When the timer expires the namespace is deleted; nothing survives it.

### Environment and database

Expand **Environment & database** to set variables for this launch only. **Add variable** adds a row - a name, a value, and a **Secret** checkbox. Values marked secret are stored as Ankra secret slots in the platform secret store and mounted as a Kubernetes Secret at deploy time; the plaintext never persists in the application's configuration.

Toggle **Attach a throwaway Postgres** and an ephemeral pgvector-capable Postgres is provisioned inside the demo namespace with a per-demo random password, then destroyed with it. Nothing is injected automatically, because every codebase names its configuration differently - reference the placeholders in your own variable *values* instead:

| Placeholder | Resolves to |
| - | - |
| `${{ ankra.demo_database.url }}` | Full `postgres://` connection string |
| `${{ ankra.demo_database.host }}` | In-namespace service host |
| `${{ ankra.demo_database.port }}` | `5432` |
| `${{ ankra.demo_database.name }}` | Database name |
| `${{ ankra.demo_database.user }}` | Database user |
| `${{ ankra.demo_database.password }}` | The per-demo random password |

With the toggle on, the editor offers quick-add buttons for the common names (`DATABASE_URL` and friends) already wired to the right placeholder.

> [!NOTE]
>
> Everything in this section applies to **this launch only**. To give every demo of the application the same configuration - manual launches, CLI and MCP deploys, and the automatic PR previews - set it once as the application's demo defaults in the environment template under **Previews** (*Preview settings*). Per-launch values win by name. Full reference: [environment variables and a throwaway database](/concepts/applications#environment-variables-and-a-throwaway-database).

### Advanced options

| Field | Use it when |
| - | - |
| **Image tag override** | You want a specific tag rather than the one resolved from the branch build - an older build, or a tag pushed outside the standard workflow. It applies to every included component, so it also rescues a partially built branch. Leave empty to use the resolved tag. |
| **Container port** | Your application listens on something other than the detected port. It is pre-filled from the web entry's build metadata and stops following it once you edit the field. |

### Full-stack demos

When the application designates a **stack profile** for demos, the dialog says so before you launch. That launch also instantiates the profile as a demo-scoped Stack in the same namespace - dependencies, add-ons, and manifests included - and tears the whole thing down with the demo. The per-demo quota rises to the full-stack row in the table above. Configure the designation in the environment template under **Previews**.

The **Previews** section also names that profile and lists the profile's own live demos, each one linking straight to its details. A profile can be demoed on its own - the same stack, without an application in front of it - which is usually a cheaper way to look at it than launching a whole application demo. See [Stack Profile Demos](/guides/stack-profile-demos).

***

## Reach the running demo

Launching drops you back in the **Previews** section, which shows one card per active preview with its status, preview URL, and remaining TTL. Each demo has a detail page carrying live provisioning progress read from the staging cluster, the namespace's bill of materials, Kubernetes events, and pod logs.

How you reach it depends on DNS:

1. **An organisation demo base domain**, if configured, wins outright: `<namespace>.<demo-base-domain>`, with your ingress class and TLS secret.
2. **Otherwise the staging cluster's delegated Ankra DNS zone**, when active: `<namespace>.<cluster-id>.<org-id>.<ankra-domain>` over HTTP (`ankra.cc` by default, or the Ankra domain your organisation selected).
3. **Otherwise in-cluster only** - the demo still runs, and the detail page gives you the service DNS name and a ready-made `kubectl port-forward` command.

The full resolution order is documented under [the preview URL](/concepts/applications#the-preview-url).

***

## From the CLI and the AI Assistant

> [tab] CLI
>
> ```bash theme={null}
> # Deploy a branch demo
> ankra application demo deploy <application-id> --branch feature/login
>
> # Override the teardown timer
> ankra application demo deploy <application-id> --branch feature/login --ttl-hours 8
>
> # List active demos, then stop one early
> ankra application demo list <application-id>
> ankra application demo stop <application-id> <workspace-id>
> ```
>
> The deploy response includes `preview_url` when a public host was resolved.

> [tab] AI / MCP
>
> Ask the AI Assistant to demo a branch, or call the `deploy_pr_demo` tool directly - it is allowed in **Ask** mode, because a demo is isolated and self-expiring. Pass `env` to set per-launch variables. Tear down early with `demo_stop`, and inspect a failed one with `get_demo_diagnostics`.

***

## No built image for this branch

When the registry holds nothing for the branch, the dialog does not dead-end. It offers, in order of effort:

* **Recent image tags** from the same repository as one-click chips - handy for demoing the last good build while a new one is still running.
* **Fix the build**, which diagnoses why no image exists and applies the safe fixes it can: restarting a failed application setup, repairing publish readiness, or re-running the latest workflow so it can push to the registry. When the deterministic fixes cannot unblock it, Ankra dispatches an agent mission and links you to its run so you can watch the work.
* **Open CI/CD**, which jumps straight to the application's pipeline runs.

***

## Stopping a demo

A demo stops itself when its TTL expires - namespace deleted, quota released, database gone. Stop one early with **Stop preview** in the **Previews** section, with `ankra application demo stop`, or with the `demo_stop` tool. There is nothing to clean up afterwards.

> [!WARNING]
>
> Demo namespaces are ephemeral by design. The throwaway database starts empty on every deploy and is wiped with the namespace - run your migrations on boot and never point a demo at data you care about.

***

## Troubleshooting

| Symptom | What to check |
| - | - |
| **Launch demo** is disabled | The dialog names the reason on hover: no branch picked, an unresolved image tag, a TTL beyond your role's cap, an invalid container port, or an incomplete environment variable. |
| **No built image was found** for a branch other than the tracked one | Expected with the generated pipeline or workflow, which publish only the tracked branch. See [Which image a demo finds](#which-image-a-demo-finds). |
| No branches are listed | The application's Git credential can no longer read the repository. Re-check it on the application's settings, then reopen the dialog. |
| Deployed, but the pod crash-loops | The demo runs *your* image, so a boot crash is application-side. Read the pod logs on the demo's detail page. If the container refuses to start without configuration, Ankra dispatches a [pre-setup agent](/concepts/applications#automatic-pre-setup-when-a-demo-crashes) that works out the missing variables, saves them as the application's demo defaults, and redeploys. |
| Pods stay `Pending` | The namespace quota or the cluster is full. Check the capacity panel and the demo's Kubernetes events, and stop demos you no longer need. |
| The preview URL does not resolve | The staging cluster needs an active Ankra DNS zone, or the organisation needs a demo base domain. Without either, use the port-forward command on the detail page. |
| An environment variable did not reach the container | Per-launch values win by name over the application defaults, and an empty value is still a value. Confirm the final set on the demo's detail page bill of materials. |

***

## Related

* [Preview demos](/concepts/applications#preview-demos) - the concept, the namespace model, and the isolation guarantees
* [PR preview environments](/guides/pr-preview-environments) - the automatic per-pull-request flow and its status comment
* [Environment variables and a throwaway database](/concepts/applications#environment-variables-and-a-throwaway-database) - the defaults layer shared by every demo surface
* [Ship Your App](/guides/deliver-your-app) - the routes from a repository to a running application, and which builder publishes which tags


# Application CI/CD
Source: https://docs.ankra.ai/guides/cicd-pipeline

Two ways to build and publish an application's image - Ankra Pipelines in your own cluster, or the generated GitHub Actions workflow that publishes to your private Ankra registry.

Ankra Applications get their container images built, scanned and published in one of two ways. [Ankra Pipelines](/guides/ankra-pipelines) runs the pipeline as hardened Jobs inside a cluster you already operate through Ankra, from one committed file, `.ankra/pipeline.yaml`; it is the primary path, a new application's setup pull request commits `.ankra/pipeline.yaml` by default, and the guide says exactly which pieces are in place today. The generated GitHub Actions workflow below is for a repository that must keep building on GitHub, and for applications set up before the pipeline became the default. To pick between these and your own CI, see [Ship Your App](/guides/deliver-your-app).

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> CI in your cluster: triggers, a Job per stage, check runs, artifacts, and what a pull request can and cannot change.

> [card] [Migrate from GitHub Actions](/guides/migrate-from-github-actions)
>
> Convert a workflow, GitLab CI file, Bitbucket pipeline or CircleCI config and review the notes.

## Bring your own CI (GitHub Actions)

Ankra Applications generates a GitHub Actions pipeline that builds your source repository, scans the image, and publishes it to your organisation's private registry. The generated Kubernetes manifests already reference that image and the matching pull secret. Nothing about it changes when you add an Ankra pipeline to the same repository: the workflow's checks keep their names, the pipeline's is `Ankra pipeline`, and Ankra keeps reading the workflow's results for publish readiness, push-to-deploy and previews.

> [!NOTE]
>
> The Ankra registry is private. Ankra provisions its project, GitHub Actions credentials, and Kubernetes pull credentials automatically.

### How it works

```mermaid theme={null}
flowchart LR
    Repo[Application repository] -->|connect| Ankra
    Ankra -->|open setup PR| PR[Setup pull request]
    PR -->|merge| Actions[GitHub Actions]
    Actions -->|build and scan| Image[Container image]
    Image -->|push| Registry[Private Ankra registry]
    Registry -->|pull| Cluster[Kubernetes cluster]
```

**1. Connect the repository**

Create an Application from a GitHub repository. Ankra analyses the source and prepares the missing Dockerfile, Kubernetes manifests, and workflow.

**2. Review the setup pull request**

The pull request adds `.github/workflows/build-and-publish.yml` and manifests under `.ankra/manifests/`. Monorepos get one scoped workflow per application.

**3. Merge and build**

Merging the pull request runs the workflow. It tests the source, builds the image, scans it with Trivy, and only then pushes it to your organisation's project on `registry.ankra.cloud`.

**4. Pull requests build but do not publish**

The workflow also runs on `pull_request`, where it tests, scans the source, builds the image and scans it with Trivy, but skips the push - so an unmerged branch never puts artifacts in your registry. Because nothing is pushed, a pull request gets no image a [PR preview](/guides/pr-preview-environments#applications-built-by-github-actions) could deploy.

**5. Deploy**

Deploy the Application to a cluster. Ankra checks that an image was published before starting the deployment.

## Registry authentication

Ankra installs these encrypted GitHub Actions secrets on the application repository:

| Secret | Purpose |
| - | - |
| `ANKRA_REGISTRY_USERNAME` | Username of the application's own push robot on the organisation registry project (`robot$<project>+app-<application-id>`) |
| `ANKRA_REGISTRY_PASSWORD` | That robot's secret |

The robot is minted per application when the application is set up, so no two applications share a registry login. Rotate or revoke it from the application's **Settings** → **Image registry**, or with `ankra application registry robot rotate|revoke` - see [Robot accounts](/concepts/applications#robot-accounts).

The generated workflow uses the secrets with `docker/login-action`. It does not use `GITHUB_TOKEN` package permissions and does not publish a public package.

For Kubernetes pulls, Ankra creates an `ankra-registry-pull` Docker registry secret in each managed namespace. Generated Deployments include:

```yaml theme={null}
spec:
  template:
    spec:
      imagePullSecrets:
        - name: ankra-registry-pull
```

The same pull credential is injected into short-lived Application preview environments.

### Your own registry

An Application that [declares its own registry](/concepts/applications#using-your-own-registry) publishes there instead. The workflow logs in with the secret names the declaration gives (defaulting to the `ANKRA_REGISTRY_*` pair), the generated Deployments reference the pull Secret it names, and Ankra creates that Secret in the deploy namespace from the registry credential the declaration names.

Ankra does not write the login secrets for a registry you operate unless you hand it robot management there: the robots are yours to administer, and overwriting a push robot with the credential Ankra holds would deny every later build. Publish readiness reports whether the named secrets exist. Name an `admin_credential_name` on the declaration to have Ankra mint a push robot for the application on your registry and write that into the secrets, or opt in with `manage_actions_secrets: true` to have it write the declared credential.

## Image retention

The Ankra registry does not keep every image forever. Each organisation project carries a retention policy that Harbor runs once a day: an artifact is kept while it was pushed within the last **30 days**, and the **three most recently pushed tagged versions** of every repository are kept whatever their age - so a component nobody has built in months still holds its last three releases. Everything else goes: older tagged images beyond the last three, and the untagged leftovers of overwritten tags once they are 30 days old. Harbor's garbage collection reclaims the storage afterwards.

Two consequences worth planning for:

* A rollback can only reach a version that is still in the registry - one of the last three, or one pushed in the last 30 days.
* A workload still running an image older than that keeps running, because the image is cached on its node, but it cannot be rescheduled onto a fresh node once the image is gone. Redeploy long-lived workloads from a recent build.

A registry you operate yourself is never touched: retention there is yours to configure.

## Existing applications

Reconcile an Application after the registry cutover. Ankra updates its image URL, replaces a legacy build workflow or manifest with the private registry version, and restores missing repository secrets.

You can inspect readiness in the application's **Pipelines** section or from the CLI:

```bash theme={null}
ankra application publish-readiness <application-id>
```

Readiness checks the organisation registry project, both repository secrets, the workflow login target, and whether an image has been published.

## Converting an existing workflow

Ankra converts a GitHub Actions workflow, a GitLab CI file, a Bitbucket Pipelines file or a CircleCI config into `.ankra/pipeline.yaml`. Ask Ankra AI in the portal chat or through the MCP server: `cicd_convert_workflow_to_pipeline` answers with the pipeline, a note for everything it could not map one to one, and a validation verdict; `cicd_validate_pipeline_yaml` checks a definition you wrote or edited. Steps that only installed cloud credentials or a registry login are dropped with a note, because the pipeline gets those from Ankra, and a third-party step the mapping table does not know becomes a stage that fails until you replace it.

For an application already connected to Ankra, `GET`/`POST .../pipeline` and `.../pipeline/migrate` do this in one call instead: read what builds it today, convert, and open the pull request - see [Migrate an existing application with one call](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call). The disposition itself only switches once that pull request merges, and a later push that adds or removes `.ankra/pipeline.yaml` or a workflow file on the default branch re-evaluates it automatically on GitHub.

The [migration guide](/guides/migrate-from-github-actions) carries the full mapping table, what each source format loses, what to review afterwards, and how to run both side by side until you trust the pipeline. The [pipeline.yaml reference](/guides/pipeline-reference) documents every key.

## Troubleshooting

> [accordion] The workflow cannot log in
>
> Open the application's **Pipelines** section. If Ankra cannot restore the repository secrets, approve the updated Ankra GitHub App **Secrets** permission and retry the fix.

> [accordion] The registry project is not ready
>
> Registry projects are provisioned automatically. The background reconciler retries missed provisioning. If readiness remains blocked after a few minutes, contact support.

> [accordion] The image push is denied
>
> Confirm that the workflow logs in to the host shown in the Application image URL and uses `ANKRA_REGISTRY_USERNAME` and `ANKRA_REGISTRY_PASSWORD`. Reconcile the Application to replace a legacy workflow.

> [accordion] Pods report ImagePullBackOff
>
> Reconcile the Application and check the target namespace for `ankra-registry-pull`. Ankra rotates and reapplies pull credentials automatically.

> [accordion] Deploy is blocked
>
> Ankra blocks deployment until it can verify a published image in the organisation registry. Check the latest GitHub Actions run, then retry after the image push succeeds.

## Next steps

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> Run the same lifecycle inside your own cluster.

> [card] [Applications](/concepts/applications)
>
> Connect a repository and follow the Application lifecycle.

> [card] [GitHub integration](/integrations/github)
>
> Review the GitHub App permissions used by Ankra.

> [card] [Pipeline Agents](/guides/pipeline-agents)
>
> Add read-only deployment and health reporting to your CI workflows.

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt other secrets stored in GitOps.


# From Claude Design to a live application
Source: https://docs.ankra.ai/guides/claude-design-to-ankra

Export a canvas from Claude Design, import it into Ankra, and get a repository, a setup pull request, a build and a public URL without writing a Dockerfile.

A design you made in [Claude Design](https://claude.ai/design) can be a running application on one of your clusters in a few minutes. Ankra takes the export, turns the artboards into a static site, creates a GitHub repository for it, commits the site with a Dockerfile, and registers it as an [application](/concepts/applications) - from there it is the same setup pull request, build and deploy flow every application goes through.

> [!NOTE]
>
> Applications connect to **GitHub** through a [GitHub credential](/integrations/github). The import creates the repository under that credential's account (or an owner you name), so the credential needs the Ankra GitHub App installed there.

## What the import does

```mermaid theme={null}
flowchart LR
    Export[Claude Design export] -->|import| Ankra[Ankra]
    Ankra -->|create + commit| Repo[GitHub repository]
    Repo -->|register| App[Application]
    App -->|"analyze + generate (PR)"| PR[Setup pull request]
    PR -->|merge| Build[Build]
    Build -->|deploy| Cluster[Live on a cluster]
```

Every artboard (`<Name>.dc.html`) becomes a page under `site/` in the repository: `Main.dc.html` is `index.html`, the rest take their name (`Pricing.dc.html` becomes `pricing.html`), and a canvas with several artboards gets a `canvas.html` front door listing them by their canvas titles and pages. Images travel along under `site/assets/`. The Dockerfile serves the site with busybox `httpd` on port 8080 as a non-root user, which is what the generated Kubernetes manifests expect. A `.ankra/design-import.json` file records what was imported, so running the same import again registers the same repository without a second commit.

## 1. Export the design

In Claude Design, export the canvas. Any of these shapes work:

* a folder holding the artboards (`Main.dc.html`, `Pricing.dc.html`, …), `canvas.json` and any images;
* a zip of that folder;
* a single artboard file;
* a saved canvas page (`.html`) - the page Claude Design publishes, which carries the artboards inside it.

Files over 2 MiB and exports over 16 MiB are refused; those are the editor's own limits, so an export that came out of it fits.

## 2. Import it

> [tab] CLI
>
> ```bash theme={null}
> ankra application import claude-design ./my-design-export --name my-site
> ```
>
> With one GitHub credential in the organisation the command picks it and creates the repository under that credential's account. Name them yourself when there is a choice:
>
> ```bash theme={null}
> ankra application import claude-design my-design-export.zip \
>   --credential my-github --owner my-org --repository my-site \
>   --source-url https://claude.ai/design/p/<project-id> --wait
> ```
>
> `--wait` follows the analysis and prints the setup pull request when it opens. `-o json` returns the application id, the repository, the pages and any warnings as one document.

> [tab] Portal
>
> Open **Applications → Add application** and choose **Claude Design** as the source. Drop the export files (or the zip, or the saved page) onto the form, name the application, pick the GitHub credential and the owner, and import. The application page opens with the repository link and the setup pull request once analysis has run.

> [tab] API
>
> ```bash theme={null}
> curl -X POST "$ANKRA_API/api/v1/org/applications/imports/claude-design" \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-site",
>     "app_repo_credential_name": "my-github",
>     "app_repo_owner": "my-org",
>     "files": [
>       {"path": "Main.dc.html", "content_base64": "..."},
>       {"path": "canvas.json",  "content_base64": "..."}
>     ]
>   }'
> ```
>
> The answer has the create route's `id` and `errors`, plus `repository`, `pages` and `warnings`. A refusal you can act on - a repository name that is taken, a file the importer does not recognise - comes back in `errors` with a 200; see the [API reference](/api-reference/applications/import-a-claude-design-application).

## 3. Merge, build, deploy

From here the application is an ordinary one. Ankra opens the setup pull request with the manifests, chart and build workflow (it keeps the committed Dockerfile), the merge builds and publishes the image, and you deploy it to a cluster:

```bash theme={null}
ankra application get <application-id>
ankra application deploy <application-id> --cluster <cluster>
```

The [applications concept](/concepts/applications) walks through the setup pull request, secrets and deployment in full.

## Artboards that use template logic

An artboard is served as it was authored. Artboards that only use markup and styles look exactly as they did on the canvas. Artboards that depend on the Claude Design runtime - `{{ }}` holes, `sc-for` or `sc-if` blocks, `dc-import` components, or a `data-dc-script` logic block - are imported too, but the import reports each of them as a warning: without the runtime they may not render as they did in the editor. Replace the logic with plain markup in Claude Design and import again, or edit the page under `site/` in the repository; every push builds and deploys.

## Importing again

The repository keeps `.ankra/design-import.json`, a record of the files the import was built from. Running the import again with the same export finds that record and registers without committing; running it with a changed export is refused for now - import into a new repository name, or edit the pages in the repository directly.

## Related

* [Applications](/concepts/applications)
* [Ankra Pipelines](/guides/ankra-pipelines)
* [Branch demos](/guides/branch-demos)


# Clone a Cluster
Source: https://docs.ankra.ai/guides/clone-cluster

Duplicate a cluster with the CLI or the portal, onto an import cluster or a different cloud provider.

> [!NOTE]
>
> Clone stack configurations from existing clusters or remote repositories. Perfect for replicating production setups to staging or dev environments.

***

## Prerequisites

* [Ankra CLI](/integrations/ankra-cli) installed and configured
* A cluster configuration file (YAML)

***

## Clone from a Local File

Copy stacks from an existing cluster configuration:

```bash theme={null}
ankra cluster clone existing-cluster.yaml new-cluster.yaml
```

***

## Clone from GitHub

Pull configurations directly from a repository:

```bash theme={null}
ankra cluster clone https://github.com/user/repo/raw/main/cluster.yaml my-cluster.yaml
```

***

## Clone Options

| Flag | Description |
| - | - |
| `--clean` | Replace all stacks in target (clean copy) |
| `--force` | Override conflicts during merge |
| `--copy-missing` | Copy missing files even from skipped stacks |
| `--stack` | Clone only specific stacks by name (repeatable) |

**Examples:**

```bash theme={null}
# Clean copy - replace all stacks in target
ankra cluster clone source.yaml target.yaml --clean

# Force merge - override conflicts
ankra cluster clone source.yaml target.yaml --force

# Clone only specific stacks
ankra cluster clone source.yaml target.yaml --stack "monitoring" --stack "networking"

# Complete replacement with all files
ankra cluster clone source.yaml target.yaml --clean --force --copy-missing
```

***

## Example Workflow

**1. Clone from GitHub**

```bash theme={null}
ankra cluster clone https://github.com/ankraio/ankra-gitops-examples/raw/main/clusters/monitoring-stack/cluster.yaml ./my-cluster.yaml
```

**2. Apply the Configuration**

```bash theme={null}
ankra cluster apply -f my-cluster.yaml
```

**3. Customize Values**

Edit the YAML file or use the UI to adjust values for your environment (resource limits, domains, replicas).

***

## Clone via UI

You can clone stacks directly in the Ankra UI:

**Clone a single stack:**

1. Navigate to **Stacks** in your cluster
2. Click the menu on any stack card
3. Select **Clone to Cluster**
4. Choose a target cluster and click **Clone Stack**

**Clone multiple stacks at once:**

1. Navigate to **Stacks** in your cluster
2. Click the **Clone Stacks** button next to the search bar (or click a stack card's avatar to start selecting)
3. Select the stacks you want to clone - a floating action bar shows the count
4. Click **Clone to Cluster**, choose a target cluster, and confirm
5. All selected stacks are cloned as drafts to the target cluster

> [!TIP]
>
> For a full guide on multi-stack cloning, see [Clone Stacks Between Clusters](/guides/clone-stack#clone-multiple-stacks-at-once).

### Clone a whole cluster

**Clone Cluster** in a cluster's menu copies every stack of that cluster onto a new one and, with **Deploy after cloning** left on, deploys them there straight away. The dialog asks where the clone should run:

* **Import an existing cluster** - Ankra creates an import cluster and prints the command that connects it. Pick this when the clone should land on Kubernetes you already run.
* **Build on a cloud provider** - Ankra provisions a new cluster on Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Proxmox VE or HPE Morpheus and copies the stacks onto it. Choose the provider and click **Continue**; the provider's create page opens with a *Cloning from* notice, where you pick the credential, region, node sizes and the usual create options. **Create Cluster** there builds the cluster and clones the stacks in one request. This is the path for moving a workload between clouds.

A cloud-provider clone skips the stacks the provider's own provisioning installs - the cloud controller (`hcloud`, `openstack`, `upcloud-cloud-provider`, `digitalocean-cloud-provider`, `scaleway-cloud-provider`), `networking`, `external-dns` and, on kubeadm targets, `cilium`. The new cluster gets the target provider's versions of those; the result lists them under `stacks_skipped` with a warning naming each one. Stacks whose values pin the old provider (a storage class, a load-balancer annotation, a node selector) still clone, so review each draft before deploying.

> [!TIP]
>
> The same request is available to automation: `POST /org/clusters/imported/{cluster_id}/clone` with `target_provider` and a `target` object carrying that provider's create body (the fields of `POST /org/clusters/{provider}`), and `deploy_after_clone: true` to deploy the clones. The response carries `target_provider`, `stacks_skipped`, `stacks_deployed` and `stacks_held` alongside the cloned and failed stacks; each cloned stack reports its `needs_input`.

### Stacks that need your input

A clone never carries secrets: every value a member's `encrypted_paths` seal is replaced by the `ENCRYPTED_VALUE_REMOVED` placeholder on the target. A stack that still holds that placeholder cannot come up healthy, so the clone does not deploy it. It is kept as a draft and marked **Needs input** in the stack list, with the members and values to re-enter listed on the chip and in the clone result. Open the draft: the builder shows the same list as a banner, each entry opens the add-on or manifest that holds the field, and once every placeholder is replaced the banner disappears and **Create Stack** deploys it. Everything else deploys on its own; addons that had no stored configuration deploy with chart defaults and are named in the warnings.

### What a cluster clone carries

Beyond the stacks, a cluster clone also copies the source cluster's **cluster variables**, so stack content keeps resolving its `${{ ankra.* }}` tokens. Everything else that is cluster-scoped cannot be cloned and is named in the result's warnings instead: a deployed **SOPS key**, **registry pull secrets**, the **Git repository connection**, and **Prometheus or log source** connections. Reconnect those on the new cluster before deploying stacks that need them.

***

## Next Steps

> [card] [Ankra CLI Reference](/integrations/ankra-cli)
>
> Full CLI command reference.

> [card] [GitOps Examples](https://github.com/ankraio/ankra-gitops-examples)
>
> Example cluster configurations to clone.


# Clone Stacks Between Clusters & Organisations
Source: https://docs.ankra.ai/guides/clone-stack

Learn how to clone one or multiple stacks from one cluster to another - including across organisations - for consistent deployments across environments

> [!NOTE]
>
> Cloning stacks allows you to replicate your infrastructure configurations across multiple clusters - even across different organisations. You can clone a single stack or select multiple stacks at once. With **Deploy on the target after cloning** left on, a cloned stack deploys on the target straight away; turn it off to keep the clone as a draft for review first. A stack whose encrypted values had to be removed is always held as a draft, marked **Needs input**, until you re-enter them.

<video />

Cloning a Stack Between Clusters

> [card] [AI Prompts](#ai-prompts)
>
> Use these prompts with the AI Assistant (`Cmd+J`) to clone stacks with natural language.

***

## Overview

Stack cloning is useful when you want to:

| Use Case | Example |
| - | - |
| **Promote configurations** | Clone a tested stack from staging to production |
| **Standardize environments** | Replicate your monitoring stack across all clusters |
| **Create templates** | Use a well-configured stack as a starting point for new clusters |
| **Keep a standby ready** | Run the same configuration on a second cluster, ready to take over |
| **Cross-org sharing** | Clone a stack from a development org to a client or production org |
| **Replicate entire clusters** | Select all stacks and clone them to a new cluster in one operation |

> [!WARNING]
>
> **By default a clone copies configuration only, and it reads the live source.** A clone reproduces the stack's definition on the target; persistent volumes and database contents stay where they are unless you add them with the **Data** step in the dialog or `--with-data` on the CLI. Cloning with data needs a [backup vault](/guides/backups). It also needs the source cluster to be readable, so it is not a disaster-recovery mechanism - for that, protect the stack and restore a [restore point](/guides/backups).

> [!WARNING]
>
> **Security Note:** Encrypted values (secrets) are not transferred during cloning for security reasons. You'll need to reconfigure them in the target cluster. This includes passwords, API keys, and any values encrypted with SOPS. A stripped Secret is still a valid Kubernetes object - each cleared key holds the `ENCRYPTED_VALUE_REMOVED` placeholder (base64-encoded under `data`) so the draft deploys and the workload fails clearly on the placeholder rather than the apply failing on the manifest.

***

## Prerequisites

* At least two clusters imported into Ankra (can be in different organisations)
* A deployed stack in the source cluster that you want to clone
* Access to both the source and target clusters
* For cross-org cloning: membership in both the source and target organisations

***

## Clone Using the Dashboard

**1. Navigate to Source Stack**

Go to your source cluster and navigate to **Stacks**. Find the stack you want to clone.

**2. Open Clone Dialog**

Click the menu icon (three dots) on the stack card and select **Clone to Cluster**.

**3. Target**

On the **Target** step:

1. If you belong to multiple organisations, select the **target organisation**. The cluster list updates to show clusters in that organisation.
2. Choose the **destination cluster**.
3. Optionally change the **Stack name**.

If your stack contains encrypted values, a warning says they do not travel. For a **cross-organisation** clone, a banner says you are taken to the target organisation once the copy is made.

**4. Data (optional)**

A **Data** step lets you carry the stack's volumes and database contents as well, through a [backup vault](/guides/backups).

**5. Review**

Check the summary. **Include addon configurations** copies the Helm values and settings of every add-on. **Deploy on the target after cloning** is on by default; turn it off to keep the clone as a draft.

**6. Clone the Stack**

Click **Clone stack**. A deployed clone takes you to the running stack on the target; a clone that needs input opens its draft in the builder, with a banner naming the values to re-enter. If you cloned to a different organisation, Ankra automatically switches your active organisation.

**7. Finish on the target**

If the clone was held as a draft (you turned deploy off, or encrypted values had to be removed), add any missing secrets, adjust cluster-specific settings, and deploy it from the builder.

***

## Clone Multiple Stacks at Once

You can select multiple stacks and clone them all to another cluster in a single operation. Each stack is created as a separate draft on the target cluster.

**1. Select Stacks**

On the **Stacks** page, click any stack card's avatar (the colored circle) to start selecting. Click additional avatars to add more stacks to your selection.

Alternatively, click the **Clone Stacks** button to the left of the search bar - this selects all stacks on the page.

**2. Open the Clone Dialog**

With stacks selected, a floating action bar appears at the bottom of the screen showing the count. Click **Clone to Cluster** in the bar, or click the **Clone N Stacks** button next to the search bar.

**3. Choose a Target**

In the dialog:

1. Select the **target organisation** (if you belong to multiple)
2. Choose the **destination cluster**
3. Toggle whether to include addon configurations

The dialog shows a list of all selected stacks as tags.

**4. Clone**

Click **Clone N Stacks**. Each stack is cloned sequentially - you'll see a progress bar and each stack tag turns green on success. Name conflicts are auto-resolved with suffixes (e.g. `-copy`).

**5. Navigate to Target**

The summary says how many stacks are deploying and how many were held for your input, with a link into each held draft's builder tab. Click **Go to Target Cluster** to watch them come up.

> [!TIP]
>
> Multi-stack cloning is useful for replicating an entire cluster's configuration. Select all stacks and clone to a new cluster; the ones without secrets deploy on their own, and the **Needs input** chip on the stack list shows which are waiting for you.

***

## Clone Using the CLI

The Ankra CLI provides a `clone` command for scripting and automation.

### Basic Usage

```bash theme={null}
# Select the source cluster first
ankra cluster select my-source-cluster

# Clone a stack to another cluster
ankra cluster stacks clone monitoring-stack --to production-cluster
```

### Command Options

| Flag | Short | Description |
| - | - | - |
| `--to` | `-t` | Target cluster name or ID (required) |
| `--name` | `-n` | Custom name for the cloned stack |
| `--include-config` | | Include addon configurations (default: true) |
| `--deploy` | | Deploy the clone on the target (default: false, so the CLI creates a draft) |
| `--with-data` | | Carry the stack's data through a restore point (needs a [backup vault](/guides/backups)) |

This table covers the common flags. `--deploy`, `--with-data` and the data flags need CLI v0.18.0 or later; see the [CLI reference](/reference/cli/cluster#ankra-cluster-stacks-clone) for `--from`, `--vault`, `--wait` and the rest.

> [!NOTE]
>
> The CLI and the dashboard have opposite defaults: the dashboard deploys the clone unless you turn **Deploy on the target after cloning** off, while `ankra cluster stacks clone` creates a draft unless you pass `--deploy`.

### Examples

**Clone with a custom name:**

```bash theme={null}
ankra cluster stacks clone my-stack --to production --name my-stack-prod
```

**Clone without addon configurations:**

```bash theme={null}
ankra cluster stacks clone my-stack --to production --include-config=false
```

**Clone using cluster IDs:**

```bash theme={null}
ankra cluster stacks clone monitoring-stack --to 550e8400-e29b-41d4-a716-446655440000
```

### CLI Output

```
Cloning stack 'monitoring-stack' to cluster 'production'...

Stack cloned successfully!
  Draft ID:    a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Stack Name:  monitoring-stack
  Addons:      3
  Manifests:   2
  Applications: 1

Warnings:
  - Addon 'grafana' had encrypted configuration that needs to be reconfigured.
  - Cluster variable 'db_host' was copied from the source cluster onto the cloned stack; review its value for the target cluster.
  - Manifest 'prometheus' pins scheduling to nodes labelled purpose=monitoring - make sure the target cluster has matching nodes.
  - Deploy check for addon 'grafana': registry 'bitnami' is not connected in this organisation.

The stack has been created as a draft. Open the Ankra dashboard to review and deploy.
```

***

## What Gets Cloned

| Component | Cloned | Notes |
| - | :-: | - |
| Stack name & description | Yes | Can be renamed during clone |
| Stack variables | Yes | Transferred as-is; cluster variables the content references are copied onto the stack (same organisation) |
| Manifests | Yes | YAML content (encrypted values cleared) |
| Addons | Yes | Chart references, versions, settings, job timeouts and AGENTS.md notes |
| Applications | Yes | Same organisation only - applications are organisation-scoped, so a cross-organisation clone drops them with a warning |
| Addon configurations | Optional | **Include addon configurations** in the dialog, or `--include-config` |
| Encrypted secrets | No | Must be reconfigured |
| Deployment state | By default | **Deploy on the target after cloning** (dashboard) or `--deploy` (CLI) deploys the clone; a stack whose secrets were removed is held as a draft |
| Resource positions | Yes | Canvas layout and deploy wave carry over |
| Dependencies | Yes | Parent relationships preserved by name and kind |

### Pre-checks in the warnings

The clone runs the checks a deploy would, and reports what it finds as warnings rather than refusing - a clone never fails on them:

* **Variables**: a `${{ ankra.* }}` token the target cannot resolve is named, and a same-organisation clone copies the source cluster's value onto the stack so the manifest does not deploy the literal token.
* **Node pinning**: manifests and applications whose `nodeSelector` targets labels the target may not have.
* **SOPS readiness**: encrypted paths that survived the strip, on a target with no deployed SOPS key.
* **Chart references**: registries not connected in the target organisation, and charts or versions the catalog does not know.

***

## Cloning Between Organisations

Ankra supports cloning stacks to clusters that belong to a different organisation. This is useful for sharing configurations with clients, replicating setups from a template org to a production org, or migrating workloads.

### How it works

1. You must be a **member of both** the source and target organisations.
2. In the clone dialog, an **Organisation** dropdown appears when you belong to more than one org. Select the target organisation to see its clusters.
3. Cross-organisation cloning is available from the dashboard only.
4. After a cross-org clone, the dashboard **switches your active organisation** to the target automatically.

### What to keep in mind

> [!WARNING]
>
> **Credentials and secrets don't transfer across organisations.** Each organisation has its own SOPS keys, registry credentials, and secrets. After a cross-org clone you must reconfigure:
>
> * Encrypted values in manifests and addon configs
> * Registry credentials if images are in private registries
> * Any organisation-specific variables referenced by the stack

> [!TIP]
>
> Organisation and cluster variables are scoped to their organisation, and no variable value crosses that boundary. A cross-organisation clone names every `${{ ankra.* }}` reference it could not resolve in its warnings - define those variables in the target organisation or on the target cluster before deploying.

***

## Handling Encrypted Values

When you clone a stack that contains encrypted values:

1. **Manifests:** Encrypted fields are replaced with the `ENCRYPTED_VALUE_REMOVED` placeholder
2. **Addon configurations:** Encrypted values are replaced with the same placeholder
3. **Held as a draft:** the stack is not deployed; the clone result, the **Needs input** chip on the stack card and a banner in the builder name each member and field to re-enter, and the banner links straight to it

> [accordion] Re-encrypting Secrets After Clone
>
> After cloning, you'll need to re-encrypt secrets for the target cluster:
>
> 1. Open the cloned draft in the target cluster
>
> 2. Navigate to each manifest or addon that had encrypted values
>
> 3. Enter the new secret values
>
> 4. List the keys under **Encrypted Keys (SOPS)** so they are sealed with the target organisation's key
>
> 5. Save and deploy
>
> > [!TIP]
> >
> > The SOPS key pair belongs to the organisation, not to a cluster. Clusters in the same organisation share it, so a value sealed for one can be decrypted by another. A clone into a different organisation cannot decrypt the source's values - this is by design for security.

> [accordion] Automating Secret Configuration
>
> For automated deployments, consider:
>
> * Using external secrets management (e.g., Vault, AWS Secrets Manager)
> * Storing secrets in environment-specific configuration
> * Using Kubernetes ExternalSecrets operator

***

## Common Workflows

> [accordion] Staging to Production Promotion
>
> ```bash theme={null}
> # Test in staging first
> ankra cluster select staging
> ankra cluster stacks list
>
> # Clone to production when ready
> ankra cluster stacks clone my-app-stack --to production
>
> # Switch to production and configure secrets
> ankra cluster select production
> # ... configure in dashboard
> ```

> [accordion] Standardizing Multiple Clusters
>
> Clone your standard monitoring stack to all clusters:
>
> ```bash theme={null}
> ankra cluster select template-cluster
>
> for cluster in dev staging production; do
>   ankra cluster stacks clone observability --to $cluster --name observability
>   echo "Cloned to $cluster"
> done
> ```

> [accordion] Creating a Backup Configuration
>
> ```bash theme={null}
> # Clone critical stacks to a DR cluster
> ankra cluster select primary
> ankra cluster stacks clone core-services --to dr-cluster
> ankra cluster stacks clone monitoring --to dr-cluster
> ankra cluster stacks clone ingress --to dr-cluster
> ```

> [accordion] Replicate All Stacks to a New Cluster
>
> In the dashboard:
>
> 1. Go to **Stacks** in your source cluster
> 2. Click the **Clone Stacks** button next to the search bar - all stacks are selected
> 3. Click **Clone to Cluster** in the floating action bar
> 4. Choose your target cluster and click **Clone**
> 5. All stacks are created as drafts on the target - review and deploy each one
>
> With the CLI:
>
> ```bash theme={null}
> ankra cluster select source-cluster
> ankra cluster stacks list   # note the stack names
>
> # Clone each stack to the new cluster
> for stack in monitoring ingress app-data; do
>   ankra cluster stacks clone "$stack" --to new-cluster
> done
> ```

> [accordion] Sharing a Stack with Another Organisation
>
> Clone a well-tested stack to a client or partner organisation from the dashboard: select the target organisation in the clone dialog's **Target** step. After cloning, Ankra switches you to the target organisation automatically, where the stack's secrets can be added.

***

## Troubleshooting

> [accordion] Clone Failed: Stack Not Found
>
> Ensure the source stack is deployed (not just a draft) and you have the correct stack name:
>
> ```bash theme={null}
> ankra cluster stacks list
> ```

> [accordion] Clone Failed: Access Denied
>
> Verify you have access to both the source and target clusters. You must be a member of both clusters' organizations.

> [accordion] Clone Failed: Target Cluster Unavailable
>
> The clone operation only creates a draft in the database - it doesn't require the target cluster to be online. Check your network connection to the Ankra API.

> [accordion] Missing Resources After Clone
>
> If addons or manifests are missing:
>
> 1. Check if the source stack had resources in a `deleting` or `deleted` state
> 2. Verify the clone included addon configurations (`--include-config=true`)
> 3. Check the warnings for any resources that couldn't be cloned

***

## AI Prompts

Press `Cmd+J` to open the AI Assistant and use these prompts:

> [accordion] Clone Stack
>
> ```
> Clone the monitoring stack to my production cluster
> ```

> [accordion] Duplicate and Modify
>
> ```
> Clone the ingress stack from staging to production and rename it to prod-ingress
> ```

> [accordion] Replicate to Multiple Clusters
>
> ```
> Help me clone my observability stack to all my clusters
> ```

***

## Next Steps

> [card] [SOPS Encryption](/guides/sops)
>
> Learn how to encrypt secrets in your stacks.

> [card] [GitOps Sync](/concepts/gitops)
>
> Sync your stack configurations to a Git repository.

> [card] [Ankra CLI](/integrations/ankra-cli)
>
> Learn more CLI commands for stack management.


# Build a Cloudflare Stack
Source: https://docs.ankra.ai/guides/cloudflare-tunnel

Use Cloudflare Tunnel to securely expose Kubernetes services without opening firewall ports

> [!NOTE]
>
> Cloudflare Tunnel lets you expose services running in your cluster to the internet without configuring public IPs, opening firewall ports, or managing TLS certificates.

> [card] [AI Prompts](#ai-prompts)
>
> Use the AI Assistant (`⌘+J`) for guidance on building your Cloudflare Tunnel stack.

***

## Why Cloudflare Tunnel?

| Traditional Ingress | Cloudflare Tunnel |
| - | - |
| Requires public IP or LoadBalancer | Works behind NAT, no public IP needed |
| Open firewall ports (80, 443) | No inbound ports required |
| Manage TLS certificates yourself | Automatic TLS from Cloudflare |
| DDoS protection costs extra | DDoS protection included |
| Complex DNS configuration | Automatic DNS via Cloudflare |

Cloudflare Tunnel is ideal for:

* Clusters running on-premises or in private networks
* Development and staging environments
* Services that need Cloudflare's security features
* Teams that want zero-trust access controls

***

## Prerequisites

Before you start:

* A Cloudflare account with a domain added
* A cluster imported into Ankra with the agent connected
* The service you want to expose running in your cluster

***

## Step 1: Create a Cloudflare Tunnel

**1. Log into Cloudflare Dashboard**

Go to [dash.cloudflare.com](https://dash.cloudflare.com) and select your account.

**2. Navigate to Zero Trust**

Click **Zero Trust** in the sidebar, then **Networks** → **Tunnels**.

**3. Create a Tunnel**

Click **Create a tunnel** and select **Cloudflared** as the connector type.

**4. Name Your Tunnel**

Give it a descriptive name like `my-cluster-tunnel` or `prod-services`.

**5. Copy the Tunnel Token**

Cloudflare will show you a token. Copy it - you'll need this for the Kubernetes deployment.
The token looks like: `eyJhIjoiNjM...`

**6. Skip the Connector Setup**

Don't install the connector yet. We'll deploy it via Ankra instead. Click **Next**.

**7. Configure Public Hostname**

Add a public hostname for your service:

* **Subdomain**: e.g., `app` or `api`
* **Domain**: Select your Cloudflare domain
* **Service**: `http://your-service.namespace.svc.cluster.local:port`
  You can add more hostnames later.

**8. Save the Tunnel**

Click **Save tunnel**. The tunnel will show as "Inactive" until we deploy the connector.

***

## Step 2: Create the Stack in Ankra

**1. Open Stack Builder**

Navigate to your cluster → **Stacks** → **Create Stack**.

**2. Name Your Stack**

Name it `cloudflare-tunnel` or similar.

**3. Add a Secret Manifest**

Click **+ Add** → **Manifest** and create a Secret for the tunnel token:

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-tunnel-token
  namespace: cloudflare
type: Opaque
stringData:
  token: "YOUR_TUNNEL_TOKEN_HERE"
```

Replace `YOUR_TUNNEL_TOKEN_HERE` with the token from Cloudflare.

> [!TIP]
>
> **Encrypt your token with SOPS**: If you have [SOPS encryption](/guides/sops) enabled, add `token` to the **Encrypted Keys** section in the manifest editor. Your token will be encrypted before being pushed to Git and automatically decrypted during deployment.

**4. Add a Namespace Manifest**

Click **+ Add** → **Manifest** for the namespace:

```yaml theme={null}
apiVersion: v1
kind: Namespace
metadata:
  name: cloudflare
```

**5. Add the Cloudflared Deployment**

Click **+ Add** → **Manifest** for the tunnel connector:

```yaml theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cloudflared
  namespace: cloudflare
spec:
  replicas: 2
  selector:
    matchLabels:
      app: cloudflared
  template:
    metadata:
      labels:
        app: cloudflared
    spec:
      containers:
        - name: cloudflared
          image: cloudflare/cloudflared:latest
          args:
            - tunnel
            - --no-autoupdate
            - run
            - --token
            - $(TUNNEL_TOKEN)
          env:
            - name: TUNNEL_TOKEN
              valueFrom:
                secretKeyRef:
                  name: cloudflare-tunnel-token
                  key: token
          resources:
            requests:
              memory: 64Mi
              cpu: 10m
            limits:
              memory: 128Mi
              cpu: 100m
          livenessProbe:
            httpGet:
              path: /ready
              port: 2000
            initialDelaySeconds: 10
            periodSeconds: 10
```

**6. Connect Dependencies**

In the Stack Builder canvas, connect:

```
Namespace → Secret → Deployment
```

This ensures resources deploy in the correct order.

***

## Step 3: Deploy and Verify

**1. Save and Deploy**

Click **Save**, then **Deploy**. Watch the deployment in **Operations**.

**2. Check Cloudflare Dashboard**

Go back to the Cloudflare Zero Trust dashboard. Your tunnel should now show as **Healthy**.

**3. Test Your Service**

Navigate to your configured hostname (e.g., `https://app.yourdomain.com`). Your service should be accessible.

***

## Configuring Routes

You configure which services are exposed in the Cloudflare dashboard, not in Kubernetes.

### Adding a New Route

1. Go to **Zero Trust** → **Networks** → **Tunnels**
2. Click your tunnel → **Configure**
3. Go to **Public Hostname** tab
4. Click **Add a public hostname**
5. Configure:
   * **Subdomain**: The subdomain to use
   * **Domain**: Your Cloudflare domain
   * **Service**: The internal Kubernetes service URL

### Service URL Format

For Kubernetes services, use this format:

```
http://SERVICE_NAME.NAMESPACE.svc.cluster.local:PORT
```

Examples:

* `http://nginx.default.svc.cluster.local:80`
* `http://api-server.backend.svc.cluster.local:3000`
* `http://grafana.monitoring.svc.cluster.local:3000`

***

## Multiple Services

One tunnel can expose multiple services. Add multiple public hostnames in Cloudflare:

| Hostname | Service |
| - | - |
| `app.example.com` | `http://frontend.default.svc.cluster.local:80` |
| `api.example.com` | `http://backend.default.svc.cluster.local:3000` |
| `grafana.example.com` | `http://grafana.monitoring.svc.cluster.local:3000` |

***

## High Availability

The example deployment runs 2 replicas for redundancy. For production:

```yaml theme={null}
spec:
  replicas: 3
  template:
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: cloudflared
                topologyKey: kubernetes.io/hostname
```

This spreads replicas across different nodes.

***

## Encrypting Secrets with SOPS

If you're using GitOps to store your Stack configuration, you should encrypt the tunnel token with SOPS to avoid committing secrets in plaintext.

### Enable SOPS Encryption

**1. Initialize SOPS at Organisation Level**

Go to **Organisation Settings** → **Encryption** and click **Initialize Encryption**. This generates an AGE key pair for your organisation.

**2. Enable SOPS on Your Cluster**

Navigate to your cluster → **Settings** → **Encryption** and toggle on **Enable SOPS Decryption**. On the ArgoCD engine this deploys the decryption key to ArgoCD; on the native engine the agent decrypts on its own.

**3. Mark the Token for Encryption**

When editing the Secret manifest in the Stack Builder, expand the **Encrypted Keys (SOPS)** section and add `token` as an encrypted key.

### How It Works

1. When Ankra writes the Stack to your Git repository, it seals the `token` field with your organisation's AGE public key
2. The sealed manifest is what your Git repository stores (if GitOps is enabled)
3. When the Stack deploys, the value is decrypted inside your cluster - by the agent on the native engine, or by ArgoCD's helm-secrets plugin on the ArgoCD engine
4. Your tunnel token never appears in plaintext in Git

### Example Encrypted Manifest

After encryption, the Secret looks like this in Git:

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: cloudflare-tunnel-token
  namespace: cloudflare
type: Opaque
stringData:
  token: ENC[AES256_GCM,data:...,iv:...,tag:...,type:str]
sops:
  age:
    - recipient: age1...
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        ...
        -----END AGE ENCRYPTED FILE-----
  encrypted_regex: ^(token)$
  version: 3.9.4
```

The `ENC[...]` value is the encrypted token. The `sops` metadata block contains the encryption parameters.

> [!NOTE]
>
> Learn more about SOPS encryption in the [SOPS Encryption guide](/guides/sops).

***

## Access Controls

Cloudflare Tunnel integrates with Cloudflare Access for zero-trust security:

1. Go to **Zero Trust** → **Access** → **Applications**
2. Click **Add an application**
3. Select **Self-hosted**
4. Configure the application URL (your tunnel hostname)
5. Add access policies (e.g., require SSO, specific emails, IP ranges)

This lets you protect internal services with identity-aware access without VPNs.

***

## Troubleshooting

> [accordion] Tunnel Shows as Inactive
>
> 1. Check the cloudflared pods are running:
>    ```bash theme={null}
>    kubectl get pods -n cloudflare
>    ```
> 2. Check the logs for errors:
>    ```bash theme={null}
>    kubectl logs -n cloudflare -l app=cloudflared
>    ```
> 3. Verify the token in the secret is correct

> [accordion] 502 Bad Gateway
>
> The tunnel is working but can't reach the backend service:
>
> 1. Verify the service URL in Cloudflare is correct
> 2. Check the service exists and has endpoints:
>    ```bash theme={null}
>    kubectl get svc,endpoints -n YOUR_NAMESPACE
>    ```
> 3. Test connectivity from cloudflared pod:
>    ```bash theme={null}
>    kubectl exec -n cloudflare -it deploy/cloudflared -- wget -qO- http://SERVICE.NAMESPACE.svc.cluster.local:PORT
>    ```

> [accordion] Connection Timeouts
>
> 1. Check if the service is responding slowly
> 2. Increase timeout in Cloudflare tunnel settings
> 3. Verify there are no NetworkPolicies blocking traffic

> [accordion] DNS Not Resolving
>
> 1. DNS propagation can take a few minutes
> 2. Verify the hostname is configured in the Cloudflare dashboard
> 3. Check that your domain's nameservers point to Cloudflare

***

## AI Prompts

Press `⌘+J` to open the AI Assistant and use these prompts:

> [accordion] Basic Cloudflare Tunnel Stack
>
> ```
> Create a stack to deploy Cloudflare Tunnel. I have a tunnel
> token ready. Deploy cloudflared with 2 replicas in a
> cloudflare namespace.
> ```

> [accordion] Expose an Existing Service
>
> ```
> I have a service called api-server in the default namespace
> on port 8080. Help me set up Cloudflare Tunnel to expose it.
> ```

> [accordion] Production Tunnel Setup
>
> ```
> Create a production-ready Cloudflare Tunnel deployment with:
> - 3 replicas spread across nodes
> - Resource limits
> - Health checks
> - Pod disruption budget
> ```

> [accordion] Troubleshoot Tunnel Issues
>
> ```
> My Cloudflare Tunnel shows as inactive in the dashboard.
> Help me troubleshoot why the cloudflared pods aren't
> connecting.
> ```

> [!TIP]
>
> The AI provides recommendations for your Stack. Just describe your tunnel setup and which services you want to expose, then build based on the guidance.

***

## Next Steps

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt secrets in your Stacks before pushing to Git.

> [card] [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/)
>
> Add zero-trust access controls to your services.

> [card] [Stack Builder](/concepts/stacks)
>
> Learn more about building and managing Stacks.

> [card] [GitOps Sync](/concepts/gitops)
>
> Store your tunnel configuration in Git.

> [card] [Monitoring Stack](/guides/monitoring-stack)
>
> Expose Grafana via Cloudflare Tunnel.


# Cluster Access
Source: https://docs.ankra.ai/guides/cluster-access

Grant teammates scoped, SSO-backed kubectl access to a cluster - without distributing static kubeconfigs or cluster credentials.

Cluster Access lets organisation admins grant teammates scoped Kubernetes access to a cluster. Instead of handing out long-lived kubeconfigs or shared service-account tokens, you create a **grant** that maps an Ankra user to a role and scope. Ankra reconciles that grant into native Kubernetes RBAC on the cluster, and the user reaches the cluster through Ankra's authenticated [kubeconfig and API proxy](/guides/kubeconfig).

> [!NOTE]
>
> Access is **SSO-backed and ephemeral**. Members authenticate as themselves (via `ankra login` or the portal), and the credentials their kubeconfig uses are short-lived tokens minted on demand - there are no static cluster secrets to leak or rotate.

***

## How it works

```mermaid theme={null}
flowchart LR
    Admin[Org admin] -->|"creates grant (user, role, scope)"| Platform[Ankra Platform]
    Platform -->|reconciles RBAC| Cluster[Your cluster]
    Member[Member] -->|"ankra login + kubeconfig"| Proxy[Ankra API proxy]
    Proxy -->|scoped requests| Cluster
```

1. An admin grants a member a role at a chosen scope.
2. Ankra reconciles the grant into Kubernetes RBAC (a `RoleBinding` or `ClusterRoleBinding`) on the cluster.
3. The member adds an Ankra context to their kubeconfig and runs `kubectl` - every request flows through the Ankra proxy and is bound by the RBAC the grant created.

***

## Roles and scopes

Each grant combines a **role** with a **scope**:

| Role | Bound to | Kubernetes capability |
| - | - | - |
| `view` | `ankra:view` | Read-only access |
| `edit` | `ankra:edit` | Read/write to most namespaced resources |
| `admin` | `ankra:admin` | Full control within the scope, including Roles and RoleBindings for permissions the grant itself holds |
| `cluster-admin` | `ankra:cluster-admin` | Full control of the cluster |

| Scope | Applies to |
| - | - |
| `cluster` | The whole cluster (cluster-wide binding) |
| `namespace` | A single namespace (the `namespace` field is required and must be a valid DNS-1123 label) |

> [!TIP]
>
> Grant the narrowest role and scope that gets the job done - for example `view` on a single `namespace` for someone triaging one team's workloads, rather than `cluster-admin`.

### No impersonation, escalation or bind

A grant binds to an Ankra-managed ClusterRole, never to the Kubernetes built-in one. Each `ankra:*` ClusterRole is derived from the built-in role of the same name with the `impersonate`, `escalate` and `bind` verbs removed. So no Ankra identity can act as another user, group or service account, and none can create a Role or binding that holds more than it already has. Even with `cluster-admin`:

```bash theme={null}
kubectl auth can-i impersonate serviceaccounts
# no
```

The gateway also strips any `Impersonate-*` headers a client sends, so `kubectl --as` and `--as-group` have no effect through Ankra.

### Secrets need their own permission

Reading or changing Kubernetes Secrets through Ankra also needs the `kubernetes.secrets_reveal` permission, whatever role the grant gives. Among the built-in organisation roles `owner`, `admin` and `operator` hold it; `member` and `viewer` do not. Without it, `kubectl get secret` and any other request for Secrets (a list, a watch, a create or an edit) returns `Forbidden` with a message naming the permission, and nothing is sent to the cluster. Every Secret request Ankra lets through is written to the [audit log](/guides/audit-log) with who made it, the cluster, the namespace and the name.

This is a check on the request, not on what a pod can do. A member whose grant lets them open a shell in a pod, or create a pod, can still read a Secret that pod mounts. To keep credentials away from someone, give them a `view` grant: the Kubernetes `view` role cannot read Secrets or open a shell in a pod, whatever their organisation role.

***

## Managing access

Open a cluster and go to its **Access** view. The page adapts to your role:

* **Admins** can list organisation members, view existing grants and their reconcile status, create new grants, and revoke them.
* **Members** see whether they have access and can generate a kubeconfig if they do.

> [!NOTE]
>
> A grant is required to mint tokens and reach the cluster **for every user, including organisation admins**. Being able to manage access does not itself include kubectl access - admins who want to use `kubectl` must create a grant for themselves too.
>
> The one exception is whoever created or imported the cluster. By default they are given a cluster-scoped `cluster-admin` grant at create time, so they can generate a kubeconfig straight away. An [organisation access policy](#organisation-access-policy) can change that role, or turn the creator grant off. It is an ordinary grant - it appears in the **Access** view and in `ankra cluster access list`, and it can be revoked like any other.

### Grant access

**1. Pick a member**

Choose an active organisation member by email. The target must already be a member of the organisation.

**2. Choose role and scope**

Select a role (`view`/`edit`/`admin`/`cluster-admin`) and a scope (whole `cluster` or a single `namespace`).

**3. Create the grant**

Ankra records the grant and begins reconciling it onto the cluster.

**4. Wait for the grant to apply**

The grant starts as `pending` while the RBAC is applied on the cluster. A token can be minted as soon as the grant exists, but `kubectl` returns `Forbidden` until the status reaches `applied` - check it in the **Access** view or with `ankra cluster access list`.

**5. Share the kubeconfig step**

The member adds an Ankra context to their kubeconfig - see [Accessing clusters with kubectl](/guides/kubeconfig). For a namespace-scoped grant, they should pass `--namespace` with the granted namespace.

### Reconcile status

Because RBAC is applied on the cluster by the agent, each grant carries a reconcile status:

| Status | Meaning |
| - | - |
| `pending` | The grant has been created and is waiting to be applied |
| `applied` | RBAC is live on the cluster |
| `failed` | Reconcile failed - see the grant's error detail |
| `cluster_offline` | The cluster is offline; the grant will apply once it reconnects |

### Revoke access

Delete an individual grant to remove that binding, or use **revoke all** to clear every grant and invalidate any tokens minted for the cluster in one action.

### From the CLI

Admins can manage grants from the [Ankra CLI](/reference/cli/cluster#ankra-cluster-access) (v0.4.0 or later) instead of the portal:

```bash theme={null}
# List grants and their reconcile status
ankra cluster access list --cluster my-cluster

# Grant a member access (cluster-wide view by default)
ankra cluster access grant user@example.com --role view

# Limit a grant to one namespace
ankra cluster access grant user@example.com --role edit --namespace staging

# Revoke a single grant by ID, or every grant a member has on the cluster
ankra cluster access revoke user@example.com
```

***

## Time-boxed grants

A grant can carry an expiry and a reason. Without an expiry it is a standing grant and lasts until someone revokes it.

* **Expiry.** Send `expires_in` as a duration such as `30m`, `4h` or `7d`, or `expires_at` as an RFC 3339 time.
* **Reason.** Send `reason`, 3 to 500 characters. It is stored with the grant and shown when grants are listed.
* **Re-timing.** Posting a grant that matches a live one (same member, role, scope and namespace) with a new expiry re-times the existing grant instead of adding a second one. Without an expiry, a matching request is refused with `409` as a duplicate.
* **Expiry is enforced.** The platform removes an expired grant from the cluster, and a kube token minted under a grant cannot outlive it, whenever the token was minted.

```bash CLI theme={null}
# Four hours of admin, with a reason
ankra cluster access grant user@example.com --cluster my-cluster --role admin --expires 4h --reason "maintenance window"

# List shows each grant's expiry (or "standing") and reason
ankra cluster access list --cluster my-cluster
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/<cluster-id>/access/grants \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"user_email": "user@example.com", "role": "admin", "scope": "cluster", "expires_in": "4h", "reason": "maintenance window"}'
```

`--expires` takes a duration or an RFC 3339 time and sends whichever field fits.

***

## Organisation access policy

An organisation access policy sets the limits every grant in the organisation is held to. It is opt-in: an organisation without a policy keeps the defaults, which are a `cluster-admin` grant for the cluster's creator, no ceiling and no bounds on expiry or reason.

| Field | Values | Effect |
| - | - | - |
| `creator_grant_role` | `none`, `view`, `edit`, `admin`, `cluster-admin` | What whoever creates or imports a cluster is given on it. `none` gives no grant. |
| `max_grant_role` | `view`, `edit`, `admin`, `cluster-admin` | The ceiling. No grant above it can be created, by anyone, admins included. |
| `elevated_max_ttl_seconds` | `60` to `31536000`, optional | Any grant above `view` must expire within this many seconds. |
| `require_reason_from_role` | `view`, `edit`, `admin`, `cluster-admin`, optional | Grants at or above this role need a reason. |

### Who can see and change it

* **Changing the policy** needs the `kube_access.policy` permission, held by owners and admins. It is human-only: an API token carries it only if the token's scopes name it explicitly, so an unscoped or `*` token is refused with `403 permission_denied (kube_access.policy)`. In practice a signed-in owner or admin changes the policy in the new Ankra interface: **Organisation settings → Roles**, section **Kubernetes access policy** (`/next/organisation/roles` on your portal's address).
* **Reading the policy** needs any of `kube_access.manage`, `kube_access.policy` or `kube_access.elevate`.

```bash CLI theme={null}
# Read the policy (there is no set command: changes are made signed in)
ankra org access-policy get
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/org/cluster-access-policy \
  -H "Authorization: Bearer <your-token>"
```

The policy is read and written at `GET` and `PUT /api/v1/org/cluster-access-policy`, and at `/org/cluster-access-policy` for a browser session. On a `PUT`, an omitted `elevated_max_ttl_seconds` or `require_reason_from_role` keeps its stored value, and `null` clears it.

### What happens to existing grants

Changing the policy does not change grants that already exist. A standing `cluster-admin` grant stays when the ceiling is lowered to `edit`, until it is revoked or expires.

The exception is Kubernetes access that comes from a custom [organisation role](/guides/roles-and-access#kubernetes-access-in-custom-roles). That access is always clamped to the ceiling, and it drops to the new ceiling within about a minute after the ceiling is lowered.

***

## Break-glass elevation

The `kube_access.elevate` permission lets its holder give **itself** time-boxed access to a cluster, and nothing else. It is meant for a person or an automation that should be able to step up during an incident without being able to hand out access.

An elevation:

* **Must expire** within the policy's `elevated_max_ttl_seconds`, or within 4 hours when the policy sets none.
* **Must carry a reason.**
* **Stays under the ceiling** set by `max_grant_role`.
* **Can be re-timed** by posting it again, which extends only the caller's own elevation.
* **Can be ended early** by the caller with `DELETE /api/v1/clusters/{cluster_id}/access/grants/{grant_id}`.

`kube_access.elevate` cannot grant anyone else, create a standing grant, extend or end someone else's grant, list grants, or change the policy. An admin who elevates is held to the same bounds.

### Elevate

`POST /api/v1/clusters/{cluster_id}/access/elevate` takes `role`, `scope` (default `cluster`), `namespace` for a namespace scope, `expires_in` or `expires_at`, and `reason`. The grantee is always the caller, so it works for a service account, which has no email. A body that names `user_email` is refused with `422`.

```bash CLI theme={null}
# Elevate yourself (or the service account the token belongs to)
ankra cluster access elevate --cluster my-cluster --role edit --expires 4h --reason "incident: restart the stuck rollout"

# End it early with the grant id elevate printed
ankra cluster access revoke <grant-id> --cluster my-cluster
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/<cluster-id>/access/elevate \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "edit", "expires_in": "4h", "reason": "incident: restart the stuck rollout"}'
```

`ankra cluster access elevate` requires `--expires` and `--reason`, and prints the id of the grant it created.

### Recommended setup for automation

For automation that needs break-glass access, such as an incident bot or an operator pod:

**1. Create a break-glass role**

Under **Organisation → Roles**, create a custom role holding only `kube_access.elevate` and `kube_access.use`, with its Kubernetes access set to `view`.

**2. Create a service account for the automation**

Under **Organisation → Service tokens**, create a [service token](/guides/service-tokens) with that role. The automation has standing read-only access and nothing more.

**3. Elevate when a person approves**

When a person approves out of band (in chat, in your ticketing tool), the automation calls `elevate` with a short expiry and a reason that points at the approval. The elevation ends on its own when it expires.

Every elevation reaches your notification channels and the audit log, as described below.

***

## Refusals

A grant or elevation the policy does not allow answers `403` with a JSON `detail` code:

| `detail` code | Extra field | Meaning |
| - | - | - |
| `cluster_access_policy_violation` | `max_grant_role` | The role is above the ceiling |
| `cluster_access_grant_expiry_required` | `max_lifetime_seconds` | The grant needs an expiry |
| `cluster_access_grant_lifetime_exceeded` | `max_lifetime_seconds` | The expiry is further away than the policy allows |
| `cluster_access_grant_reason_required` | `require_reason_from_role` | The grant needs a reason |

***

## Notifications and audit

Two notification kinds report access changes. Both are `warning` severity and are delivered through your organisation's [notification routes](/guides/notification-routing#cluster-access-kinds) (Slack, Microsoft Teams, Discord, PagerDuty, webhook):

| Kind | Sent for |
| - | - |
| `cluster_access_policy_changed` | Every accepted policy change, with who made it and the policy before and after |
| `cluster_access_elevated_grant` | Every self-elevation at any role, and every `admin` or `cluster-admin` grant, including extensions |

They reach catch-all routing rules and the home channel without any configuration, and a rule can also name either kind.

Every grant and policy change is also in the [audit log](/guides/audit-log): `cluster_access_grant_created`, `cluster_access_grant_extended`, `cluster_access_grant_deleted` and `cluster_access_policy_updated`. Grant entries record the `authority`, the permission the grant was made under (for example `kube_access.manage` or `kube_access.elevate`).

***

## Availability

* Cluster Access requires the access gateway to be enabled for your deployment. When it is not enabled, the access endpoints return `404` and the **Access** view reports the feature as unavailable.
* [Sandbox clusters](/guides/cluster-sandbox) do not support Cluster Access.

***

## API

All endpoints are organisation-scoped and operate on a specific cluster. Managing grants requires the `kube_access.manage` permission (owners and admins); write operations require a CSRF header for browser-originated requests.

The table below lists the **session-authenticated portal endpoints**. The CLI and API tokens use token-authenticated equivalents under `/api/v1/clusters/{cluster_id}/...` (`/access/grants` for managing grants, `/access/elevate` for break-glass, `/k8s-token` and `/kubeconfig` for consuming access) - see the [kubectl access API table](/guides/kubeconfig#api).

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/org/clusters/{cluster_id}/access/capabilities` | Whether access is enabled, and if the caller can manage / already has access |
| `GET` | `/org/clusters/{cluster_id}/access/members` | Organisation members eligible for a grant |
| `GET` | `/org/clusters/{cluster_id}/access/grants` | List existing grants and their reconcile status |
| `POST` | `/org/clusters/{cluster_id}/access/grants` | Create a grant |
| `DELETE` | `/org/clusters/{cluster_id}/access/grants/{grant_id}` | Delete a grant |
| `POST` | `/org/clusters/{cluster_id}/access/kubeconfig` | Generate a kubeconfig for the caller |
| `POST` | `/org/clusters/{cluster_id}/access/revoke-all` | Revoke all grants and tokens for the cluster |
| `GET` | `/org/cluster-access-policy` | Read the organisation access policy |
| `PUT` | `/org/cluster-access-policy` | Change the organisation access policy |

See [Accessing clusters with kubectl](/guides/kubeconfig) for how members consume their access, and the [API Reference](/api-reference/introduction) for full schemas.


# Cluster Autoscaling
Source: https://docs.ankra.ai/guides/cluster-autoscaling

Automatically scale node groups on Ankra-provisioned clusters based on pod demand.

Ankra-provisioned clusters on Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, AWS EC2 and Ankra Cloud (both k3s and kubeadm; Scaleway and Ankra Cloud are in closed beta) can automatically scale worker node groups based on pod demand. Ankra runs the upstream [Kubernetes Cluster Autoscaler](https://github.com/kubernetes/autoscaler) inside your cluster and wires it to the Ankra platform, which provisions and removes the actual cloud servers.

When pods are unschedulable because a node group is full, the autoscaler adds nodes (up to the group's **max**). When nodes sit underutilised and their pods fit elsewhere, it drains and removes them (down to the group's **min**), respecting PodDisruptionBudgets throughout.

***

## How it works

Autoscaling is configured per node group with three settings:

| Setting | Meaning |
| - | - |
| **Enabled** | Whether the autoscaler manages this group's node count |
| **Min** | The group never shrinks below this many nodes (minimum `1`) |
| **Max** | The group never grows beyond this many nodes (up to `100`, and within the cluster's node limit below) |

Behind the scenes:

1. The **Cluster Autoscaler** runs in your cluster and watches for unschedulable pods and underutilised nodes.
2. It talks to the **Ankra agent** in-cluster (over mutual TLS), which forwards scaling decisions to the Ankra platform.
3. The **platform** creates or drains/deletes the actual cloud servers through the same provisioning pipeline used for manual scaling - every change shows up as an operation and an audit entry attributed to `cluster-autoscaler`.

Scale-down drains nodes before removal and honours PodDisruptionBudgets. Scale-up clones the group's existing worker configuration (instance type, labels, taints).

> [!NOTE]
>
> Enabling autoscaling requires a recent `ankra-agent` (the platform tells you the minimum version if the cluster's agent is too old). The Cluster Autoscaler itself is installed automatically the first time you enable autoscaling on any group - no manual Helm work needed.

***

## Enable at cluster creation

In the create wizard for any of these providers, toggle **Enable autoscaling** on a node group and set **Min**/**Max**. The node count becomes the group's *initial* count and must lie within the bounds.

Via the API, include an `autoscaling` object per node group:

```json theme={null}
{
  "node_groups": [
    {
      "name": "default",
      "instance_type": "cpx32",
      "count": 2,
      "autoscaling": { "enabled": true, "min_count": 1, "max_count": 5 }
    }
  ]
}
```

***

## Enable on an existing cluster

### Via the Platform UI

**1. Open the node groups**

Open **Nodes** in the cluster sidebar, then the **Node groups** tab.

**2. Toggle autoscaling on the node group**

On the node group card, switch **Autoscaling** on and set **Min** and **Max**. The manual node-count stepper becomes read-only ("Managed by autoscaler").

**3. Save**

Saving persists the bounds and installs the Cluster Autoscaler (plus metrics-server) on first enable.

### Via the CLI

```bash theme={null}
# Show current settings
ankra cluster node-group autoscaling get <cluster_id> <group_name>

# Enable with bounds
ankra cluster node-group autoscaling set <cluster_id> <group_name> \
  --enabled --min 1 --max 5

# Disable (the group keeps its current node count)
ankra cluster node-group autoscaling set <cluster_id> <group_name> --enabled=false
```

The cloud provider is detected automatically from the cluster.

### Via the API

```bash theme={null}
# Read
GET /api/v1/clusters/{provider}/{cluster_id}/node-groups/{group_name}/autoscaling

# Write
PUT /api/v1/clusters/{provider}/{cluster_id}/node-groups/{group_name}/autoscaling
{ "enabled": true, "min_count": 1, "max_count": 5 }
```

***

## Interaction with manual scaling

Per-group manual scaling stays available while autoscaling is enabled, but the requested count is **clamped into `[min, max]`** - you cannot manually push an autoscaled group outside its bounds. The legacy whole-cluster worker scale (`ankra cluster scale`) is refused while any group is autoscaling-enabled, since it removes workers across all groups indiscriminately. To take full manual control again, disable autoscaling first.

New nodes added by the autoscaler carry the group's labels and taints, plus the canonical `ankra.cloud/node-group` label Ankra uses to track group membership.

***

## Behaviour details

* **Scale-down is conservative by default**: a node must be unneeded for \~10 minutes, and scale-down pauses for 10 minutes after any scale-up.
* **Failed provisioning is self-healing**: if a cloud server fails to create or join, the autoscaler is told about the failure and backs off; stuck half-created servers are garbage-collected automatically.
* **Node upgrades and autoscaling do not fight**: a node the autoscaler is draining for removal is skipped by Kubernetes version upgrades.
* **Control planes are never autoscaled** - only worker node groups.

## Limitations (v1)

* **Min must be at least 1.** Scale-to-zero is not supported yet: the autoscaler templates new nodes from a live node of the group.
* While a group has zero *Ready* nodes, scale-up is degraded for the same reason.
* Deleting a node group removes its autoscaling settings with it.
* **The cluster's pod range caps the whole cluster.** A cluster created with a network identity holds at most 64 nodes, control planes included (see [Network ranges and their limits](/platform/cluster-mesh#network-ranges-and-their-limits)). A **Max** that would let the groups grow past that is refused when you set it, and a scale-up the autoscaler asks for past it is refused, so the autoscaler backs off instead of adding a node that could never become Ready.

> [!TIP]
>
> Operators can globally suspend autoscaler-driven scaling without touching clusters by setting `AUTOSCALER_ENDPOINTS_ENABLED=false` on the platform - the in-cluster autoscaler keeps observing, but its scaling requests are refused until the switch is turned back on.


# Verify a Cluster Mesh
Source: https://docs.ankra.ai/guides/cluster-mesh-verification

Prove cross-cluster traffic on a Cilium Cluster Mesh with a global service, live from the pod terminal

Both clusters show `ready`, but you want proof that traffic really crosses the mesh before you rely on it. This guide takes a connected [Cluster Mesh](/platform/cluster-mesh) and proves it end to end: a service with backends only in one cluster, consumed from a pod in the other, verified live in the portal's pod terminal. It takes about five minutes and leaves nothing behind.

## What you need

* Two clusters joined to the same mesh, both members showing `ready`:

  ```bash theme={null}
  ankra cluster mesh show <mesh-id>
  ```

* `kubectl` contexts for both clusters (`ankra cluster kubeconfig add --use` on each).

Throughout this guide, **cluster A** runs the backends and **cluster B** consumes them. The direction is arbitrary - swap it or run it both ways.

## 1. Deploy backends and a global service on cluster A

The whole trick is one annotation: `service.cilium.io/global: "true"`. A Service carrying it, with the **same name and namespace** in every cluster, is one service mesh-wide - Cilium merges the healthy backends from every member.

```yaml mesh-echo-backend.yaml theme={null}
apiVersion: v1
kind: Namespace
metadata:
  name: mesh-test
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mesh-echo
  namespace: mesh-test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mesh-echo
  template:
    metadata:
      labels:
        app: mesh-echo
    spec:
      containers:
        - name: echo
          image: ealen/echo-server:0.9.2
          ports:
            - containerPort: 80
          env:
            - name: PORT
              value: "80"
          resources:
            requests:
              cpu: 10m
              memory: 32Mi
            limits:
              cpu: 100m
              memory: 64Mi
---
apiVersion: v1
kind: Service
metadata:
  name: mesh-echo
  namespace: mesh-test
  annotations:
    service.cilium.io/global: "true"
spec:
  selector:
    app: mesh-echo
  ports:
    - port: 80
      targetPort: 80
```

```bash theme={null}
kubectl --context <cluster-a> apply -f mesh-echo-backend.yaml
```

## 2. Create the same global service on cluster B - with no backends

Cluster B gets the Service and namespace only. Its selector matches nothing locally, which is the point: any traffic it serves must have crossed the mesh.

```yaml mesh-echo-frontend.yaml theme={null}
apiVersion: v1
kind: Namespace
metadata:
  name: mesh-test
---
apiVersion: v1
kind: Service
metadata:
  name: mesh-echo
  namespace: mesh-test
  annotations:
    service.cilium.io/global: "true"
spec:
  selector:
    app: mesh-echo
  ports:
    - port: 80
      targetPort: 80
```

```bash theme={null}
kubectl --context <cluster-b> apply -f mesh-echo-frontend.yaml
kubectl --context <cluster-b> -n mesh-test run mesh-client \
  --restart=Never --image=curlimages/curl:8.10.1 --command -- sleep 14400
```

The `mesh-client` pod is your vantage point inside cluster B.

## 3. Prove it from the pod terminal

In the portal, open **cluster B → Kubernetes → Workloads → Pods**, search for `mesh-client`, open it, and switch to the **Terminal** tab. **Connect**, then run:

```bash theme={null}
hostname; for i in 1 2 3 4 5; do curl -s mesh-echo.mesh-test | grep -o '"HOSTNAME":"[^"]*"'; done
```

![Ankra pod terminal on the consuming cluster: hostname prints mesh-client, and five curl responses print the HOSTNAME of mesh-echo backend pods that run on the other cluster, alternating between the two](https://mintcdn.com/ankra/_z3dVhlo8R4GQTBy/images/cluster-mesh-terminal-proof.jpg?fit=max\&auto=format\&n=_z3dVhlo8R4GQTBy\&q=85\&s=c7e2728ec078120190ced46cc91f7197)

Five requests from a pod on one cluster, every response served by pods on the other - load-balanced between them.

Read what the output says: `hostname` confirms you are in `mesh-client` on cluster B, and every response's `HOSTNAME` is a `mesh-echo-…` pod. Cluster B has **zero** backends for this service, so each of those responses was served across the mesh - and the alternation between pod names is Cilium load-balancing over the remote backends.

## 4. Close the loop

Open **cluster A → Kubernetes → Workloads → Pods** and search for `mesh-echo`:

![Cluster A's pod list showing the two mesh-echo backend pods, Running in the mesh-test namespace, whose names match the HOSTNAME values the terminal printed](https://mintcdn.com/ankra/_z3dVhlo8R4GQTBy/images/cluster-mesh-backends-proof.jpg?fit=max\&auto=format\&n=_z3dVhlo8R4GQTBy\&q=85\&s=44aed35e1a821f11dc885ac430aa02ed)

The exact pods that served the requests, running on the other cluster.

The pod names match the `HOSTNAME` values from the terminal, byte for byte. Request made on one cluster, served by the other.

## What this verifies - and what it does not

A passing run proves the whole chain at once: the shared trust root, both `clustermesh-apiserver`s, the cross-cluster service catalogue, and the pod-to-pod data path over the overlay. If you want the layer-by-layer view instead, `cilium-dbg status` inside a Cilium agent pod reports `ClusterMesh: 1/1 remote clusters ready`, and `cilium-health status` probes every node and endpoint in both clusters.

For real workloads, run backends in **both** clusters behind the global service: Cilium prefers healthy backends and a cluster losing its local ones fails over to the remote side. This guide keeps backends on one side only because asymmetry is what makes the proof unambiguous.

## Troubleshooting

* **`curl` times out** - check both members read `ready` in `ankra cluster mesh show`; a member in `configuring` has not converged yet, and `degraded` means it verified fewer peers than expected. The [Cluster Mesh page](/platform/cluster-mesh#troubleshooting) maps each status to its fix.
* **DNS resolves but only local backends answer** - the Service must carry `service.cilium.io/global: "true"` and identical name + namespace in *both* clusters; a mismatch on either side splits it back into two local services.
* **A Proxmox or on-prem pair** - confirm the site prerequisites (site address, UDP port-range forward): one reachable side is enough, but none is not.

## Clean up

```bash theme={null}
kubectl --context <cluster-a> delete namespace mesh-test
kubectl --context <cluster-b> delete namespace mesh-test
```


# Playground
Source: https://docs.ankra.ai/guides/cluster-sandbox

A real, writable, ephemeral Kubernetes environment to try Ankra with - no cluster required.

## What Is the Playground?

The playground is a real, writable Kubernetes environment Ankra provisions just for you. Unlike a static demo, everything works: you deploy actual stacks through the actual pipeline, browse live resources, stream real logs, and ask the AI to build and ship things - all before connecting a cluster of your own.

> [!NOTE]
>
> On Ankra's shared playground infrastructure, playgrounds are isolated per organisation. The **free Trial is limited to one per organisation** and expires once everyone has been away for a while — **3 hours on the free plan, a week on a paid one** — with a heads-up notification and email first, and signing back in resets the clock. **Paid sizes can be many** and do not idle-expire: each stays until you destroy it, bounded by your organisation's playground memory budget (below).

> [!NOTE]
>
> The playground replaces the old sandbox demo and is available to every organisation - there is nothing to enable. Organisations created before the change may still have a "sandbox-demo" cluster listed; it keeps working, but its deploys are simulated rather than run on real infrastructure. Start a playground for the real thing.

## Playgrounds on Ankra Cloud

Playgrounds are moving to **Ankra Cloud dev clusters**: a single-node Kubernetes cluster managed by Ankra, with the Ankra agent installed and connected. It is the cluster [guided setup](/get-started/guided-setup) creates in its first step, and each organisation has one playground at a time.

> [!NOTE]
>
> This is rolling out and is not yet the default everywhere. Until it reaches your organisation, a new playground is created on Ankra's shared playground infrastructure, described in the rest of this page.

| | Without a payment method | With a payment method |
| - | - | - |
| **Size** | One server with 2 vCPU / 4 GB, which also runs Kubernetes and the platform components | The same |
| **Cost** | Free | Paid from your [credit](/platform/billing#credit-and-payment-method) |
| **Lifetime** | 24 hours, then the free cluster ends | Keeps running until you destroy it, while you have credit |

Saving a card while the free cluster is running keeps it: it converts to a cluster paid from credit, and nothing is charged to the card unless you top up. For a new organisation, saving a card also unlocks €59 of [welcome credit](/platform/billing#welcome-credit), so the cluster keeps running without paying anything up front.

The cluster gets its own domain, and apps you publish with an Ingress get a hostname under it. The cluster status shows the domain once it is set up.

The rest of this page also covers playgrounds on Ankra's shared playground infrastructure - virtual clusters with their own API server, ordered by size. Playgrounds started that way keep working as described below.

***

Watch a real playground spin up, start to finish: ready in 82 seconds, the starter app live on its own hostname, then a stack deployed onto it.

[Spin up a real Kubernetes cluster in two minutes with the Ankra Playground](https://www.youtube-nocookie.com/embed/WThqMpO30VE?rel=0)

## Key Characteristics

> [card] Fully Writable
>
> Deploy stacks, apply manifests, delete things, break things. It is a real cluster and it is yours alone.

> [card] Nothing to Install
>
> Ankra provisions the environment and installs the agent for you. No helm command, no kubectl, no cloud account.

> [card] Starter Stack Included
>
> A small demo application deploys through the normal Ankra pipeline the moment your playground comes online - watch a real deploy land in the activity feed.

> [card] Free to Try, Yours When Paid
>
> The free Trial expires once the organisation has been away for a while - 3 hours on the free plan, a week on a paid one - with an in-app and email warning first. A paid size stays until you destroy it.

***

## Starting a Playground

**1. Choose the playground**

On your first visit to Ankra you are offered the choice: connect your own cluster or try the playground. You can also start one any time from **Clusters** → **Create cluster**, where **Playground** is the first Ankra Managed option - it opens a size picker, with the free Trial preselected.

**2. Wait about two minutes**

Provisioning a real environment takes one to three minutes. The progress screen walks through the phases: reserving, starting the cluster, connecting the agent, deploying the starter stack.

**3. Take the tour**

You land on the cluster overview with a short tour that opens on your starter stack deploying live, then hands you the controls: deploy something yourself with the AI (press `⌘+J`).

> [!TIP]
>
> Try asking the AI: *"deploy nginx with 2 replicas"* - it builds the stack and ships it through the same pipeline your production deploys would use.

The picker is not the only door. The same lane is served by the CLI (`ankra cluster playground create`), the API, and **Ankra AI itself** - in chat or through the MCP tools you can ask for the available sizes (with live availability and your budget headroom), order a playground, follow its provisioning, resize it, or destroy it. Anything that costs money asks for your confirmation first, naming the size and the monthly price, and every billing check applies exactly as it does in the picker.

***

## What's Included

| What | Details |
| - | - |
| **A real cluster** | A single-tenant [vcluster](https://www.vcluster.com/) with its own API server, isolated per organisation |
| **The Ankra agent** | Pre-installed and connected - the platform manages it for you |
| **A starter stack** | A small demo app deployed through the normal native-engine pipeline |
| **Resource budget** | The size you ordered, reserved for your own workloads - the virtual cluster's control plane, CoreDNS and the Ankra agent run on top of it, not out of it. Capped pods and storage per size |
| **Storage** | PersistentVolumeClaims bind on the playground host's storage class. Storage is local to that host and **not backed up** - keep anything you cannot afford to lose in your own repositories and registries |
| **Direct deploys** | Stacks deploy through the agent; no Git repository or credentials required |

***

## What You Can Do

Everything that works on an imported cluster works here:

* **Deploy stacks** - build them visually or ask the AI, and watch them come alive.
* **Browse live Kubernetes resources** - real pods, deployments, services, and events.
* **Stream logs and open terminals** - it is a real cluster.
* **Publish with an Ingress** - anything you expose gets a hostname under your playground's own domain, with TLS handled for you. Use an Ingress rather than a LoadBalancer Service: the playground host runs no load-balancer implementation, so a LoadBalancer's external IP stays pending forever.
* **Use the AI assistant** - analyse, deploy, troubleshoot.
* **Explore the activity feed** - every deploy and event, as it happens.

## Sizes and Pricing

Playgrounds are the cheapest compute power on the internet. The playground comes in sizes, ordered from the size picker in **Create cluster** → **Playground**, each at a flat monthly price with storage bundled. The vCPU and memory a size advertises are yours to deploy into: the platform components that run the environment (the virtual cluster's control plane, CoreDNS, the Ankra agent) are reserved on top of the size, not carved out of it.

| Size | For your workloads | Storage | Max pods | PVCs | Monthly price |
| - | - | - | - | - | - |
| **Trial** | 1 vCPU / 2 GB | 20 GB | 30 | 5 | Free - expires when the organisation goes idle |
| Small | 2 vCPU / 4 GB | 50 GB | 40 | 10 | €5.21 |
| Medium | 4 vCPU / 8 GB | 100 GB | 60 | 20 | €8.06 |
| Large | 8 vCPU / 16 GB | 200 GB | 100 | 30 | €15.19 |
| Extra large | 16 vCPU / 32 GB | 400 GB | 150 | 50 | €28.01 |

Prices are in EUR excluding VAT. That works out to €2.61 per vCPU and €1.30 per GB of RAM a month on Small, €2.02 and €1.01 on Medium, €1.90 and €0.95 on Large, and €1.75 and €0.88 on Extra large. There are no per-vCPU, per-GB, egress, IP or GPU charges on top, and a playground never counts toward your plan's worker-vCPU metering.

Ordering a paid size requires billing permissions in your organisation, a billing plan, and a payment card on file - the billing pieces are set up on the billing page, and the picker says so before the order if anything is missing. The free Trial needs none of that. The price you order at is the price of record: later catalogue changes apply to new orders only, never to an environment you are already running. Billing runs pro-rata by the second from the moment the environment is ready until you destroy it, appears as its own line on the invoice, and every order, resize and destroy leaves a notification receipt. Unpaid invoices eventually pause the lane: new paid orders refuse while an invoice is overdue, and paid playgrounds of an organisation three weeks past due are reclaimed (with warnings well before). The full billing rules are on the [billing page](/platform/billing#playground-environments).

> [!WARNING]
>
> Playgrounds are for development and evaluation only: no production workloads, no personal data, no backups, and they are excluded from the SLA (Terms of Service clauses 6.2 to 6.4 and 9.9).

### Resizing

A paid playground resizes in place from **Settings → General → Playground size** or from the CLI: only the namespace quota and the monthly price change, billed pro-rata across the change - the old price until the resize, the new price after. Nothing you deployed is touched. The free Trial has one fixed shape; ordering a paid size is the upgrade path.

```bash theme={null}
ankra cluster playground resize <playground-id> --size <plan>
```

### Memory budget and limit increases

Paid playgrounds share a per-organisation memory budget: the sum of their advertised memory, **8 GB by default** unless a limit increase has been approved (the free Trial does not count). The size picker shows how much of the budget your playgrounds use, and a size that does not fit offers a **limit-increase request** right there - the new limit and a short justification, reviewed by the Ankra team, with a notification when it is decided. The budget also lives on the [billing page](/platform/billing#playground-environments): the Playground memory budget card shows the same numbers and request path, along with a request that is pending review or one that was declined.

The free monthly AI allowance works the same way: the allowance card on the billing page offers **Request a limit increase** when you need more platform-funded AI usage than the plan includes.

A size the shared pool cannot place right now shows as unavailable in the picker rather than disappearing - pick a smaller size or try again shortly.

***

## Limits

* One free Trial per organisation (recreate it after it expires); paid playgrounds are bounded by the organisation's memory budget.
* A fixed resource budget (quota-enforced) and egress restricted to what deploys need - the playground is for trying Ankra, not for hosting workloads.
* No GitOps or cluster-access (kubeconfig) wiring - those are for clusters you own.

***

## Playground vs. Your Own Cluster

| Feature | Playground | Imported Cluster |
| - | - | - |
| Setup | One click, \~2 minutes | One helm command on your cluster |
| Ownership | Ankra-hosted, ephemeral | Yours, permanent |
| Write operations | Fully supported | Fully supported |
| Resources | Quota-capped budget | Whatever your cluster has |
| GitOps | Not available | Optional - add a repo for an audit trail |
| Lifetime | Trial expires when idle; paid sizes stay | Forever |

***

## Ready for the Real Thing?

Everything you did in the playground works identically on your own cluster - connecting one takes a single helm command.

> [card] [Import a Cluster](/guides/import-cluster)
>
> Follow the step-by-step guide to connect your real Kubernetes cluster.

> [card] [Install the Agent](/concepts/cluster-agent)
>
> Learn how to install and configure the Ankra Agent.

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.


# Cluster Security
Source: https://docs.ankra.ai/guides/cluster-security

Fleet-wide Trivy vulnerability and compliance posture, actionable cluster checks, organisation policies, NetworkPolicy exposure scoring, and per-add-on security views.

Ankra turns [Trivy Operator](https://aquasecurity.github.io/trivy-operator/latest/) vulnerability and compliance reports into a prioritised security workflow across your organisation, and computes pod-security posture itself from the inventory the agent already streams. The platform reads the operator's Kubernetes reports through the agent. No scanner runs on Ankra's side and no image data leaves your cluster.

> [!NOTE]
>
> Security is a **read and policy layer** over Trivy Operator image CVEs, benchmark compliance, and configuration audits. You install and configure the operator like any other add-on. Ankra surfaces, ranks, explains, and helps remediate what it finds.

***

## Where to work

| Surface | Purpose |
| - | - |
| **Organisation → Security** | Fleet overview, findings, cluster coverage, compliance, and organisation-wide policies |
| **Cluster → Security** | Scoped overview, findings, workloads, and actionable compliance checks for one cluster |
| **Stack add-on → Overview** | Compact security posture for one add-on, with a deep link into cluster Security |

The dashboard **Fleet Security** widget summarises actionable severe risk and links into the organisation Security Center.

***

## Prerequisites

Trivy Operator must be running in each cluster you want to assess. If it is not installed, the Security views explain the setup state and link to **Settings → Integrations → Trivy Operator**.

**1. Add the Trivy Operator add-on**

From **Settings → Integrations → Trivy Operator**, or the Stack Builder, add the `trivy-operator` Helm add-on and deploy it. It scans workloads and writes vulnerability, compliance, and configuration-audit reports.

**2. Wait for the first reports**

The operator scans images shortly after install. Until reports exist, the integration shows `installed_no_reports`.

**3. Open Security**

Use the organisation **Security** entry for fleet triage, or a cluster's **Security** sidebar entry for a scoped view.

**4. Optional: publish a software bill of materials**

The **SBOM** tab reads the operator's SbomReports, which are off by default because they are the largest objects it writes. On a cluster with control-plane headroom, set the security baseline input **Software bill of materials per image** (`trivy_sbom_generation_enabled`) to `true`; the next scan pass fills the tab. A package list, never image content, then leaves that cluster.

***

## Security baseline

`ankra-security-baseline` is the public stack profile the platform installs on every cluster it provisions, unless the organisation opted out, and the one **Enable security baseline** installs on an imported cluster's Security page. Like every profile it is a catalogue entry you can open, copy and fork. From version 5 it carries:

* **Trivy Operator** for image vulnerabilities, sized for a small cluster by default. Its workload configuration audit, RBAC assessment, CIS compliance report and CIS node assessment are off by default since version 7, because each of them loads the control plane. Turn them on per cluster with the profile inputs `trivy_config_audit_enabled`, `trivy_rbac_assessment_enabled`, `trivy_cluster_compliance_enabled` and `trivy_infra_assessment_enabled` to fill the CIS compliance view.
* **Pod Security Standards, enforced by Kubernetes itself.** The profile ships an `ankra-pod-security` ConfigMap declaring the standard (`baseline` or `restricted`), the policy mode and the exempt namespaces. The Ankra agent labels every other namespace for [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/), the admission controller built into every API server: `pod-security.kubernetes.io/audit` and `/warn` at the standard in Audit mode, and `/enforce` as well once you switch the cluster to Enforce. Labels are only ever raised, so a namespace you hold at a stricter level keeps it, and the agent records what it set so switching back to Audit restores the previous state exactly.
* **A guard for the enforce label.** A ValidatingAdmissionPolicy (Kubernetes 1.30 or newer) refuses lowering the enforce label of a managed namespace below the declared floor for anyone but the agent, so enforcement cannot be switched off with a namespace edit. It fails open: an admission it cannot evaluate is admitted.

No policy engine runs on the cluster. Earlier versions of the baseline carried Kyverno with its Pod Security Standards preset; a cluster that installed one keeps it, receives the new manifests on its next update, and the policy mode toggle drives both mechanisms until you remove the two Kyverno add-ons from the stack. Kyverno remains available as the opt-in `ankra-policy-engine` profile, in the same safe mode, for image-signature verification and policies of your own.

### What runs where

| Concern | Where it is computed |
| - | - |
| Image vulnerabilities, and the configuration audits and CIS benchmark on a cluster that turned them on | Trivy Operator, on the cluster; the platform reads its reports |
| Pod Security Standards and configuration posture of every workload | The platform, from the inventory the agent streams; no report object is written on the cluster |
| Pod-security enforcement | The API server's Pod Security Admission, from namespace labels the agent manages |
| Enforce-label protection | A ValidatingAdmissionPolicy the API server evaluates in-process |

The Security Center's **Policies** tab shows both halves per cluster: the platform posture table (every check, how many workloads pass and fail it, and when the inventory it was computed from was last seen) and the Pod Security Admission line (mode, standard, and how many namespaces carry the labels), beside the policy engine's own reports where one is installed. Enforcement is measured from the namespaces, not assumed from the setting.

### Sizing

The platform sizes the baseline from the cluster's shape. A control plane below **8 GB** of memory, or one whose size the platform cannot determine, gets the **lite** shape: the CIS node assessment is off so no collector job lands on the control plane, and one image scan runs at a time. The cluster carries a notification saying so until the control plane grows. A control plane of 8 GB or more gets the standard shape, and three or more workers let two scans run at once. A cluster you moved to Enforce, or whose exempt list you changed, keeps that across every republish.

### Inputs

| Input | Default | Meaning |
| - | - | - |
| `pod_security_standard` | `baseline` | The standard every managed namespace is labelled with; `restricted` will flag most off-the-shelf charts |
| `policy_mode` | `Audit` | Audit reports and warns and never blocks; Enforce makes the API server refuse pods that violate the standard |
| `pod_security_exempt_namespaces` | the control plane, scanner, agent, GitOps, CNI, Hetzner and cert-manager namespaces | Namespaces the standard is never applied to. `kube-system`, `kube-public`, `kube-node-lease` and the agent's namespace are exempt whatever the list says; a single `-` exempts nothing else |
| `trivy_scan_concurrency` | `1` | Image scans that run at once |
| `trivy_scan_job_timeout` | `10m` | How long one image scan may run |
| `trivy_infra_assessment_enabled` | `true` | The CIS node assessment (the lite shape turns it off) |
| `trivy_sbom_generation_enabled` | `false` | The SBOM opt-in described above |

The policy mode is also on the API: `POST /org/clusters/imported/{cluster_id}/security/policy-mode` with `{"mode": "audit"}` or `{"mode": "enforce"}`, and the per-cluster `GET .../security/policy-violations` read carries `policy_mode` beside a `platform_posture` block with the posture table and the `pod_security` coverage figures.

**From the CLI and MCP.** `ankra security policy-mode audit|enforce --cluster <cluster>` switches the mode (both directions confirm; `--yes` skips the prompt), `ankra security violations --cluster <cluster>` reads the posture table and the results per policy, and `ankra security enable-baseline --cluster <cluster>` publishes the baseline stack on a cluster that has none. From chat or the MCP server the same three are `set_cluster_security_policy_mode`, `get_cluster_policy_violations` and `enable_security_baseline`; the two writes are confirmed before they run.

***

## Connection and scanner states

| State | Meaning |
| - | - |
| `not_installed` | Trivy Operator CRDs are not present — install the add-on |
| `installed_no_reports` | The operator is installed but has not produced reports yet |
| `connected` / fresh | Live or recently materialised reports are available |
| `degraded` / stale | The live read failed or data is older than the freshness window; cached data may still be shown |
| `unscanned` | The cluster has no usable security snapshot yet |

***

## Observed vs actionable risk

Every finding is tracked with two complementary views:

* **Observed** — everything Trivy currently reports, including accepted risk.
* **Actionable** — findings that still need attention: open **and** acknowledged. Accepted risk is excluded from actionable totals, remediation queues, and threshold alerts, but remains visible.

Primary KPIs, fleet posture, alerts, scheduled reports, and AI summaries use **actionable** counts. Observed and accepted-risk totals stay available for context.

***

## Exploitation intelligence (CISA KEV and EPSS)

CVSS severity says how bad a vulnerability could be; it says nothing about whether anyone is exploiting it. The Security Center cross-references every finding with two public feeds so you can prioritise on real-world exploitation:

* **CISA Known Exploited Vulnerabilities (KEV)** - the catalog of CVEs with confirmed in-the-wild exploitation. A listed finding carries a **KEV** marker, the date CISA added it, the federal remediation deadline, and whether it is known to be used in ransomware campaigns.
* **FIRST EPSS** - the daily Exploit Prediction Scoring System: the probability the CVE is exploited in the next 30 days, and where that probability ranks among all scored CVEs (for example `EPSS 94% · top 1%`).

The join happens on the platform by CVE id against the ids already present in your Trivy reports, so no image data leaves your cluster and Trivy Operator needs no extra configuration. The platform refreshes both feeds every six hours; a CVE that first appears between two refreshes has its KEV status immediately (the whole catalog is stored) and its EPSS score after the next pass.

Where it appears:

* **The exploited-in-the-wild banner** - when CISA lists any of your actionable findings, the Overview, the Findings page, and each cluster's Security tab open with a red banner naming how many vulnerabilities are being exploited, how many are past CISA's remediation deadline, and how many CISA links to ransomware campaigns, with **Review exploited findings** and **Fix with AI** one click away. It only appears on a synced catalog with a real count - it never renders "nothing exploited" from a catalog that has not been read.
* **Findings** - the list opens ranked by **Exploitability** (KEV listing first, then EPSS, then severity), so the top of the page is what is actually being exploited. Each listed finding shows the **KEV** marker, CISA's remediation deadline in explicit tense (**deadline passed 2025-04-22** turns red), a **ransomware** marker where CISA reports ransomware use, and the EPSS probability. The **Known exploited (CISA KEV)** chip narrows to listed findings. The detail sheet quotes CISA's own entry - vulnerability name, vendor and product, the deadline, and **CISA required action** - and shows EPSS and KEV under **Advisory details**.
* **Overview** - a **Known exploited** scorecard tile with the overdue and ransomware subsets, and remediation candidates ranked known-exploited first with their CISA deadline.
* **Clusters**, **Workloads**, and the add-on security panel - a known-exploited count beside the actionable and fixable counts, in red wherever it is above zero.
* **Alerts** - two `security_findings` metrics: `kev` (actionable known-exploited findings on a cluster) and `new_kev_cves` (known-exploited CVEs new since the previous scan). The built-in new-severe-CVE notification also flags KEV listings of any severity.
* **Scheduled reports** - a known-exploited banner, **KEV** markers and EPSS in the top-CVE table, and fix groups that clear a known-exploited CVE listed first.
* **API and MCP** - `known_exploited`, `kev_date_added`, `kev_due_date`, `kev_ransomware_use`, `kev_vendor_project`, `kev_product`, `kev_vulnerability_name`, `kev_required_action`, `epss_score`, and `epss_percentile` on every finding and remediation candidate, a `known_exploited` filter on the findings and workloads lists, `known_exploited` counts on the overview, cluster, workload, and add-on reads, and `known_exploited_overdue` and `known_exploited_ransomware` finding counts on the overview. Pull them into your own reporting with a personal API token (`ankra tokens create`) against `GET /api/v1/org/security/overview`, `/findings`, `/findings/{finding_id}`, `/workloads`, and `/clusters` on `https://platform.ankra.app` - for example `GET /api/v1/org/security/findings?known_exploited=true&sort=exploitability&order=desc`. The AI security context carries the same fields.
* **CLI** - `ankra security overview` (fleet totals, coverage, remediation candidates, and the exploited-in-the-wild summary first), `ankra security findings` (exploitability order by default, with `--known-exploited`, `--severity`, `--status`, `--fixable`, `--cluster`, `--addon`, `--namespace`, `--sort`), `ankra security finding <id>` (CISA's entry, deadline and required action above every occurrence) , `ankra security advisory <cve>` (the platform's own advisory for a CVE: the parsed NVD/OSV record, CISA's guidance, affected versions in words, and your organisation's exposure) and `ankra security clusters`; every one takes `-o json` for reporting.

```bash theme={null}
ankra security overview                      # fleet totals, coverage, and the exploited-in-the-wild summary
ankra security findings --known-exploited    # only the findings CISA lists as exploited, deadline first
ankra security finding <id>                  # CISA's entry, deadline and required action for one finding
ankra security advisory <cve>                # the platform's advisory: parsed NVD/OSV record, CISA guidance, your exposure
ankra security clusters -o json              # per-cluster posture for reporting
```

Until the platform has synced the catalog at least once, the overview tile and the findings page say so rather than reporting zero: an unsynced catalog is unknown, not clean.

## Advisory pages

Every finding links to an **Ankra advisory page** for its CVE at `/organisation/security/advisories/CVE-...` - the **Advisory** link on each findings row and **Open advisory** in the finding sheet - instead of sending you to the scanner's external advisory site. The platform reads the public record itself, from the NVD 2.0 API and OSV, parses it, and renders it in the Security Center's own vocabulary:

* **Summary** - the analyst description, weakness classes (CWE ids), and aliases such as the GHSA id.
* **Exploitation** - CISA's KEV entry when the CVE is listed (catalog name, vendor and product, date added, the remediation deadline in explicit tense, ransomware use, and **CISA required action**), the FIRST EPSS probability, and CISA's SSVC decision (exploitation observed, automatable, technical impact) as NVD republishes it.
* **Severity** - the lead CVSS score and vector spelled out component by component (attack vector, privileges required, user interaction, impact), with every published assessment - NVD's own and the CNA's - one click away.
* **Affected versions** - the CNA's affected products and version ranges from NVD and the ecosystem package ranges from OSV, written as "2.34 before 2.39 (fixed in 2.39)" rather than as commit hashes.
* **In your fleet** - the organisation's current findings for the CVE (one per package, with occurrences, clusters, workloads, and how many occurrences have a fix), each opening the finding sheet.
* **References** - the sources' links grouped by kind: patches and vendor advisories first, then exploits, trackers, and mailing lists.

An advisory has three states and the page says which one it is in. A CVE the platform has not read yet shows **Fetching this advisory from NVD and OSV** and refreshes on its own - opening the page moves that CVE to the front of the platform's read queue, and most records arrive within a minute. A CVE neither source holds a record for (a reserved or very new id) says **No public advisory record for this CVE yet** and is re-checked every two weeks. Only a record both sources actually returned renders as the advisory, with a provenance footnote naming when NVD and OSV were last read and linking to their own pages.

The platform reads advisories for every CVE its security findings reference, known-exploited ones first, and re-reads stored records every 14 days so a reanalysed score or a newly published fixed version lands without anyone asking. The same content is available on the API as `GET /api/v1/org/security/advisories/{cve_id}` with a personal API token and on the CLI as `ankra security advisory <cve>`; its `status` field carries the three states (`fetched`, `pending`, `missing`, plus `error` while a source cannot be read).

***

## Organisation Security Center

The organisation Security Center has eight sections:

### Overview

Emphasises what to fix first. When CISA lists any actionable finding, the page opens with the exploited-in-the-wild banner. A fleet scorecard follows: a posture ring showing the share of scanned clusters with no actionable critical or high findings, a plain-language verdict, a **Known exploited** tile counting findings on the CISA Known Exploited Vulnerabilities (KEV) catalog (with how many are past CISA's deadline and how many are used in ransomware), and tiles for actionable critical, actionable high, fixable severe, and scanner coverage. Remediation candidates rank known-exploited CVEs first, ahead of CVSS severity. Below it sit the fleet trend, ranked remediation opportunities, and policies nearing review.

The page reads from posture rollups the platform keeps current as scans land, so the overview, the findings list, and the cluster posture answer in milliseconds on fleets with millions of recorded occurrences.

The fleet posture trend is built from **daily snapshots**, so you can see whether actionable risk is rising or falling over time rather than only its current level. The same trend feeds [scheduled security reports](/guides/security-reports).

**From the CLI and MCP.** One cluster's snapshots are readable off the browser: `ankra security history --cluster <cluster> [--days 90]` prints the day-by-day table (findings by severity, fixable severe, workloads and namespaces scanned, risk score, the actionable / acknowledged / accepted-risk split) with a one-line trend; from chat or the MCP server the tool is `get_cluster_security_history`, and with an API token the route is `GET /api/v1/org/clusters/imported/{cluster_id}/security/trivy/history?days=`. A cluster without snapshots yet answers an empty list, not zeros.

**Fix top findings with AI** hands the highest-ranked remediation candidates to Ankra AI with fleet context attached and asks for a prioritised plan. See [Ask Ankra AI](#ask-ankra-ai).

### Findings

Server-paginated inventory of logical findings, deduplicated across clusters and workloads. Status filter chips carry live counts: **Actionable** (open and acknowledged, the default view), **Open**, **Acknowledged**, **Accepted risk**, and **Resolved**. Filter further by severity, fixability, **Known exploited (CISA KEV)**, cluster, add-on, and namespace. Each finding carries its exploitation intelligence: a **KEV** marker when CISA lists the CVE as exploited in the wild, CISA's remediation deadline, a **ransomware** marker where CISA reports it, and the FIRST **EPSS** probability and percentile. The list opens sorted by **Exploitability** (KEV listing, then EPSS, then severity); every other sort is one click away. The detail sheet lists occurrences and matching policies, quotes CISA's required action for a listed CVE, and carries the disposition actions plus **Ask Ankra AI**.

Every number on a row opens the rows behind it. The **Occurrences** chips (**Open · 7**, **Resolved · 2**) count occurrences - one per workload, container and image, so a workload can carry several - and selecting one opens the sheet on exactly that status: the live statuses filter the remediation plan, and **Resolved** shows the occurrences the scanner no longer reports, most recently resolved first, with the workload, image and when each was resolved. The **Affected** cell (**7 clusters · 7 workloads**) opens the sheet's **Affected clusters** table, one row per cluster with its live workloads, the same four status counts, and when it last reported the finding; each cluster name deep-links into that cluster's Security tab with the finding already open, so a fleet-wide count can be followed down to one cluster's rows. A cluster that has since been deleted keeps its row (its occurrences are still part of the totals) but is marked **deleted** and not linked. The counts and the lists are computed by the same query, so a chip never claims a row the sheet cannot show. The API exposes the same views as `clusters` on `GET /api/v1/org/security/findings/{finding_id}` and the paginated `GET /api/v1/org/security/findings/{finding_id}/occurrences?status=resolved&cluster_id=…`.

**When an occurrence becomes resolved.** Deleting a workload, or the `VulnerabilityReport` trivy-operator wrote for it, does not retire its occurrences on the next pass. The platform re-evaluates findings every five minutes, but it counts an occurrence as missing only once per completed full resource sync of the vulnerability-report kinds, and retires it after it has been missing on two consecutive full syncs, so a partial or interrupted sync can never read as a clean bill. Full syncs run about once an hour, which means an image that stopped running stays **Open** for one to two hours before it moves to **Resolved** and the cluster's and namespaces' actionable, critical and known-exploited totals drop with it. To bring that forward, run **Full Sync** from the cluster's [Settings → Kubernetes](/platform/cluster-settings#kubernetes) tab twice, letting the first finish before starting the second; the evaluation that follows the second sync retires the occurrences.

### Clusters

Per-cluster actionable posture, observed/accepted context, scanner freshness, and a deep link into that cluster's Security view.

### Workloads

The fleet broken down the way a platform team owns it: **cluster, then namespace, then workload, then pod**. Each row is one namespace on one cluster with its scanned workloads and images, the pods the cluster runs there right now, the actionable findings by severity, the known-exploited count, fixable severe findings, and the last scan. Cluster-scoped reports (node and control-plane images) keep a row of their own, labelled **Cluster-scoped**, so the rows still add up to the cluster's totals. Search by namespace or cluster, scope to one cluster, and sort by actionable findings, severity, known exploited, workloads, or pods.

A namespace is where the drill-down starts, because it is usually how a team owns its workloads. Every row carries the way down: **Findings**, **Bill of materials** and **Containers** open the Findings and SBOM tabs already narrowed to that namespace on that cluster, and every figure on the row is a link to the list it counts - the actionable total to those findings, the known-exploited count to the KEV-listed ones, the image count to the images running there, the pod count to the running containers. Rows also say how many of their images have a bill of materials, with a link to the containers running without one. Once narrowed, a **scope bar** at the top of the Findings, Workloads and SBOM tabs names the cluster and namespace, offers the same scope on the other surfaces, and drops it in one click; the tab bar carries the scope across too, so switching tabs never falls back to the fleet.

**Show workloads** on a row lists the scanned workload images in that namespace, riskiest first, each linking to its live Kubernetes page and to the bill of materials of the containers it runs. **Show pods** under a workload lists the pods it owns right now - resolved through the owner chain, so a Deployment's report on its ReplicaSet reaches the pods - with every container joined to the findings of the workload container behind it: critical and high counts, known-exploited markers, readiness and restarts, and the running image digest. A container the scanner has no report for is marked **Not scanned**, never shown as clean, and a pod nobody scanned reads **Not scanned** rather than healthy. A namespace with more than 2,000 pods says the listing is capped.

The API exposes the same three levels: `GET /api/v1/org/security/namespaces?cluster_id=&search=&sort=&order=`, the existing `GET /api/v1/org/security/workloads?cluster_id=&namespace=`, and `GET /api/v1/org/security/pods?cluster_id=&namespace=&workload_uid=` (or `workload_kind` + `workload_name`).

**From the CLI and MCP.** `ankra security namespaces [--cluster]`, `ankra security workloads` (the findings filters plus `--sort risk_score`) and `ankra security pods --cluster <cluster> --namespace <namespace> [--workload-kind --workload-name]` walk the same three levels, and `ankra security finding <id> --status resolved --cluster <cluster>` lists one finding's occurrences instead of the summary. From chat or the MCP server the tools are `list_security_namespaces`, `list_security_workloads`, `list_security_pods` and `list_security_finding_occurrences`.

### SBOM

The fleet's **software bill of materials**: every package the scanner found in every container image, where it runs, and whether a finding names it. It answers the question a new CVE raises - *where do we run this package* - without waiting for a rescan.

**Components** lists one row per package name, version and ecosystem across every image that carries it: its licences and their **licence risk tier**, how many images, workloads and clusters carry it, and the findings that name that exact package and version on those images (with **actionable** and **known exploited** counts; the findings count links to the Findings tab searched for the package). Search by name or package URL, filter by ecosystem or licence tier (the chips carry live counts), keep only packages with or without findings, and scope to one cluster or namespace.

#### Licence risk

Every component's licences - the SPDX identifiers, expressions or names the scanner recorded - are classified into one of six tiers, ordered by what they oblige of the code that links the package. The classification follows SPDX semantics: an `OR` expression lets you pick the least consequential alternative, an `AND` binds every term, and a package that names several licences is taken to be under all of them.

| Tier | Licences | What it means for a service you host |
| - | - | - |
| **Network copyleft** | AGPL, SSPL, EUPL, OSL, RPL, CAL | Serving it over a network counts as distribution: the source of every service that links it must be published. The single biggest landmine for a proprietary backend. |
| **Source-available** | BUSL, Elastic License, Redis Source Available, Commons Clause, PolyForm, non-commercial Creative Commons | Hosting it as part of a managed service needs a commercial licence from the author, whatever your repository's visibility. |
| **Copyleft** | GPL, GFDL, CeCILL, Sleepycat, CC-BY-SA | Safe behind a private backend (the "SaaS loophole"); shipping it in a browser bundle, mobile app or CLI is distribution and requires publishing the source of what it links. |
| **Weak copyleft** | LGPL, MPL, EPL, CDDL, CPL, and GPL with a linking or Classpath exception | Links alongside proprietary code; only modifications to the component itself must be published. |
| **Permissive** | MIT, Apache-2.0, BSD, ISC, Unlicense, CC0, Zlib, PostgreSQL, Python, Boost | No obligation on the surrounding code. |
| **Unclassified** | Anything else, `NOASSERTION`, or a row the classifier has not reached yet | Not a verdict: confirm the terms before relying on it. An unclassified component never counts as permissive. |

The SBOM summary counts the packages under the two tiers that reach the hosting service (**Licence obligations**) and breaks every view down by tier; each figure links to the list it counts, and the tier chips narrow the component list the same way the ecosystem chips do. An image's row and its detail page carry the same per-tier counts, and the CSV export gains a `license_risk` column. Classification happens once, when the bill of materials is stored, so the fleet-wide "every AGPL package we run" read is an indexed filter rather than a rescan; rows stored before the tier existed are classified in the background within a few minutes of a deploy.

Isolating a network-copyleft component behind its own service, reached over REST or gRPC rather than linked into your code, keeps the obligation with that service alone; the tier is the same either way, so the filter is the place to check that no such package sits in an image of your own application.

Every figure in a component row opens the list it counts. The package name opens the **package page**: the images whose bill of materials name that exact name, version and ecosystem, every workload container currently running those images (cluster, namespace, workload, container, image, last seen), and the clusters they run on with per-cluster workload and image counts. The **images**, **workloads** and **clusters** figures in *Where it runs* open that page scrolled to the matching section, and each entry there links onward - an image to its bill of materials, a workload to its live Kubernetes page, a cluster to its security tab, a per-cluster count to the same page narrowed to that cluster (each cluster row reads *N workloads in M containers*) - so the trail from a licence tier to the place it runs never dead-ends. The lists cap at 200 images and 500 containers and say so when they do. The same read is `GET /org/security/sbom/component?name=&version=&package_type=` (add `cluster_id=` to narrow it to one cluster), `ankra security sbom component <name> --version <v> --type <ecosystem> [--cluster <name>]`, and the `get_security_sbom_component` AI tool.

**Images** lists every image with a bill of materials: OS, component count, its licence risk (the obliging tiers it carries), the workloads, clusters and namespaces running it, the actionable findings attributed to it, and when the bill of materials was generated. Opening an image shows its identity (reference, digest, registry, CycloneDX version), the workload containers running it, its **Vulnerabilities** - every CVE the scanner names on the image, one row per CVE and installed package version across every container running it, with the fixed version, the CISA KEV listing and EPSS probability, the worst disposition across its occurrences and where it runs, each opening the finding for its advisory and remediation plan - then its full component list with the same search, ecosystem and findings-first controls, and two **Download** buttons: a CycloneDX 1.5 JSON document (what Dependency-Track, Grype and licence scanners ingest) or a flat CSV, rebuilt from the stored components and complete rather than paged. The counts on the image summary open the lists they count: the component count the components, the findings and known-exploited counts the vulnerabilities, the workload count the containers running the image.

**Containers** starts from the other end: every container the clusters are running *right now*, init containers included, joined to the bill of materials of its image - or marked **No bill of materials** when the scanner has none for it. Those rows sort first, because they are the gap to close: a cluster with SBOM generation switched off, a registry the scanner cannot pull from, or a tag that rolled since the last scan. The headline counts running containers, how many have a bill of materials and how many do not, before the status chips or the search narrow the list, so the figure holds while you drill. Column headers sort like every other list in the portal.

Every view scopes by **cluster**, **namespace** and **workload** (the resolved Deployment, StatefulSet, DaemonSet or CronJob; a bare pod matches its own name), so "what does this deployment ship" is one filter away. The coverage headline above a scoped list is that scope's, not the fleet's, and every figure in it links to the list it counts - components, images, workloads, the packages a finding names, the containers with and without a bill of materials, the clusters publishing one - so a number is never a dead end.

An application's **Security** section carries the same data per version on its **SBOM** view: one row per pushed tag of each component's image, with the bill of materials the scanner holds for it (and the obliging licence tiers it carries), the findings currently attributed to it (known-exploited and fixable-severe counts included), where it is running, and which sources saw it - so a tag nobody deployed, a deployed tag with no bill of materials, and a scanned tag the registry no longer lists stay distinguishable. The CycloneDX and CSV downloads sit on each row.

The pane also reads the licences against the application's own repository. When the repository is **private** and the newest scanned version of a component links a network-copyleft package, a **Licence obligation** notice says so in plain terms - hosting that version as-is obliges you to publish its source, or to move the package behind a separate service - and lists the packages, each opening the image's bill of materials filtered to that tier. A source-available package raises the same notice whatever the visibility, because a managed service needs a commercial licence either way; GPL packages get a quieter note about distribution. A public repository has already met the disclosure obligation and the notice says that instead; a repository the platform has not synced is treated as private until someone confirms otherwise, never as public. The same verdict is on the API (`repository.visibility`, `license_exposure.source_disclosure_required`, `license_exposure.service_licence_required` and the flagged `components` on `GET /org/applications/{id}/security/versions`).

The bill of materials is **opt-in per cluster** (see [Prerequisites](#prerequisites)). The tab's coverage line says how many scanned clusters publish one, and the empty state names the input to turn on, so an empty inventory reads as a switch nobody has flipped rather than a fleet with no packages. Images are keyed by digest and their components stored once, so an image running on ten clusters costs one bill of materials; an image no cluster runs any more keeps its last bill of materials but shows no workloads.

The API exposes `GET /api/v1/org/security/sbom` (components; `search`, `package_type`, `vulnerable`, `cluster_id`, `namespace`, `workload_kind`, `workload_name`, `image`, `sort`, `order`), `GET /api/v1/org/security/sbom/images` (the same scope), `GET /api/v1/org/security/sbom/image?image=<digest or reference>`, `GET /api/v1/org/security/sbom/containers` (`cluster_id`, `namespace`, `workload_kind`, `workload_name`, `status=present|absent`, `search`; the response carries an `inventory` block counting the scope), `GET /api/v1/org/security/sbom/image/export?image=<identity>&format=cyclonedx|csv` (a download), and `GET /api/v1/org/security/sbom/image/findings?image=<identity>` (the CVEs on one image: `search`, `severity`, `sort`, `order`, paging; `image.sbom_status` says whether a bill of materials is stored, and a `summary` block totals the image before the filters narrow the rows). Every read carries a `coverage` block with `scanned_clusters` against `clusters_with_sbom`, scoped the way the list is. Namespace rows on `GET /api/v1/org/security/namespaces` carry `sbom_images`, the distinct images running there with a bill of materials. Per application, `GET /org/applications/{id}/security/versions` lists the image versions.

From the terminal, `ankra security sbom`, `ankra security sbom images`, `ankra security sbom image <image>`, `ankra security sbom findings <image>` (the CVEs on one image, `--severity` repeatable), `ankra security sbom containers` and `ankra security sbom export <image> [--format csv]` read the same data; every one takes `-o json`, and the inventories take `--cluster`, `--namespace`, `--workload-kind` and `--workload-name`. From chat or the MCP server, the tools are `list_security_sbom_components`, `list_security_sbom_images`, `get_security_sbom_image`, `list_security_sbom_image_findings` and `list_security_sbom_containers`.

### Policies

Organisation-wide disposition rules: active, expiring, fix-available, mitigated, unmatched, expired, and revoked. Edit, renew, or soft-revoke with a fresh server-side match preview.

**From the CLI and MCP.** `ankra security dispositions` lists the policies (`--status` and `--disposition` repeatable, `--sort updated_at`), `ankra security dispositions preview --occurrence <id> --disposition accepted_risk` shows what a decision would cover, `ankra security dispositions create --occurrence <id> --disposition acknowledged|accepted_risk --reason "…" [--expires-at 2026-12-31] [--expire-when-fix-available]` writes it after printing that preview and asking (`--yes` skips the prompt), `--scope workload` or `--scope image` on either records it for a finding no add-on owns (see [what a disposition is pinned to](#what-a-disposition-is-pinned-to)), and `update <policy-id>` / `revoke <policy-id> --reason "…"` carry the lifecycle. From chat or the MCP server the tools are `list_security_dispositions`, `preview_security_disposition`, `create_security_disposition`, `update_security_disposition` and `revoke_security_disposition`; the three writes are confirmed before they run and re-check `security.triage` or `security.manage` exactly as the portal does.

### Network Exposure

How tightly a cluster's NetworkPolicies are scoped, in and out. Identity - not port or CIDR - is what excludes an attacker, so a workload with no policy, or an allow-rule broader than a named workload identity, counts as over-privileged.

Ingress and egress are scored separately, each from 0 to 100, and each blends two halves:

| Half | Question |
| - | - |
| Coverage | How many workloads are selected by any policy in that direction? |
| Tightness | Of the rules that admit traffic, how many are scoped to a named workload identity? |

A rule counts as broad unless every peer is identity-scoped. An `ipBlock` on ingress, a `namespaceSelector`, an empty selector, or a missing `from` / `to` all make a rule broad.

Findings list every unprotected workload and every broad rule, ranked by severity with ingress before egress. Filter by flow, namespace, or severity. An unprotected workload is high severity on ingress and medium on egress, because egress default-deny is uncommon enough that its absence is exposure to review rather than an active misconfiguration.

> [!WARNING]
>
> This score reads your policy objects, never your traffic. It cannot tell you whether a policy is safe to apply, and three limits follow from that:
>
> * **Enforcement is not verified.** The score reflects how the policies are written, not whether your CNI enforces `NetworkPolicy` at all.
> * **A fully locked-down cluster and a broken one score identically.** A default-deny in every namespace with no allow-rules scores 100 out of 100 while blocking every flow in the cluster. Treat a high score as "policy is written tightly", not "the cluster is healthy".
> * **Coverage is partial.** Only Deployments, StatefulSets, and DaemonSets are inventoried, and ports are not scored.
>
> Use it to find workloads nobody has scoped yet. Do not use it to decide a policy change is safe - that needs observed traffic, which this metric does not have.

**From the CLI and MCP.** `ankra security network-exposure --cluster <cluster>` prints both scores with their coverage and tightness halves and the ranked findings; the tool is `get_cluster_network_policy_overprivilege`. Both are live reads through the agent, so an offline cluster answers with a retry hint rather than a stale score.

### Compliance

Fleet-wide benchmark scores for CIS Kubernetes, NSA/CISA hardening, and Pod Security Standards, alongside configuration-audit findings and report coverage. Filter for clusters that need attention, compare frameworks, and select a cluster to open its full Security workspace on the Compliance tab.

**From the CLI and MCP.** `ankra security compliance` is the fleet rollup, `ankra security compliance frameworks` lists GDPR, ISO 27001, SOC 2 and NIST CSF with each framework's switch and live score, `frameworks enable|disable <key>` flips one (`--yes` skips the prompt), `frameworks report <key> [--month 2026-08]` reads a report control by control, and `ankra security compliance export --format csv|json [--start-date --end-date] [--output-file]` downloads the [evidence report](/security/compliance-management#the-compliance-report). Per cluster, `ankra security benchmarks --cluster <cluster>` lists every failing control with its remediation and `benchmarks resources --cluster <cluster> --check <id> [--source config_audit]` the objects behind one control. From chat or the MCP server: `get_security_compliance_overview`, `list_security_compliance_frameworks`, `get_security_compliance_framework_report`, `set_security_compliance_framework` (confirmed, `security.manage`) and, per cluster, `get_compliance_reports`.

***

## Cluster Security view

Each cluster Security page shares the same domain model, scoped to that cluster:

* Quiet scanner/freshness status with refresh and secondary actions ([schedule a report](/guides/security-reports), create an alert).
* **Stacks** — the cluster broken down the way Ankra deployed it, and the tab the page opens on when the cluster runs stacks. One row per stack with its attribution status, scope (add-ons · manifests · matched workloads · unmatched members), actionable findings with the fixable severe count, the known-exploited count, and how many of its running containers have a bill of materials; a closing **Outside any stack** row counts the system namespaces, node images and hand-applied objects no stack owns, so the rows add up to the cluster. Every figure opens the list it counts, already narrowed to the stack, and the stack name opens the stack's own [Security tab](#stack-security), where a member drills on to its workloads and pods. The summary strip above the table (actionable in stacks, known exploited, stacks with a gap to close, containers without a bill of materials) links the same way. A stack whose members matched nothing reads **Unmatched**, never clean. A cluster with no stack opens on the Overview instead, and `?tab=` in the URL always wins.
* **Overview** — the exploited-in-the-wild banner, the actionable summary, and then the breakdowns: a **Known exploited (CISA KEV)** card (how many of this cluster's findings CISA lists as exploited, their share of its actionable occurrences, how many are past CISA's deadline or used in ransomware, and the exploited findings themselves with their deadlines), the **Risk breakdown** (severity mix, review state, fix readiness), the ranked remediation list, the cluster's **Application hotspots** (workloads ranked by weighted actionable risk), and the trend.
* **Findings** — server-side list and detail sheet with acknowledge / accept-risk flows, including the KEV markers, EPSS scores, and exploitability sort.
* **Workloads** — risk explorer with namespace and add-on filters. The organisation-wide [Workloads](#workloads) tab adds the namespace and pod levels above and below it.
* **Network Exposure** - the same NetworkPolicy scoping scores and findings described above, for this cluster alone.
* **Compliance**: failed and passed benchmark checks, configuration-audit hotspots, scanner remediation, and **Fix with AI** actions.

Use the Compliance filters to focus by result, severity, framework, check ID, or remediation text. Failed checks show affected results and scanner guidance. Passed checks stay collapsed by benchmark until you need evidence for an audit.

***

## Stack security

A stack's detail page has a **Security** tab built around what makes the stack up: its running pods, each under the add-on or manifest that deploys it, and every container of every pod with its own CVE report, bill of materials and KEV report one click away.

The stack is attributed to running objects two ways, one per member kind. An **add-on** is a Helm release, so every object in the cluster's resource cache carrying that release's identity - the `meta.helm.sh/release-name` annotation with its release namespace, or the `app.kubernetes.io/instance` label the chart stamped - belongs to it, whether or not the chart is in the add-on catalog. A **manifest** is the objects its YAML declares, matched by kind, namespace and name. From those objects the scope walks two owner levels down (Deployment → ReplicaSet → Pod, CronJob → Job → Pod), because the scanner reports on the controller that owns the pods, not the object you wrote.

The tab has three views, and the view and its filters live in the page URL so a container's report can be handed to someone as a link:

* **Pods** (the default) - a posture strip on top: actionable occurrences by severity, the **known-exploited** count, the fixable severe count, the component count and how many of the stack's running containers have a bill of materials, each figure opening the list it counts. Below it the running pods, grouped under the member that deploys each. A pod names its namespace, its owner workload (linked to the workload page), its priority and when it was last seen, then every container and init container: image, scan state, actionable findings by severity, KEV count, bill of materials, and three openers - **CVE**, **SBOM** and **KEV** - into the container's dedicated view. Search matches pod, namespace, member, workload, container and image; a member chip narrows to one add-on or manifest; a member with no running pod attributed is listed as unmatched, never dropped. A stack past the read's container cap says the listing is partial.
* **Findings** - the stack's CVEs with the same severity, status, known-exploited and fix-available filters, sorts and detail sheet as the Security Center, and facet counts computed for the stack alone.
* **Components** - every package in the images the stack's pods run, searchable, with a **Vulnerable only** switch and the findings that name each component.

The pods list is also the way down through Kubernetes. Under a member's heading, **Show workloads** lists the workloads that member deploys - the Deployments, StatefulSets, DaemonSets, CronJobs and Jobs its release identity or declared objects resolved to - each with its pods, scan state, severe actionable findings, known-exploited count and how many of its containers have a bill of materials. A workload opens on its own **Security** tab, its **Bill of materials** link opens the Security Center's containers list scoped to that workload, and **Show pods** lists the pods it runs right now, each opening on the pod's [Security tab](#pod-security). Every link from a security surface to a Kubernetes object lands on that object's Security tab rather than its overview, so the path cluster → stack → member → workload → pod → container never leaves the security view. The workloads read is `GET /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security/workloads`; the cluster's stack list is `GET /org/clusters/imported/{cluster_id}/security/stacks`, both with `/api/v1` twins. On the CLI, `ankra security stacks --cluster <cluster>` prints the stack list, `ankra security stack <name> --cluster <cluster>` the stack with its members and their workloads, and `ankra security pod <namespace> <pod> --cluster <cluster>` one pod container by container; Ankra AI and the MCP server answer the same questions through `list_cluster_security_stacks`, `get_cluster_stack_security` and `get_cluster_pod_security`.

The tab never renders an absent answer as a clean one. A cluster the scanner has not reported on reads **not scanned** and its containers are still listed, each marked **Not scanned**; a stack whose members resolve to no object in the resource cache reads **unmatched** (it may not be deployed yet, or its workloads carry no Helm release identity); pods that were attributed but carry no report yet read **no reports yet**; and when the CISA catalog has not been synced, every known-exploited figure reads unknown rather than zero. The summary is on the API as `GET /org/clusters/imported/{cluster_id}/stacks/{stack_name}/security`, with `/pods`, `/findings` and `/sbom` lists beside it and `/api/v1` twins for API tokens.

### The container view

Every container - opened from the stack's pods, from the pod's Security tab, or by link - has one dedicated view with three sections named in the URL (`section=cve`, `sbom` or `kev`):

* **CVE report** - every CVE the scanner names on the container's image, one row per CVE and installed version, with severity, exploitation (CISA listing and EPSS), installed and fixed versions, disposition and where else the image runs; each opens the finding and its advisory.
* **Bill of materials** - the image's components with the findings that name each exact version, searchable and filterable by ecosystem, with the **CycloneDX** and **CSV** downloads. A container whose image has no stored bill of materials says so as a state to act on, with the opt-in guidance, rather than showing an empty list.
* **KEV report** - the same CVE list filtered to the CISA Known Exploited Vulnerabilities catalog, with the remediation deadline each carries. While the catalog has not been synced the report reads **unknown**, never empty.

Around the reports is the ring of links that closes the circle: the pod's Security tab, the stack and the member that deploy the pod, the owning workload's page, the image in the Security Center's SBOM tab, every container running the same image, and the findings of the namespace. A container no report covers is marked **Not scanned** in the view's header, and the CVE figure reads *not scanned* rather than zero.

***

## Pod security

A pod's detail page has a **Security** tab (shortcut `s`) that reads the pod container by container: every container and init container it runs, each with the CVEs the scanner attributes to the workload container behind it and the bill of materials of its image. The owner chain is walked the way the namespace breakdown walks it (Pod → ReplicaSet → Deployment, Pod → Job → CronJob), so a Deployment's report on its ReplicaSet reaches the pod. When one of the cluster's stacks deploys the pod, the tab says which stack and which add-on or manifest, linked back to that stack's pods.

The summary shows the pod's actionable occurrences by severity, how many of its containers the scanner covers, the known-exploited and fixable-severe counts, and how many containers have a bill of materials with the component and image totals. The **By container** table lists init containers first with the image, readiness and restarts, the scan state, actionable findings by severity, the KEV count and the bill of materials (components and OS, or **Absent**), and the same three openers as the stack's pods - **CVE**, **SBOM**, **KEV** - into the container view described above, named in the URL (`container=` and `section=`) so it can be linked to directly.

Nothing absent reads as clean: a container no report covers is marked **Not scanned**, a container whose image has no stored bill of materials reads **Absent** and its SBOM view explains what is missing, a pod with neither reads **no report yet**, an unscanned cluster says so, an unsynced CISA catalog leaves the known-exploited figure unknown, a pod nothing in a stack deploys simply carries no stack line, and a pod whose stacks' members could not be read says the stack is **unknown** rather than pretending there is none. The same read is on the API as `GET /org/clusters/imported/{cluster_id}/security/pods/{namespace}/{pod_name}` - its `stack` field names the deploying member or is null, and `stack_attribution` says what that null means (`attributed`, `none` or `unknown`) - with an `/api/v1` twin for API tokens.

***

## Add-on security posture

On a stack add-on's **Overview**, a compact Security panel shows:

* Actionable critical/high counts, the known-exploited (CISA KEV) count, and the accepted-risk count
* Affected images and workloads
* Scan freshness and scanner setup states
* Partial-attribution warnings when ownership cannot be proven for every report

Cluster-scoped and ambiguous reports are **not** attributed to an add-on. The panel's **Open in Security** action deep-links into the cluster Security view filtered by that add-on's slug. A security API failure never blocks the operational add-on overview.

**From the CLI and MCP.** `ankra security addon <addon-name> --cluster <cluster>` reads the same panel, and `get_cluster_addon_security` is the tool. Per application, `ankra application security-versions <application> [--component <name>]` and `get_application_security_versions` list every pushed image version with its bill of materials, findings and licence exposure.

***

## Acknowledge vs accept risk

Two distinct dispositions are available for a finding:

| Disposition | Effect |
| - | - |
| **Acknowledged** | Reviewed, but still **actionable** and alertable |
| **Accepted risk** | Excluded from actionable totals, remediation queues, and threshold alerts; still visible in observed/accepted totals |

Accepted risk requires:

* A reason
* An actor (recorded in audit)
* A review deadline, maximum one year
* Optionally, automatic expiry when a fix becomes available

Matching uses a deterministic selector: organisation + CVE + package type + package name + what the disposition is pinned to. Creation always shows a server preview of affected findings, clusters, ambiguous exclusions, and the observed→actionable count change. Policies are never hard-deleted; they can be revoked, expire, mitigate when no matches remain, or reopen if findings return.

### What a disposition is pinned to

A disposition is created from one occurrence of a finding, and its scope decides what it covers:

| Scope | Covers | Needs |
| - | - | - |
| `organisation_addon` (default) | The add-on the occurrence belongs to, on every cluster (for example, Grafana across the fleet) | The occurrence attributed to an add-on with high confidence |
| `workload` | The one workload it was seen in: cluster, kind, namespace and name | A workload recorded on the occurrence |
| `image` | The image digest it was seen in, wherever that image runs | An image digest recorded on the occurrence |

Some images belong to no add-on: pods an operator creates from a custom resource (a CloudNativePG `Cluster`, for example), workloads from plain manifests, control-plane pods, and charts the add-on catalogue does not know. The default scope refuses those, and the refusal names the two scopes that work. Use `workload` to decide for one place, or `image` to decide once for an image that runs in several namespaces or clusters:

```bash theme={null}
ankra security dispositions preview --occurrence <id> --scope workload --disposition accepted_risk
ankra security dispositions create --occurrence <id> --scope image --disposition accepted_risk \
  --reason "No upstream fix; reviewed" --expires-at 2026-12-31
```

An image-scoped disposition follows the digest, so it stops matching when the image is rebuilt or upgraded and the finding returns for a fresh decision. From chat or the MCP server, pass the same `scope` to `preview_security_disposition` and `create_security_disposition`.

> [!WARNING]
>
> Expiry or fix availability can make findings actionable again and may fire threshold alerts. It does **not** emit a false “new CVE discovered” notification — “new” means newly observed in raw scan data **and** currently actionable.

***

## Permissions

| Permission | Who can use it (built-in defaults) | Capabilities |
| - | - | - |
| `security.read` | Viewer and above | View Security Center, cluster Security, add-on posture |
| `security.triage` | Operator, admin, owner | Acknowledge findings |
| `security.manage` | Admin, owner | Accept risk, create/edit/revoke organisation policies |

Custom roles may grant these permissions. Backend enforcement is authoritative; the UI only gates controls.

All disposition mutations are audited and write append-only policy events in the same transaction.

***

## Ask Ankra AI

The AI assistant can read the same vulnerability and compliance data. Three entry points open chat already grounded in what you are looking at:

| Action | Where | What it sends |
| - | - | - |
| **Fix top findings with AI** | Organisation Overview | The top remediation candidates with their severity, package, reach, and fix availability, and a request for a prioritised fleet remediation plan |
| **Ask Ankra AI** | Any finding detail sheet | The finding and the cluster the occurrence was seen on |
| **Fix with AI** | A failed compliance check | The check, benchmark, severity, affected count, and remediation |

The agent can inspect affected Kubernetes resources, propose or apply safe changes, and verify the result. Risky or disruptive changes still require confirmation.

> [!NOTE]
>
> Product analytics for these actions record only that an AI action happened, through a strict allowlist. CVE identifiers, finding titles, prompts, and workload names are never sent.

```text theme={null}
What are the most critical actionable vulnerabilities in this cluster?
Which single image upgrade fixes the most high-severity CVEs?
Why is CIS check 1.1.1 failing, and can you fix the affected resources?
```

The assistant distinguishes observed, actionable, acknowledged, and accepted-risk findings. Accepted risk is never treated as “gone.”

***

## Related

> [card] [Add-ons](/concepts/addons)
>
> Install Trivy Operator and other add-ons.

> [card] [Roles and access](/guides/roles-and-access)
>
> Grant security.read, security.triage, and security.manage.

> [card] [AI Assistant](/platform/ai-assistant)
>
> Triage vulnerabilities in chat.

> [card] [AI Insights](/platform/ai-insights)
>
> Proactive cluster health analysis.


# Connect to a Managed Service
Source: https://docs.ankra.ai/guides/connect-to-a-managed-service

How an application on the service's cluster receives its connection as environment variables, when Ankra delivers it without a redeploy and when a deploy does, the variable names for each service, and how to connect an application on another cluster by hand.

> [!WARNING]
>
> **Closed beta.** Connecting to a service is part of [Managed services](/concepts/managed-services), which is in closed beta and enabled per organisation on request. [Contact support](/platform/support) to have it turned on for your organisation.

A managed service answers only inside its own cluster, at fixed addresses in its namespace. It keeps the credentials it generated in a Secret in that namespace, and a workload can read a Secret only in its own namespace.

Ankra connects your application for you when it runs on the same cluster as the service: once the service is ready, Ankra copies the connection into the application's namespace, and the application's containers read it as environment variables such as `DATABASE_URL`. The copy happens inside the cluster, and Ankra never sees the values. An application on another cluster is not connected for you: give it the values yourself, as in [Connect from another cluster](#connect-from-another-cluster).

***

## How your application receives the connection

Every application environment a service was set up for, on the service's cluster, receives the service's connection in two parts:

1. A Secret named `<service>-connection` in the application's namespace, with `<service>` standing for the service name. Ankra copies its values inside the cluster from the service's own credentials Secret.
2. A reference to that Secret, which a deploy of the application adds to every container and init container of its Deployments, StatefulSets and DaemonSets through `envFrom`, so each of the Secret's keys becomes an environment variable. The names are listed under [Variable names](#variable-names). A deploy adds the reference while the service is still being set up too. The reference is optional, so the application starts while the Secret does not exist yet.

Once the service has generated its credentials, Ankra writes the Secret by itself, without redeploying or restarting anything, but only while no running pod of the application references the Secret: pods restarting one by one would otherwise read different values. What the application needs then depends on its state:

* **The workloads reference the Secret but none of their pods runs**, for example because they are scaled to zero: Ankra writes the Secret, and each pod reads the variables when it starts.
* **The workloads do not reference the Secret**, because the application was deployed before the service was connected: Ankra writes the Secret, and the application reads it after its next deploy adds the reference.
* **Running pods reference the Secret**, for example because the application was deployed while the service was being set up: Ankra leaves the Secret to a deploy. Deploy the application once the service is ready: the deploy writes the Secret and rolls the workloads that reference it together onto it.
* **Running pods read the Secret but started before it existed**: they run without its variables until they restart. Ankra never restarts them by itself.
* **A variable the connection would add is defined twice**, by the connection and by another source the workloads read, such as one of the application's environment secrets: the connection is not delivered, by Ankra on its own or by a deploy, until you remove the other definition or choose another service, or none, to provide those names, as under [Variable names](#variable-names).

The service's page shows each environment's state under **Use it in \<application>**, with the platform's reason beside it. The label follows `pickup`, described below, when the platform sent one, and the delivery's `state` when it did not:

| In the portal | In the API | Meaning |
| - | - | - |
| **Connects when the service is ready** | `pickup` `waiting_for_service` | Ankra delivers the connection once the service has generated its credentials. Nothing to do. |
| **Ankra is connecting it now** | `pickup` `delivering` | Ankra is writing the Secret into the application's namespace, without a redeploy or a restart. Nothing to do. |
| **Waiting for someone to choose a service** | `pickup` `holder_gone`, or a `holder_gone` entry on the delivery | The service that gave the environment names such as `DATABASE_URL` no longer serves it. **Choose the service** opens the application, where you choose which service provides them, or none, as under [Variable names](#variable-names). |
| **Waits for its next deploy** | `pickup` `redeploy_needed`, not delivered yet | Ankra leaves the connection to a deploy. **Deploy \<environment>** opens the application to deploy it. |
| **Delivered, its workloads do not read it yet** | `pickup` `redeploy_needed`, `state` `delivered` | The Secret is in the application's namespace, but the running workloads do not read it yet. **Deploy \<environment>** opens the application to deploy it. |
| **Waiting for a variable defined twice to be resolved** | `pickup` `redeploy_needed` with `name_collisions`, not delivered yet | A deploy would not deliver it either, so none is offered. Remove the other definition, or choose another service, or none, to provide those names, as under [Variable names](#variable-names). |
| **Connected, its workloads need a restart** | `pickup` `restart_needed` | Running pods read the Secret but started before it existed. Restart them: Ankra never restarts them by itself. |
| **Connected** | `pickup` `in_use`, or `state` `delivered` without a `pickup` | The `<service>-connection` Secret is in the application's namespace. |
| **Not connected yet** | `state` `pending` without a `pickup` | Not delivered yet. The reason says what it waits for. |
| **Connect by hand** | `state` `unsupported` | Ankra does not connect this environment, usually because it runs on another cluster. The reason is shown. See [Connect from another cluster](#connect-from-another-cluster). |
| **Not known** | `state` `unknown` | Ankra could not read the delivery. It does not mean the connection is missing. |
| **Not known** | a `pickup` the portal does not recognise yet, on a connection not delivered yet | The platform reported how far the delivery is in a way this portal does not know. The reason beside it says what it waits for. |

A deploy usually connects the workloads, but not every one: see the note on Jobs, CronJobs and `ankra.io/deploy-overrides` below.

The same state is in the API, on each of `consumers` in [Get a managed service instance](/api-reference/services/get-a-managed-service-instance), as `connection_delivery` with the `secret_name`, the `variables` the application receives and a `reason`. Its `pickup` says how far the environment is from running with the connection, and `reason` says what to do:

| `pickup` | Meaning |
| - | - |
| `waiting_for_service` | The service is still being set up or has not generated its credentials. Ankra delivers the connection once it has. |
| `delivering` | The credentials exist and no running pod references the connection, so Ankra is writing it into the application's namespace, without a redeploy or a restart. |
| `holder_gone` | Delivery waits for you to choose which service provides the names without a prefix, as under [Variable names](#variable-names). |
| `redeploy_needed` | Deploy the application. If `name_collisions` lists variables, first remove their other definition or choose another service, or none, to provide them: until then a deploy does not deliver the connection either. Otherwise the cause is one of these, and a deploy resolves each: the Secret is there but no running workload references it yet; running pods already reference it, so Ankra does not write it on its own; or another connection written with it is left to a deploy. |
| `restart_needed` | Running pods read the Secret but started before it existed, so they lack its variables until they restart. Ankra never restarts them by itself. |
| `in_use` | Every running pod that reads the Secret started after it existed. |

`pickup` is absent when Ankra could not read it, and for a consumer it does not connect, such as one on another cluster.

A workload annotated `ankra.io/deploy-overrides: "none"` keeps the manifest you committed, so it gets no `envFrom` reference. The `<service>-connection` Secret is still written to its namespace: reference it from the workload yourself. Jobs and CronJobs are not given the reference either.

When a service is [deleted](/guides/delete-a-managed-service), the application's next deploy removes its `<service>-connection` Secret and the reference to it.

To take one application off a service that keeps running for its other applications, [disconnect it](/guides/disconnect-an-application-from-a-managed-service). Its next deploy removes the reference and rolls its workloads, and Ankra removes the `<service>-connection` Secret once no pod reads it.

> [!WARNING]
>
> **Do not also set a delivered variable as an environment secret.** If the application already has, say, `DATABASE_URL` as an [environment secret](/reference/cli/application#ankra-application-env-secrets), Ankra does not deliver the connection, on its own or in a deploy, and `name_collisions` names the variable. Delete the copy with `ankra application env-secrets delete <application-id> DATABASE_URL` and apply the secrets again with `ankra application env-secrets apply <application-id>`, or choose another service, or none, to provide `DATABASE_URL`. If a name is set twice after the connection was delivered, `reason` says how to resolve it.

## Variable names

Each service delivers the variables its kind of client conventionally reads:

| Service | Variables | Values |
| - | - | - |
| PostgreSQL | `DATABASE_URL`, `JDBC_DATABASE_URL`, `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD` | `DATABASE_URL` and `JDBC_DATABASE_URL` carry the user and password, and name the read-write address. `PGHOST` is `postgresql-rw.<service>.svc.cluster.local`. |
| Valkey | `REDIS_URL`, `REDIS_HOST`, `REDIS_PORT`, `REDIS_USERNAME`, `REDIS_PASSWORD` | `REDIS_URL` is a complete `redis://` URL for the primary. |
| NATS | `NATS_URL`, `NATS_USER`, `NATS_PASSWORD` | `NATS_URL` carries no credentials. |
| OpenSearch | `OPENSEARCH_URL`, `OPENSEARCH_USERNAME`, `OPENSEARCH_PASSWORD`, `OPENSEARCH_CA_CERT` | `OPENSEARCH_CA_CERT` is the PEM text of the service's CA certificate, not a file path. |
| SeaweedFS (S3) | `S3_ENDPOINT`, `AWS_ENDPOINT_URL_S3`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `S3_FORCE_PATH_STYLE` | Both endpoint variables are `http://seaweedfs-all-in-one.<service>.svc.cluster.local:8333`. The key pair is the admin pair. `AWS_REGION` is `us-east-1` and `S3_FORCE_PATH_STYLE` is `true`. |
| VictoriaLogs | `VICTORIA_LOGS_URL`, `VICTORIA_LOGS_USERNAME`, `VICTORIA_LOGS_PASSWORD` | |
| VictoriaMetrics | `VICTORIA_METRICS_URL`, `VICTORIA_METRICS_USERNAME`, `VICTORIA_METRICS_PASSWORD` | |

Every service also delivers each variable under its own prefix: the service name in capitals, with hyphens as underscores. A PostgreSQL service named `orders-db` delivers `ORDERS_DB_DATABASE_URL`, `ORDERS_DB_PGHOST` and so on.

The names without a prefix go to one service of each kind per application environment: the one connected first, recorded the first time a deploy gives it those names. An application with one database reads `DATABASE_URL`. When a second PostgreSQL service is added for the same environment, `DATABASE_URL` keeps pointing at the first, and the second is read through its prefixed names only. Valkey and any other Redis-compatible service count as one kind, as they share `REDIS_URL`.

The names without a prefix never move to another service by themselves. If the service that provides `DATABASE_URL` is retired while another PostgreSQL service still serves the environment, the application's next deploy is refused and nothing is deployed: giving `DATABASE_URL` to the other database would make the application read and write a different database without anyone choosing that. The service's page shows the same warning on the application. Choose which service provides the names, or choose none so the application reads only the prefixed names, then deploy again:

* Ankra AI or MCP: `set_service_connection_default` with the application, cluster, namespace, the kind (`postgres`, `redis`, `nats`, `opensearch`, `s3`, `victorialogs` or `victoriametrics`) and the service's instance id, or `none: true`.
* API: `PUT /api/v1/org/service-admission/connection-defaults` with `application_id`, `cluster_id`, `namespace`, `protocol` and `instance_id` (`null` for none).

If no other service of that kind serves the environment, the deploy goes ahead without the names and says so on its result. A service of that kind connected later then provides them.

The refusal starts as soon as the deletion of the service that provides the names has begun, not only once it has finished: from then on, while another service of that kind serves the environment, its deploys are refused, so the running application keeps what it read at its last deploy. While no other service of that kind serves it, deploys keep delivering the names from the service being deleted until its credentials are removed, and the deploy that stops delivering them says so.

A service set up again under the name of a retired one is a new service, not the old one: it does not hold the retired service's data. If the retired one provided `DATABASE_URL`, the deploy is refused in the same way and says so; choose the new service explicitly once you have moved the data. Removing the application's deployment from the namespace forgets which service Ankra recorded as providing the names, so a new deployment there starts fresh; a service you chose yourself stays chosen.

***

## Find the connection details

Open the service in **My services**. Its **Connect** section shows:

* the namespace, which is the service name;
* each address, with a **Copy** button;
* the name of the Secret that holds the credentials;
* under **Read a credential yourself**, for each key in that Secret, an Ankra CLI command that prints its value, with a **Copy** button. The command names the service's cluster and also uses `jq`, as in [Read a value](#read-a-value).

The portal never shows the values themselves. The details are derived from the service's package, not observed on the cluster, so they are shown as soon as the service is set up: the addresses answer once the service is running. The section is not shown for a deleted service or while a service is being deleted.

The same details are on the service in the API, as `connection` on [Get a managed service instance](/api-reference/services/get-a-managed-service-instance): the `namespace`, the named `endpoints` and the `secret` with its `name` and `keys`. They follow a fixed pattern for each service, below, with `<service>` standing for the service name.

## Addresses and Secrets

| Service | Address | Secret | Keys |
| - | - | - | - |
| PostgreSQL | Read-write: `postgresql-rw.<service>.svc.cluster.local:5432` Read-only: `postgresql-ro.<service>.svc.cluster.local:5432` | `postgresql-app` | `fqdn-uri`, `fqdn-jdbc-uri`, `username`, `password`, `dbname`, `port` |
| Valkey | Primary: `valkey.<service>.svc.cluster.local:6379` Read replicas: `valkey-read.<service>.svc.cluster.local:6379` | `valkey-credentials` | `url`, `username`, `password`, `host`, `port` |
| NATS | `nats://nats.<service>.svc.cluster.local:4222` | `nats-credentials` | `url`, `username`, `password` |
| OpenSearch | `https://opensearch.<service>.svc.cluster.local:9200` | `opensearch-credentials` | `url`, `username`, `password`, `ca.crt` |
| SeaweedFS (S3) | `http://seaweedfs-all-in-one.<service>.svc.cluster.local:8333` | `seaweedfs-s3-secret` | `admin_access_key_id`, `admin_secret_access_key`, `read_access_key_id`, `read_secret_access_key` |
| VictoriaLogs | `http://victoria-logs.<service>.svc.cluster.local:9428` | `victoria-logs-credentials` | `url`, `username`, `password` |
| VictoriaMetrics | `http://victoria-metrics.<service>.svc.cluster.local:8428` | `victoria-metrics-credentials` | `url`, `username`, `password` |

The addresses resolve from any namespace on the service's cluster, and not from outside it. On a cluster with a custom DNS domain, use the shorter `<name>.<service>.svc` form, for example `valkey.<service>.svc:6379`. Of the delivered variables, `DATABASE_URL`, `JDBC_DATABASE_URL`, `PGHOST`, `S3_ENDPOINT` and `AWS_ENDPOINT_URL_S3`, and their prefixed copies, use the full `svc.cluster.local` form, so on such a cluster they do not resolve: give the application short-form values for them yourself, as in [Connect from another cluster](#connect-from-another-cluster), under variable names the delivery does not use. The other delivered addresses, in `REDIS_URL`, `REDIS_HOST`, `NATS_URL`, `OPENSEARCH_URL`, `VICTORIA_LOGS_URL` and `VICTORIA_METRICS_URL`, already use the short form and resolve there.

Resolving is not reaching: on their current package versions, PostgreSQL, Valkey, NATS, OpenSearch and SeaweedFS admit their client port only from the service's own namespace, the namespace of the cluster's Ankra agent and the namespaces of the applications connected to the service, where the cluster's network plugin enforces NetworkPolicy. See [How a service runs](/concepts/managed-services#how-a-service-runs).

## Read a value

You need a value only to connect something Ankra does not connect for you. Select the service's cluster, then read the Secret by name with `--reveal`, using the Secret and namespace from the table:

```bash theme={null}
ankra cluster select <cluster>
ankra cluster get secrets <secret> -n <service> --reveal -o json
```

Without `--reveal`, every value comes back as a `sha256:` digest. `--reveal` needs the `kubernetes.secrets_reveal` permission on the cluster, which the operator, admin and owner roles carry, and every reveal is recorded in the organisation's audit log. Values under `data` stay base64-encoded.

For a PostgreSQL service named `orders-db`, this prints its password:

```bash theme={null}
ankra cluster get secrets postgresql-app -n orders-db --reveal -o json | jq -r '.data["password"]' | base64 -d
```

A key with a dot in its name, such as OpenSearch's `ca.crt`, works the same way:

```bash theme={null}
ankra cluster get secrets opensearch-credentials -n search --reveal -o json | jq -r '.data["ca.crt"]' | base64 -d > opensearch-ca.crt
```

## Connect from another cluster

An application on another cluster than the service is not connected for you, and the service's addresses do not resolve there. Reaching the service from another cluster needs a network path between the clusters that you provide, and the address that path exposes. A service whose client port admits only the namespaces named under [Addresses and Secrets](#addresses-and-secrets) also needs a NetworkPolicy of your own in its namespace that admits the traffic of that path.

Give the application the values as [environment secrets](/reference/cli/application#ankra-application-env-secrets), from the service page's **Use it in \<application>** button, which opens the application's **Settings › Secrets**, or from the CLI. Piping the value keeps it out of your shell history:

```bash theme={null}
ankra cluster get secrets postgresql-app -n orders-db --reveal -o json \
  | jq -r '.data["password"]' | base64 -d \
  | ankra application env-secrets set <application-id> PGPASSWORD
ankra application env-secrets apply <application-id>
```

Storing a value does not reach a running workload: `env-secrets apply` seals the stored values into the application's deployments and rolls them. The URL keys, such as PostgreSQL's `fqdn-uri`, name the in-cluster address, so build the URL your application uses from your own network path's address rather than copying them.

For a workload that is not an Ankra application, keep the Secret in Git and encrypt it with [SOPS](/guides/sops).

A value you copy this way is yours: [deleting the service](/guides/delete-a-managed-service) does not remove it from the application. Delete it yourself once the application no longer uses the service.

## Notes per service

* **PostgreSQL.** `DATABASE_URL` and `JDBC_DATABASE_URL` carry the operator's `fqdn-uri` and `fqdn-jdbc-uri`. The operator also writes `uri`, `jdbc-uri` and `host` keys, but they name the short host `postgresql-rw`, which resolves only inside the service's own namespace. You connect as `app`, the owner of the database `app`, and superuser access is off. The read-only address reaches replicas only, so it answers only when `instances` is above 1, and no variable names it. The image includes the pgvector and pgaudit extensions.
* **Valkey.** Authenticate as the `app` user, which `REDIS_USERNAME` carries, with `REDIS_PASSWORD`; `REDIS_URL` is a complete `redis://` URL that carries both. Write to the primary address. The read-replicas address serves reads from every pod.
* **NATS.** Connect as `app`. `NATS_URL` carries no credentials, so pass `NATS_USER` and `NATS_PASSWORD` separately. JetStream is on; memory-backed streams are disabled.
* **OpenSearch.** Use HTTPS with basic auth as `admin`, the only user. The certificate is signed by a private CA generated in the cluster: have your client trust `OPENSEARCH_CA_CERT`, which holds that CA's certificate.
* **SeaweedFS.** Use the S3 API over plain HTTP inside the cluster, with path-style addressing. The admin key pair, the one delivered, can read, write, list and administer buckets. The read-only key pair can only read, and is in the service's Secret only.
* **VictoriaLogs.** Send logs over HTTP with basic auth, as JSON lines, Loki push, OpenTelemetry or Elasticsearch bulk, and query them with LogsQL. No log collector is installed, so ship logs with your own agent.
* **VictoriaMetrics.** Push metrics with basic auth using Prometheus `remote_write`, OpenTelemetry, InfluxDB or another supported protocol, and query with PromQL or MetricsQL on the Prometheus HTTP API. It scrapes nothing itself, so push from vmagent, a Prometheus agent or an OpenTelemetry Collector.

## Check that the service answers

A finished deployment is not yet a ready service. The service's **Service health** section says whether its workload runs as planned, which does not prove a client can connect. Ankra checks that a client can connect for every service it publishes, about every five minutes, and shows the result as the service's **Readiness**: see [Health and readiness](/concepts/managed-services#health-and-readiness). Until readiness reads **Ready**, or while it reads **Not verified** because the cluster's agent is too old to run the check, check the service yourself before you rely on it. Its pods run in its namespace:

```bash theme={null}
ankra cluster get pods -n <service>
```

A PostgreSQL service can report its deployment finished 30 to 100 seconds before the database accepts connections. Check the database itself until its `Ready` condition is `True`:

```bash theme={null}
ankra cluster describe Cluster postgresql -n <service> --group postgresql.cnpg.io
```

About every five minutes, a service's namespace also holds a short-lived pod: labelled `app.kubernetes.io/name=ankra-postgres-connection-test` for PostgreSQL, and `app.kubernetes.io/name=ankra-service-canary` for every other service. That is Ankra's readiness check, which connects the way an application would; it is deleted when it finishes.

## Next steps

> [card] [Managed service settings](/reference/managed-services)
>
> What each setting changes, with its range and default.

> [card] [Managed services](/concepts/managed-services)
>
> How the services run, their health and readiness, and their current limits.

> [card] [Disconnect an application](/guides/disconnect-an-application-from-a-managed-service)
>
> Take one application off a service that keeps running for the others.

> [card] [Delete a managed service](/guides/delete-a-managed-service)
>
> What deleting removes and keeps, and how to confirm it.


# Create a Registry
Source: https://docs.ankra.ai/guides/create-a-registry

Host your own Helm charts on GHCR and add the registry to Ankra so your charts appear as add-ons.

> [!TIP]
>
> Adding your own registry to Ankra enables you and your team to distribute Helm charts as add-on components that can be deployed onto a cluster as part of a stack.

## Create your own registry with GitHub

> [!NOTE]
>
> **Use any OCI Helm registry** ([GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), [Harbor](https://goharbor.io/docs/), [JFrog Artifactory](https://www.jfrog.com/confluence/display/JFROG/Helm+Chart+Repositories), [AWS ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/push-oci-artifact.html), [Google Artifact Registry](https://cloud.google.com/artifact-registry/docs/helm), etc.) with Ankra. This guide focuses on GitHub Container Registry (GHCR) as a free and accessible example.

GitHub Container Registry (GHCR) provides a free and reliable way to host your own Helm charts.

### Prerequisites

Before you begin, ensure you have:

* A GitHub account
* Git installed on your machine
* Helm CLI installed ([Installation guide](https://helm.sh/docs/intro/install/))
* A GitHub Personal Access Token with `write:packages` permission

> [!NOTE]
>
> To create a Personal Access Token: Go to GitHub Settings > Developer settings > Personal access tokens > Generate new token, and select the `write:packages` scope.

### Step 1: Set Up Your Repository

Create a new GitHub repository to host your Helm charts:

1. Go to GitHub and create a new repository (e.g., `my-helm-charts`)
2. Clone the repository locally:

```bash theme={null}
git clone https://github.com/YOUR_USERNAME/my-helm-charts.git
cd my-helm-charts
```

### Step 2: Create Your Helm Chart

Generate a new Helm chart or prepare an existing one:

```bash theme={null}
# Create a new chart
helm create my-sparkly-app

# Or copy an existing chart to your repository
# cp -r /path/to/existing/chart ./my-sparkly-app
```

This creates a basic chart structure:

```
my-sparkly-app/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ...
└── charts/
```

### Step 3: Configure Your Chart

Edit the `Chart.yaml` file to include proper metadata:

```yaml theme={null}
apiVersion: v2
name: my-sparkly-app
description: A Helm chart for my sparkly application
type: application
version: 1.0.0
appVersion: "1.0.0"
home: https://github.com/YOUR_USERNAME/my-helm-charts
sources:
  - https://github.com/YOUR_USERNAME/my-helm-charts
maintainers:
  - name: Your Name
    email: your.email@example.com
```

### Step 4: Package Your Chart

Package your Helm chart into a `.tgz` file:

```bash theme={null}
helm package my-sparkly-app
```

This creates a file like `my-sparkly-app-1.0.0.tgz`.

### Step 5: Login to GHCR

Authenticate with GitHub Container Registry using your Personal Access Token:

```bash theme={null}
echo $GITHUB_TOKEN | helm registry login ghcr.io -u YOUR_USERNAME --password-stdin
```

Replace `$GITHUB_TOKEN` with your actual token and `YOUR_USERNAME` with your GitHub username.

### Step 6: Push Your Chart

Push your packaged chart to GHCR:

```bash theme={null}
helm push my-sparkly-app-1.0.0.tgz oci://ghcr.io/YOUR_USERNAME/helm-charts
```

### Step 7: Verify your registry

After pushing, your chart will be available at:

```
oci://ghcr.io/YOUR_USERNAME/helm-charts/my-sparkly-app
```

You can verify the upload by checking your GitHub repository's "Packages" tab.

### Step 8: Add your registry to Ankra

Now that your chart is published, add your GHCR registry to Ankra:

**1. Create a registry credential**

Go to **Credentials** → **Add** → **Registry** and enter your GitHub username and the Personal Access Token (with `read:packages` scope). See [Credentials](/platform/credentials/registry) for details.

**2. Add the registry**

Go to the **Add-ons** page in the main navigation, click **Manage registries** → **Add**, and enter:

* **URL**: `oci://ghcr.io/YOUR_USERNAME/helm-charts`
* **Credential**: the registry credential you just created

**3. Sync and verify**

Ankra syncs the registry and indexes your charts. Your chart (e.g. `my-sparkly-app`) now appears in the add-on catalog, ready to drop into any stack.

## Use Your Chart in a Stack

Open the Stack Builder on any cluster, click **+ Add** → **Add-on**, and search for your chart. Configure its values, connect any dependencies, and deploy.

## Next Steps

> [card] [Helm Registries](/integrations/helm-registries)
>
> Connect other registry types - Harbor, Artifactory, ECR, and more.

> [card] [Stacks](/concepts/stacks)
>
> Compose your charts with manifests and dependencies into reusable stacks.


# Delete a Managed Service
Source: https://docs.ankra.ai/guides/delete-a-managed-service

Delete a managed service through a reviewed plan - acknowledge the environments that lose it and its data, check exactly what is removed and kept, type its name to confirm, then follow the deletion to its receipt.

> [!WARNING]
>
> **Closed beta.** Deleting a service is part of [Managed services](/concepts/managed-services), which is in closed beta and enabled per organisation on request. [Contact support](/platform/support) to have it turned on for your organisation.

Deleting a managed service removes its stack from the cluster, then deletes its namespace with the data in it. It takes two steps: you acknowledge what the deletion does, Ankra prepares a plan of exactly what is removed and kept, and you confirm that plan by typing the service's name. Nothing is deleted until you confirm. To take one application off a service that keeps running for its other applications, [disconnect the application](/guides/disconnect-an-application-from-a-managed-service) instead.

> [!WARNING]
>
> **Deleting a service deletes its data, and it cannot be undone.** The service's namespace is deleted with every volume claim and Secret in it, including the credentials the service generated, and anything else placed in that namespace, even objects Ankra did not create. No export is made first. Copy out anything you need before you confirm.

***

## Prerequisites

* **The installation has finished.** A service whose status is **Installation requested** or **Deployment in progress** cannot be deleted yet. A service whose installation or deployment needs attention can be.
* **Your role allows it:**

| Permission | Where |
| - | - |
| `applications.deploy` | Your organisation |
| `clusters.operate`, `stacks.delete` and `clusters.read` | The cluster the service runs on |
| `clusters.read` | The cluster of every application environment the service serves |

The built-in `owner`, `admin` and `operator` roles hold all of them. Without them the service's page shows no **Delete service** section, and the deletion page says **Your role cannot delete this service.** See [Roles and access](/guides/roles-and-access).

***

## What is removed and what is kept

| Removed | Kept |
| - | - |
| The service's stack and every member of it | Shared operators the service needed, such as the CloudNativePG operator (stack `cloudnative-pg`), because other services may use them |
| The service's namespace, which is the service name, with every volume claim and Secret in it | Restore points already taken, in their backup vault, until the vault's retention removes them |
| The service's link to each application environment it serves | Volumes on a StorageClass with reclaim policy `Retain`: they stay released, with their data, until you remove them |
| | The applications themselves, and anything in their namespaces, including the delivered `<service>-connection` Secret until the application deploys again |
| | The service's record in **My services**, as history |

The volumes behind the deleted claims are erased where the StorageClass reclaims them with reclaim policy `Delete`, the usual default.

The `<service>-connection` Secret Ankra delivered into each connected application's namespace stays until that application's next deploy, which removes it and the application's reference to it. Values you set by hand, as in [Connect from another cluster](/guides/connect-to-a-managed-service#connect-from-another-cluster), stay until you delete them. Applications still configured with the service's address lose their connection.

***

## Delete the service

**1. Open the service**

In the new Ankra portal, open **Managed services**, then **My services**, and choose the service. The **Delete service** section is at the bottom of its page. Choose **Delete service**.

**2. Acknowledge what the deletion does**

Under **Environments that lose this service**, tick each application environment the service serves. Each one stops using the service; the application itself is not changed.

Then tick **I understand that deleting `<service>` deletes its data and generated credentials, and that no export is made first.**

Choose **Review deletion**. Reviewing prepares a plan. It deletes nothing.

**3. Review the plan**

The plan is what the platform resolved for this service, and what the deletion will do:

* **Service**, **Cluster** and **Namespace deleted**.
* **Removed from the cluster**: the stack, and each member with the namespace it deploys into.
* **Environments that lose it**: each application environment the service serves.
* **Kept**: shared stacks the service needed, such as the CloudNativePG operator.
* **What happens to the data**: the platform's statement of what is deleted, including whether volumes on a `Retain` StorageClass stay behind.

If nothing was ever deployed for the service, the plan says so: deleting it then removes nothing on the cluster and only releases its name.

**4. Type the name and confirm**

Type the service's name exactly in **Type `<service>` to confirm**, then choose **Delete service**. Confirm within the review window, **10 minutes** after the plan was prepared; the page shows when it ends. When the window passes, **Review again** prepares a fresh plan for the same acknowledgements.

**Start over** returns to the first step. A plan you do not confirm expires on its own and deletes nothing. Each person can hold at most 10 deletion reviews waiting for confirmation, and each organisation 50.

***

## Follow the deletion

After you confirm, the service's page shows **Deletion confirmed.** and the deletion's progress, one step at a time:

1. **Removing the service's stack**
2. **Waiting for the cluster to remove the stack**: Ankra waits up to an hour for the cluster's agent to report every member removed.
3. **Deleting the service's namespace and its data**: Ankra first checks that no other Ankra-managed workload deploys into the namespace, then deletes it and waits up to 30 minutes to see it gone.

**My services** shows the service as **Deleting**. **View cluster operations** opens the cluster's operations with the detail. The service's health and connection details are no longer shown once the deletion starts.

***

## Verify

When the namespace is gone, the page becomes a **Service deleted** receipt with the status **Deleted**: the stack was removed, the namespace was deleted and seen gone from the cluster, and the name was released. The receipt lists what is kept, and **My services** shows the service as **Retired**.

To check the cluster yourself, select it and look for the namespace and the volumes:

```bash theme={null}
ankra cluster select <cluster>
ankra cluster get namespaces --name <service>
ankra cluster get resources PersistentVolume -o json
```

The namespace is no longer listed. On a StorageClass with reclaim policy `Retain`, the service's volumes are left with status `Released`. Delete them once you no longer need their data.

The name is free again. A new service set up under the same name on the same cluster generates new credentials and starts with none of the old data.

### When data may remain

A deletion can release the service's name while Ankra cannot show that its data is gone. The receipt then reads **Service deleted, but its data may remain**, and **My services** shows the service as **Deleted, data may remain**. The status says which case it is:

| Status | What it means |
| - | - |
| **Deleted, data kept** | When Ankra looked after deleting the namespace, at least one of the service's persistent volumes still held its data, because the volume's reclaim policy kept it. |
| **Deleted, data not confirmed gone** | Ankra cannot show that the data is gone: a volume could not be read, a volume claim had no volume when the deletion was reviewed, not every claim could be listed, the service had no namespace of its own, or its cluster was deleted in Ankra, which does not prove its storage was destroyed. |

Its **Data that may remain** section says what to do and lists the volumes that may still hold the data, with Ankra CLI commands to copy: one to see what a volume holds, one to list the cluster's persistent volumes when Ankra could not name every one, and, for a volume Ankra saw kept, one to delete it with its data. Ankra looks once, after the namespace is gone, and does not check again, so a listed volume may have been removed since. Before you delete a volume, inspect it and confirm that its `spec.claimRef.namespace` is the service's namespace and its `status.phase` is `Released`.

***

## When a deletion stops short

Only **Deleted** removes the service. Any other outcome leaves the service and its name in place, says why under **What happened**, and the **Delete service** section offers **Review the deletion again**.

| Outcome | What it means | What to do |
| - | - | - |
| **Deletion did not finish** | Removing a member of the service's stack failed on the cluster, or did not finish within an hour. The data may still be there. | Ankra keeps retrying the removal. Check the cluster's operations; once the members are gone, review the deletion again. It continues from where the stack is. |
| **Data not confirmed deleted** | The stack is gone, but the namespace was not deleted: another Ankra-managed workload deploys into it (the reason names it), or the deletion was not accepted or not seen finished within 30 minutes. The data is still on the cluster. | Move the named workload out of the namespace, or bring the cluster's agent back online. A namespace stuck in `Terminating` is usually waiting on a finalizer. Then review the deletion again. |
| **Deletion stopped** | The person who confirmed lost the permissions above, or the stack changed outside Managed services after the review. Nothing further was removed. | Review the deletion again. |
| **Deletion interrupted** | The deletion's operation was cancelled or timed out. | Review the deletion again. |

***

## A service's stack is deleted through the service

The service owns its stack. Deleting the stack directly - in the portal, through the API, with `ankra cluster stacks delete` or by asking the AI Assistant - is refused with:

```text theme={null}
Stack '<service>' belongs to managed service '<service>'; retire the service instead of deleting its stack.
```

Delete the service instead, as above.

> [!NOTE]
>
> Removing a service's stack from the cluster's GitOps repository is not refused yet. It removes the service's deployment while the service and its name stay in **My services**. Delete the service from its page instead.

## A cluster or application a service depends on

While a managed service has not been deleted, deleting the cluster it runs on, or an application it serves, is refused too: through the API with `409`, with `ankra cluster delete`, and by the AI Assistant and MCP tools `delete_cluster` and `delete_application`. The refusal names the services, for example:

```text theme={null}
This cluster hosts managed service 'orders-db'. Retire it before deleting the cluster, so its data is removed through a reviewed retirement. Retiring needs the applications.deploy permission, clusters.read, clusters.operate and stacks.delete on the service's cluster, and clusters.read on the cluster of every application it serves; the operator, admin and owner roles have them. If the retirement itself keeps being refused, contact Ankra support. If the cluster cannot be reached, deleting it is allowed once its agent has been offline for 15 minutes; retiring it afterwards releases its name.
```

Delete the services first, as above, then delete the cluster. A cluster whose agent has been offline for 15 minutes can be deleted with its services in place, since no deletion could reach them; deleting such a service afterwards only releases its name, and it reads **Deleted, data not confirmed gone**. Destroying a playground is never refused for the services on it.

An application does not need its services deleted. [Disconnect it](/guides/disconnect-an-application-from-a-managed-service#deleting-an-application-or-removing-its-binding) from each service the refusal names, which leaves each service running for its other applications, or delete those services. Then delete the application.

***

## Delete through the API

The API calls a deletion a **retirement**. It takes the same two steps, with an [API token](/api-reference/introduction) whose holder has the permissions above:

1. Read the service with [Get a managed service instance](/api-reference/services/get-a-managed-service-instance) for its `generation` and the `id` of each of its `consumers`.
2. [Prepare a managed-service retirement review](/api-reference/services/prepare-a-managed-service-retirement-review) with `expected_generation`, `disconnect_consumer_ids` (every consumer id, each once) and `acknowledge_data_loss: true`. The answer carries the plan, its `digest` and its `expires_at`, 10 minutes later. Nothing changes on the cluster. It also carries `connection_names`, whose `environments` lists each application environment on the service's cluster that reads names such as `DATABASE_URL` from this service, with a `statement` of what happens to them: read each one before you confirm. `complete` is `false` when an environment could not be read. See [Variable names](/guides/connect-to-a-managed-service#variable-names).
3. [Confirm a managed-service retirement by its digest](/api-reference/services/confirm-a-managed-service-retirement-by-its-digest) with that `digest`. Confirming again with the same digest returns the same receipt, never a second deletion.
4. Follow `retirement` on the service, or [Get a managed-service retirement](/api-reference/services/get-a-managed-service-retirement): its `phase` while it runs, then its `outcome` and `reason`. Only the outcome `retired` deleted the service. With that outcome, `data_disposal` says what became of the data: `complete` only when Ankra can show it is gone, and `data_kept` or `unconfirmed` when it may remain, as under [When data may remain](#when-data-may-remain). `kept_data` then lists the volumes and the Ankra CLI `commands` for them.

***

## Troubleshooting

| What you see | Cause | Remedy |
| - | - | - |
| `You can delete this service once its installation has finished.` | The installation or its deployment is still running | Wait until **My services** shows the service out of **Installation requested** and **Deployment in progress** |
| `Your role cannot delete this service.` | You lack one of the [permissions](#prerequisites), on the service's cluster or an environment's cluster | Ask an administrator for access |
| `This review has expired.` | The 10-minute window passed | **Review again** |
| `Something this deletion covers changed after you reviewed it.` or `The service changed since this page read it.` | The plan no longer matches the service | **Review again** |
| `The environments this service serves changed.` | An environment started or stopped using the service after you acknowledged | **Start over** and acknowledge the current environments |
| `The service's stack was changed outside Managed services` | The stack was renamed or replaced, so Ankra cannot tell it is still the service's own | Give the stack the service's name again, then review the deletion again |
| `Part of the service's stack deploys outside the service's own namespace` | A member added to the stack deploys into another namespace, or names none, so deleting the service's namespace would leave data behind | Remove that member from the stack, or deploy it into the service's namespace, then review again |
| `You have too many deletion reviews waiting.` | 10 reviews of yours, or 50 in the organisation, are waiting | Confirm one, or let them expire after 10 minutes |
| `An application is still being disconnected from the service; retire it once the disconnection has finished` | A [disconnection](/guides/disconnect-an-application-from-a-managed-service) of one of its applications has not finished: deleting the service would remove the source of the connection Secret it keeps in place for pods that still read it | Wait until the disconnection has finished, as under [Follow the disconnection](/guides/disconnect-an-application-from-a-managed-service#follow-the-disconnection), then review the deletion again |
| `We could not tell whether the review was prepared.` | The answer to **Review deletion** was lost | A review may be waiting. It expires within 10 minutes and deletes nothing. Review the deletion again when you are ready |
| `Ankra cannot delete services on this cluster right now.` | Ankra is not starting operations on the service's cluster, for example shortly after a force stop | Try again later. Nothing was deleted |

***

## Next steps

> [card] [Managed services](/concepts/managed-services)
>
> How services run, their health and readiness, and their current limits.

> [card] [Set up a managed service](/guides/set-up-a-managed-service)
>
> Set up a service again, under the same name or a new one.


# Ship Your App
Source: https://docs.ankra.ai/guides/deliver-your-app

Get an application from a Git repository running on a cluster, and redeployed every time a change merges - pick the route that fits where your code lives and who builds the image.

You have an application in a Git repository. You want it running on a cluster, and you want every merge to the main branch rebuilt and redeployed without anyone running a command. Ankra has more than one way to do that, and the right one depends on where your code lives and how much of the pipeline you want Ankra to own. This page helps you pick one and points you to the guide for it.

***

## Pick your route

| Route | Your code lives on | Who builds the image | Deploys, and redeploys on merge |
| - | - | - | - |
| [**Applications**](#applications), with `ankra application ship` | GitHub | Ankra Pipelines in your own cluster (the default), the generated GitHub Actions workflow, your own workflow, or Ankra platform builders | Yes. Push to deploy is on from registration |
| [**Your own CI**](#bring-your-own-ci), committing the new tag to your GitOps repository | Anywhere. The GitOps repository must be on GitHub or Bitbucket Cloud | Your CI | Yes, once CI commits the tag and Ankra syncs it |
| [**Ankra Pipelines**](/guides/ankra-pipelines) on a repository that is not an application | GitHub, GitLab or Bitbucket Cloud | Nobody: `build` needs an application to push to | No. It runs CI only: with no application, `publish` has no repository to release into, so a `deploy` stage has nothing to roll out |
| [**Previews**](#preview-a-change-before-merge) of a pull request or branch | GitHub, as an application | Nobody: it deploys an image already built | A throwaway copy on your staging cluster, redeployed on every push |

In short:

* **Your repository is on GitHub and you want Ankra to handle the build and the deploy:** use Applications. It is the only route where Ankra writes the Dockerfile, the manifests and the CI definition for you.
* **You already have CI you want to keep, or your code is on GitLab:** keep your CI and have it commit the new image tag to the GitOps repository.
* **You want CI inside your own cluster:** [Ankra Pipelines](/guides/ankra-pipelines). To also deploy, connect the repository as an application; the pipeline then builds its image.

***

## Applications

An application is a GitHub repository Ankra builds and deploys. Registering one opens a setup pull request with a Dockerfile (when the repository has none), Kubernetes manifests and a CI definition. After you merge it, every successful build of the tracked branch rolls out to the clusters the application runs on. [Applications](/concepts/applications) explains the model in full.

### Ship from your checkout

One command takes a local checkout to a running deployment. Run it in a checkout whose `origin` remote is the GitHub repository, with a cluster selected (`ankra cluster select`) or named with `--cluster`:

```bash theme={null}
ankra application ship .
```

`ship` works through these steps and prints what it is waiting on at each one:

1. **Register.** If your organisation has no application for this repository yet, `ship` registers one, with the same flags as `ankra application add`. The GitHub credential and the branch are detected when you do not pass `--credential` and `--branch`.
2. **Wait for setup.** Ankra analyses the repository and opens the setup pull request. `ship` prints its URL.
3. **Wait for you to merge the setup pull request**, when the application builds with the GitHub Actions workflow Ankra generated. This is the one step that needs a person. An application built by Ankra Pipelines (the default for new applications) or by your own workflow skips it.
4. **Wait for the build** of the tracked branch: the Ankra pipeline run for the branch's head commit until its `publish` stage has pushed the image, or the GitHub Actions workflow run. A push to the branch during the wait moves `ship` on to the new head commit.
5. **Deploy** to the cluster, in a namespace derived from the application name unless you pass `--namespace`.
6. **Wait until the workload is running**, then print the public URL when the application has one.

An application whose setup runs a PostgreSQL database on the cluster needs the CloudNativePG operator there. The deploy installs it itself where the environment's **Who runs it** is **Ankra runs it**, which is the default for every environment but Production, and in a Production environment, whose default is **Together**, unless someone chose **You run it**. A deploy that could not set it up says so in a `Warning:` line. Anywhere else the deploy is refused with `The CloudNativePG operator is not installed on this cluster` and nothing is applied: run `ship` again with `--set-up-database`, which needs `stacks.write` on the cluster, or add the Postgres (CloudNativePG) add-on to the cluster yourself.

`--timeout` bounds all the waiting together (one hour by default). Re-running `ship` is safe at any point: it reads where the flow stands and carries on from there, so an interrupted run resumes instead of registering, building or deploying twice. Add `-o json` to get the application, cluster, namespace and URL as JSON on stdout.

#### The first build, with nothing pushed yet

If nothing starts a pipeline run for the head commit within a minute - nothing was pushed since the application was registered - `ship` asks Ankra for the run a push to the tracked branch would have started, for the branch's current head. That run publishes the image, so `ankra application ship .` reaches a running URL without a push. Starting that run needs permission to deploy applications (`applications.deploy`).

A run that skips `publish` for any other reason stops `ship` instead of deploying without an image. Push a commit to the tracked branch and run `ship` again, or pass `--ankra-build` to build the first image on [Ankra platform builders](/concepts/applications#building-on-ankras-builders), which Ankra enables per organisation.

### How a merge redeploys

Push to deploy is on for every new application from the moment it is registered. Once the application has been deployed once - by `ship` or by `ankra application deploy` - every successful build of the tracked branch rolls out to every cluster it is installed on, with no approval step. A successful build is whichever of these the application uses:

* an Ankra pipeline run whose `publish` stage re-tagged the image as `sha-<7>` in your registry,
* a completed, successful run of the generated GitHub Actions workflow or of your own workflow,
* an Ankra platform build.

A build of any other branch never deploys. With push to deploy off, a merge still builds; the new image just waits for an explicit `ankra application deploy`.

Check and change the switch from the CLI:

```bash theme={null}
# On or off, the branch it watches, and the newest build seen there
ankra application auto-deploy get <application-id>

# Turn it off, or back on
ankra application auto-deploy set <application-id> --enabled=false
ankra application auto-deploy set <application-id> --enabled
```

In the portal the same switch is the application's **Settings** → **Push to deploy**. Once the application runs in more than one environment, that section lists each one under **What follows pushes** with its own switch, so you can let staging follow every merge while production waits for an explicit deploy. Changing the switch needs permission to deploy applications; reading it does not. Each environment can also follow its own branches - production `main`, staging `release/*`, development `develop` - see [Environments and branch rules](/guides/application-environments).

> [!NOTE]
>
> Applications registered before push to deploy became the default keep the setting they had, which is off unless someone turned it on. Run `ankra application auto-deploy get` to check.

### Where the image is built

The setup pull request decides what builds the application, and that choice also decides which images a preview can use.

| Builder | What it is | What it publishes |
| - | - | - |
| **Ankra Pipelines** (default for new applications) | `.ankra/pipeline.yaml`, run as Jobs in the cluster your organisation runs CI on. Needs that cluster set up first - see [Before your first run](/guides/ankra-pipelines#before-your-first-run) | A pull request run builds and scans the head commit and pushes it by digest to a staging repository. A push to the tracked branch also runs `publish`, which re-tags the approved digest as `sha-<7>` in the application's registry |
| **Generated GitHub Actions workflow** | `.github/workflows/build-and-publish.yml`, for a repository that must keep building on GitHub. See [Application CI/CD](/guides/cicd-pipeline) | A pull request builds and scans the image but pushes nothing. A push to the tracked branch pushes `sha-<7>` and a tag named after the branch |
| **Your own workflow** | A workflow you wrote that pushes the image the application deploys | Whatever tags your workflow pushes |
| **Ankra platform builders** | Builds a commit on Ankra's infrastructure, on request: `ankra application build start <application-id> --commit <full-sha>`, or `ship --ankra-build` | `sha-<7>` for the commit you asked for |

For previews this means:

* A **pull request preview** of a pipeline-built application deploys the digest the pipeline built for that pull request's head. Nothing else is needed.
* A **pull request preview** of any other application needs an image tagged `sha-<7>` of the head commit, `pr-<number>` or the branch name in the application's registry. The generated workflow never pushes one for a pull request, so those previews only work when your own CI pushes such a tag.
* A **branch demo** deploys a tag that already exists. With the generated workflow or the generated pipeline, only the tracked branch gets one; for any other branch, build its head on platform builders or pick an existing tag.

### Preview a change before merge

Two features deploy a throwaway copy of a change to your organisation's staging cluster before it merges:

* [PR preview environments](/guides/pr-preview-environments) deploy every pull request automatically, post a status comment with the link, redeploy on each push and tear the copy down when the pull request closes.
* [Branch demos](/guides/branch-demos) launch a copy of any branch by hand, with its own environment variables, an optional throwaway Postgres and a teardown timer.

***

## Bring your own CI

Keep the CI you have. Your pipeline builds and pushes an image with a tag that never changes, commits the new tag to the cluster's GitOps repository, and Ankra syncs the commit into the cluster. CI never needs credentials for the cluster itself.

Before you start:

* **Connect a GitOps repository to the cluster** under the cluster's **Settings** → **GitOps**. It must be on [GitHub](/integrations/github#connecting-github) or [Bitbucket Cloud](/integrations/bitbucket-cloud#connecting-a-repository-to-a-cluster): Ankra does not sync cluster configuration from GitLab. Your application code and CI can live anywhere.
* **Deploy the application once as a manifest in a Stack.** Ankra writes it to `clusters/<cluster-name>-<short-id>/stacks/<stack-name>/manifests/<manifest-name>.yaml` in the GitOps repository. That is the file your CI edits.
* **Give CI a token that can push to the GitOps repository**, and nothing more. On GitHub, a fine-grained personal access token with **Contents** read and write on that one repository.
* **Let the cluster pull the image.** For a private registry, add an image pull secret to the Stack (encrypt it with [SOPS](/guides/sops)) and reference it from the Deployment.

Both examples below build on every push to `main`, tag the image with the commit, and replace the `image:` line in the manifest. Replace `my-org/my-app`, `my-org/my-gitops-repo` and the manifest path with your own.

> [tab] GitHub Actions
>
> `.github/workflows/deploy.yml` in the application repository, pushing to GitHub Container Registry and bumping a GitOps repository on GitHub:
>
> ```yaml theme={null}
> name: build-and-deploy
> on:
>   push:
>     branches: [main]
>
> permissions:
>   contents: read
>   packages: write
>
> env:
>   IMAGE: ghcr.io/my-org/my-app
>   MANIFEST: clusters/my-cluster-<short-id>/stacks/my-app/manifests/my-app.yaml
>
> jobs:
>   build-and-deploy:
>     runs-on: ubuntu-latest
>     steps:
>       - uses: actions/checkout@v4
>
>       - name: Build and push an immutable tag
>         run: |
>           TAG="sha-${GITHUB_SHA::7}"
>           echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
>           docker build -t "$IMAGE:$TAG" .
>           docker push "$IMAGE:$TAG"
>           echo "TAG=$TAG" >> "$GITHUB_ENV"
>
>       - name: Check out the GitOps repository
>         uses: actions/checkout@v4
>         with:
>           repository: my-org/my-gitops-repo
>           token: ${{ secrets.GITOPS_TOKEN }}
>           path: gitops
>
>       - name: Commit the new tag
>         working-directory: gitops
>         run: |
>           sed -i "s|image: ${IMAGE}:.*|image: ${IMAGE}:${TAG}|" "$MANIFEST"
>           git config user.name "ci-bot"
>           git config user.email "ci-bot@users.noreply.github.com"
>           git commit -am "Deploy my-app ${TAG}"
>           git push
> ```

> [tab] GitLab CI
>
> `.gitlab-ci.yml` in the application repository, pushing to the GitLab Container Registry and bumping a GitOps repository on GitHub. Store the token as a masked, protected CI/CD variable named `GITOPS_TOKEN`:
>
> ```yaml theme={null}
> stages: [build, deploy]
>
> variables:
>   IMAGE: $CI_REGISTRY_IMAGE
>   MANIFEST: clusters/my-cluster-<short-id>/stacks/my-app/manifests/my-app.yaml
>
> build:
>   stage: build
>   image: docker:27
>   services: [docker:27-dind]
>   rules:
>     - if: $CI_COMMIT_BRANCH == "main"
>   script:
>     - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
>     - docker build -t "$IMAGE:sha-$CI_COMMIT_SHORT_SHA" .
>     - docker push "$IMAGE:sha-$CI_COMMIT_SHORT_SHA"
>
> deploy:
>   stage: deploy
>   image: alpine:3.20
>   needs: [build]
>   rules:
>     - if: $CI_COMMIT_BRANCH == "main"
>   script:
>     - apk add --no-cache git
>     - git clone "https://x-access-token:${GITOPS_TOKEN}@github.com/my-org/my-gitops-repo.git" gitops
>     - cd gitops
>     - 'sed -i "s|image: ${IMAGE}:.*|image: ${IMAGE}:sha-${CI_COMMIT_SHORT_SHA}|" "$MANIFEST"'
>     - git config user.name "ci-bot"
>     - git config user.email "ci-bot@example.com"
>     - git commit -am "Deploy my-app sha-${CI_COMMIT_SHORT_SHA}"
>     - git push
> ```
>
> The [GitLab CI/CD tutorial](/guides/gitlab-cicd-pipeline) walks through the same setup step by step, with a deploy key instead of a token.

After the commit lands, Ankra picks it up on the connected branch and applies it; the cluster's **GitOps** page shows the sync, and **Sync** there pulls it at once. Once CI has edited the file, its contents in Git no longer match what Ankra last wrote, so Ankra keeps the Git version from then on and later edits from the portal do not overwrite your tag - see [Hand-maintaining a file](/concepts/gitops#hand-maintaining-a-file).

To roll back, revert the commit in the GitOps repository.

***

## Next steps

> [card] [Applications](/concepts/applications)
>
> The application model: setup, registries, robot accounts, scanning and demos.

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> CI in your own cluster, and exactly which stages run today.

> [card] [PR preview environments](/guides/pr-preview-environments)
>
> A live copy of every pull request on your staging cluster.

> [card] [GitOps](/concepts/gitops)
>
> How Ankra syncs a cluster from its GitOps repository.


# DigitalOcean Clusters
Source: https://docs.ankra.ai/guides/digitalocean-clusters

Create a Kubernetes cluster on Droplets in your own DigitalOcean team, with Ankra installing and operating Kubernetes, ingress, TLS and DNS.

Choose DigitalOcean when your team already runs on DigitalOcean and you want a Kubernetes cluster whose control plane you own, on Droplets in your own account. Ankra creates the VPC, NAT gateway, bastion and Droplets, installs Kubernetes and the DigitalOcean cloud integration, and then operates the cluster for you - this is an **Ankra Managed** cluster. DigitalOcean bills you directly. If you would rather DigitalOcean ran the control plane, use [DOKS](/guides/doks-clusters) instead; [Managed Kubernetes](/guides/managed-kubernetes) compares the two.

## Before you start

* A **DigitalOcean personal access token** with read and write scope, stored as a [DigitalOcean credential](/platform/credentials/digitalocean). Tokens start with `dop_v1_`.
* An **SSH key credential** - your own public key, or one Ankra generates. See [SSH Key Credentials](/platform/credentials/ssh-key).
* Room in your account limits for the Droplets, a VPC, load balancers and volumes. Check them in the [DigitalOcean Control Panel](https://cloud.digitalocean.com/); DigitalOcean support raises them.

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **DigitalOcean** under **Ankra Managed**.
>
> **2. Credential & Region**
>
> Pick the DigitalOcean credential and an SSH key (or add either inline), and a region, for example `nyc3`, `fra1` or `lon1`.
>
> **3. Network & Compute**
>
> Keep or change the VPC range, then pick the bastion Droplet size (for example `s-1vcpu-1gb`), the control plane count (1 or 3) and size (for example `s-2vcpu-4gb`), and one or more worker node groups. The wizard shows each size's vCPUs, memory and monthly price.
>
> **4. Kubernetes**
>
> Keep **kubeadm** (the default, with Cilium) or pick **k3s**, and optionally the version. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) for the CNI and etcd options.
>
> **5. GitOps**
>
> Optionally connect a Git repository; Ankra commits the cluster's stacks to it. Skipping GitOps still deploys the DigitalOcean cloud controller manager and CSI driver. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind a DigitalOcean load balancer.
> * **Include Public DNS** - a delegated subdomain on `ankra.cc` with external-dns wired, so an ingress hostname under it gets its DNS record and TLS certificate automatically.
>
> **6. Details**
>
> Name the cluster, set its environment, and click **Create cluster**. A progress view follows the VPC, NAT gateway, bastion, Droplets, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials digitalocean create --name my-do-token   # prompts for the token
> ankra credentials digitalocean ssh-key create --name my-ssh-key --generate
>
> # What your credential can deploy
> ankra cluster digitalocean regions --credential-id <digitalocean-credential-id>
> ankra cluster digitalocean sizes --credential-id <digitalocean-credential-id> --region nyc3 --available-only
>
> ankra cluster digitalocean create \
>   --name my-cluster \
>   --credential-id <digitalocean-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --region nyc3 \
>   --control-plane-count 1 \
>   --control-plane-size s-2vcpu-4gb \
>   --worker-count 2 \
>   --worker-size s-2vcpu-4gb
> ```
>
> `--distribution k3s`, `--etcd-topology external` with `--etcd-node-count` and `--etcd-size`, `--include-networking=false` and the `--gitops-*` flags cover the other choices.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/digitalocean \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<digitalocean-credential-id>",
>     "ssh_key_credential_id": "<ssh-key-credential-id>",
>     "region": "nyc3",
>     "control_plane_count": 1,
>     "control_plane_size": "s-2vcpu-4gb",
>     "node_groups": [
>       {"name": "default", "instance_type": "s-2vcpu-4gb", "count": 2}
>     ],
>     "include_networking": true,
>     "include_dns": true
>   }'
> ```
>
> `worker_count` and `worker_size` are still accepted, and `node_groups` wins when both are given. Every field, default, region and common size is in the [DigitalOcean Reference](/reference/digitalocean).

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created in your account

* **A VPC** for all traffic between the Droplets.
* **A VPC NAT gateway**, set as the VPC's default route - the egress path for the nodes. DigitalOcean bills it separately; see [VPC NAT gateway pricing](https://docs.digitalocean.com/products/networking/vpc/details/pricing/).
* **A bastion Droplet** - the only Droplet with a public IP and the only SSH entry point. It carries no workload or egress traffic.
* **Control plane and worker Droplets** with private IPs only, and dedicated etcd Droplets for a kubeadm cluster with external etcd.
* **Two tag-scoped cloud firewalls**, kept as defence in depth.
* **The `digitalocean-cloud-provider` stack**: the DigitalOcean cloud controller manager (load balancers for `LoadBalancer` Services) and CSI driver (block storage through the `do-block-storage` StorageClass), using your credential.

The [DigitalOcean Reference](/reference/digitalocean#architecture) has the full layout.

## DigitalOcean specifics

* **Clusters created before private-Droplet support** keep their original layout: every Droplet has a public IP and the tag-scoped cloud firewalls are the ingress boundary. Public networking is fixed when a Droplet is created, so those clusters - including nodes added when you scale them - stay on that model. Only new clusters get private nodes and a NAT gateway.
* **Resizing a node group** powers each Droplet off, resizes it and powers it on again, with brief downtime for its workloads. Droplet sizes only grow; for smaller nodes, create a new group and delete the old one.
* **A stop** deletes the node Droplets, the bastion and the VPC NAT gateway, and keeps the cluster's configuration, network definition and SSH keys. The block storage volumes the CSI driver created are kept and keep billing while the cluster is stopped.
* **Terminating** deletes the Droplets, NAT gateway, VPC and SSH keys. Anything left over from an earlier teardown can be removed in the [DigitalOcean Control Panel](https://cloud.digitalocean.com/).

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `digitalocean`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Cluster stuck in provisioning | Check the token's permissions and your account limits |
| Invalid API token | Create a new read and write token in the [DigitalOcean Control Panel](https://cloud.digitalocean.com/account/api/tokens) (prefixed `dop_v1_`) and [rotate the credential](/platform/credentials/digitalocean) |
| Droplet size unavailable | Try another region or size; `ankra cluster digitalocean sizes --available-only` lists what the region offers |
| Cannot scale workers | Check that the cluster is **Online** and no operation is running |
| `LoadBalancer` Service stuck in `Pending` | Check that the CCM runs in the `digitalocean-cloud-provider` namespace |
| PVCs stuck in `Pending` | Check that the CSI driver runs and the `do-block-storage` StorageClass exists |


# Disconnect an Application from a Managed Service
Source: https://docs.ankra.ai/guides/disconnect-an-application-from-a-managed-service

Take one application environment off a managed service that keeps running for its other applications - what the review shows, why nothing changes until the application's next deploy, when Ankra removes the connection Secret and the network access, and what disconnecting cannot do for each service.

> [!WARNING]
>
> **Closed beta.** Disconnecting an application is part of [Managed services](/concepts/managed-services), which is in closed beta and enabled per organisation on request. [Contact support](/platform/support) to have it turned on for your organisation.

Disconnecting takes one application environment off a managed service, while the service keeps running for its other applications. It takes two steps: Ankra prepares a review of exactly what the disconnection does, and you confirm it. Nothing changes until you confirm, and the running application is not touched until its next deploy. To remove the service itself, with its data, [delete it](/guides/delete-a-managed-service) instead.

> [!NOTE]
>
> In the new Ankra portal, you disconnect an application from the service's page, as under [Disconnect in the new Ankra portal](#disconnect-in-the-new-ankra-portal). The Ankra CLI disconnects one too, as under [Disconnect with the Ankra CLI](#disconnect-with-the-ankra-cli), and so does the API, as under [Disconnect through the API](#disconnect-through-the-api). You can also ask the AI Assistant or an MCP client, which use the tools `prepare_service_disconnection` and `confirm_service_disconnection`. In the AI Assistant, confirming always asks for your approval first, whatever its mode.

> [!WARNING]
>
> **Disconnecting does not revoke the application's credential.** All the applications connected to a service share one credential. The application keeps the one it has, and it can still use the service from any namespace the network still admits. To make sure it can no longer authenticate, rotate the service's credential, which changes it for every connected application. Ankra has no rotation for managed services yet. See [What disconnecting can and cannot do](#what-disconnecting-can-and-cannot-do).

***

## Prerequisites

* **The service is installed and not being deleted.** A service whose installation has not finished, or whose deletion was confirmed, cannot have an application disconnected from it.
* **No deploy of the application environment is in progress.** Wait for it to finish.
* **Your role allows it.** Disconnecting needs exactly what connecting the environment needed:

| Permission | Where |
| - | - |
| `applications.deploy` | Your organisation |
| `clusters.operate` | The cluster the service runs on |
| `clusters.operate` and `clusters.read` | The cluster the application environment runs on |

The built-in `owner`, `admin` and `operator` roles hold all of them. An API token needs them too, and its own scopes must allow them. See [Roles and access](/guides/roles-and-access).

***

## What happens, in order

1. **You confirm.** The service stops counting the environment among the applications it serves at once: it is no longer among the service's `consumers`, and it is listed under the service's `disconnections` until the disconnection has finished. Nothing changes on the cluster yet. The application keeps running with the connection it has.
2. **The application environment's next deploy.** The deploy removes the workloads' reference to the `<service>-connection` Secret and rolls them, as any deploy rolls a changed workload. When the environment had received the Secret, the deploy writes it again exactly as it was, so a pod started before the disconnection that restarts during the rollout still finds the values it started with. After this deploy, the workloads no longer receive the service's variables. Deploy the application now to finish sooner, or let its next deploy do it.
3. **Ankra removes the Secret once no pod reads it.** Every 15 seconds, Ankra checks whether any pod in the namespace reads the Secret, through `envFrom`, an environment variable's `secretKeyRef`, or a Secret or projected volume, terminating pods included, and whether any workload in the application's deployed manifest still refers to it. When two checks in a row, at least 10 seconds apart, find nothing, Ankra removes the Secret from the application's namespace. Removing it restarts nothing.
4. **Ankra takes the namespace off the service's client port**, unless you chose to keep network access or there is nothing to narrow, as under [Network access](#network-access). The disconnection has then finished, and records what Ankra observed.

Ankra restarts nothing by itself. The only pods that roll are the application environment's own workloads, in the deploy you run.

Ankra checks for readers only while the application's cluster is online, while no deploy of the environment is in progress, and while its view of the cluster's pods and Secrets is current, synced within the last 15 minutes. In a few cases it also waits for something else to settle first, for example the deletion of another service connected to the environment. Until then, the Secret stays.

> [!WARNING]
>
> **A workload whose reference to the Secret was written by hand keeps it in place.** Ankra removes only the reference a deploy attached. A workload that reads `<service>-connection` through a reference someone wrote keeps the disconnection waiting, and with it the Secret, because removing the Secret is the change that would break that workload. Nothing times out: change or remove such workloads yourself. Ankra also cannot see a workload deployed some other way that has no running pod, such as a CronJob between runs or a Deployment scaled to zero. Once the Secret is gone, such a workload starts without its values.

Disconnecting at once, before the next deploy, is not offered. The application would keep the shared credential it has, so cutting it off at once would only break it without revoking anything. A request with `timing` set to `now` is refused.

***

## What the review shows

The review is a plan the platform resolved for this environment. Each part carries a `statement`, the platform's own words for what the disconnection does. Read each one before you confirm.

| Part of the plan | What it says |
| - | - |
| `credential` | That the credential is shared, how many other application environments use it (`other_consumers`), and that Ankra cannot revoke it for this application alone. `cannot_guarantee` says what the application can still do with it, for this kind of service. |
| `rotation` | How to make sure the application can no longer authenticate: rotate the service's credential, which changes it for every connected application. |
| `connection_names` | Every variable the application stops receiving (`variables`). When this service gives names such as `DATABASE_URL`, who gives them from now on, as under [Names such as DATABASE\_URL](#names-such-as-database_url). |
| `connection_secret` | Whether the environment's deploys delivered the `<service>-connection` Secret (`delivered`). If they did, Ankra keeps it exactly as it is while pods still read it, and removes it once none does. If not, there is no Secret to remove. |
| `workloads` | The deployed workloads that read the Secret. Those in `attached_by_ankra` read it through the reference a deploy attached: the next deploy removes it and rolls them. Those in `written_by_hand` read it through a reference someone wrote: change them yourself, or they start without its values once it is gone, and a reference that is not optional keeps them from starting at all. `state` reads `not_stored` when Ankra has no copy of the deployed manifest and so cannot list them, and `not_deployed` when nothing is deployed in the environment. |
| `network` | Whether the namespace loses access to the service's client port, and why, as under [Network access](#network-access). |
| `data` | That nothing is deleted from the service. |
| `timing` | That the disconnection takes effect with the next deploy. `deploy_now_offered` is `true` when the environment has a deployment to deploy again. |
| `kept` | What stays after the disconnection has finished, as under [What stays](#what-stays). |

Beside the plan, `running_pods` lists the pods that read the Secret right now, read when the answer is served. It is not part of the plan, so it can change without the review changing.

An environment on another cluster than the service never received a connection from Ankra: `on_service_cluster` is `false`, confirming removes only the service's record of it, and the disconnection finishes at once.

***

## What disconnecting can and cannot do

Every service Ankra publishes gives all the applications connected to it one shared credential. A disconnection removes the connection Ankra delivered, the workloads' reference to it and, for most services, the namespace's network access. It never changes the credential.

| Service | The shared credential | Disconnecting removes | Disconnecting cannot guarantee |
| - | - | - | - |
| PostgreSQL | The password of `app`, the owner of the database | The delivered connection, the workloads' reference to it, and the namespace's access to port 5432 | The application keeps the owner's password and its full rights from any namespace the network still admits. The data it wrote stays in the database. |
| Valkey | The password of the `app` user | The delivered connection, the reference, and the namespace's access to port 6379 | The password does not change, and the keys the application wrote stay. |
| NATS | The password of the `app` user | The delivered connection, the reference, and the namespace's access to port 4222 | The password does not change, and the streams and consumers the application created stay. |
| OpenSearch | The `admin` password | The delivered connection, the reference, and the namespace's access to port 9200 | The admin password does not change, so from a namespace the network still admits the application could still administer the search cluster. Its indices stay. |
| SeaweedFS (S3) | The admin access keys | The delivered connection, the reference, and the namespace's access to port 8333 | The access keys do not change, and the objects the application wrote stay. |
| VictoriaLogs | The basic-auth password | The delivered connection and the reference | The client port is open to every namespace by design, so nothing changes on the network. The password does not change. |
| VictoriaMetrics | The basic-auth password | The delivered connection and the reference | The client port is open to every namespace by design, so nothing changes on the network. The password does not change. |

For every service:

* **Rotating the credential affects every connected application.** It is the only way to make sure the disconnected application can no longer authenticate, and Ankra has no rotation for these services yet.
* **The network change holds only where the cluster's network plugin enforces NetworkPolicy.** New connections from the namespace are then refused. Connections already open may stay open until they close, depending on the plugin. A service installed on an earlier package version admits every namespace on its client port, so nothing changes on the network.
* **Nothing is deleted from the service.** For PostgreSQL the database and everything the application wrote stay. For the other services Ankra cannot tell which keys, streams, indices, objects, logs or metrics the application wrote, so nothing is deleted.

### What stays

* Earlier copies of the connection Secret, in the namespace's Helm release history (`<application>-services`, up to 10 revisions), until newer revisions replace them.
* The shared credential, which stays valid: the application can still use the one it has wherever the network admits it.
* For PostgreSQL, the service's backups, which keep whatever the application wrote until their retention ends.

While the disconnection has not finished, a service newly connected to the same environment reaches it only with the environment's next deploy, not on its own.

***

## Network access

By default, Ankra takes the application's namespace off the service's client port once no pod reads the connection Secret. Choose to keep network access (`keep_network_access`) when something else in that namespace still needs to reach the service, for example a workload someone wired to it by hand, which would otherwise lose access too.

The namespace keeps its access while the disconnection waits for pods to stop reading the Secret and for the Secret to be gone. `network.reason` in the review says what happens after that:

| `reason` | What happens |
| - | - |
| `narrows` | Ankra takes the namespace off the service's port. |
| `keep_requested` | You chose to keep network access: anything running in the namespace can still reach the service. |
| `still_needed` | The namespace keeps its access for now, because the service itself, Ankra's agent or another connected application runs there, or another application there is also being disconnected. When this disconnection finishes, Ankra takes the namespace off unless something still needs it then. Of two disconnections in one namespace, whichever finishes last takes it off. |
| `open_by_design` | VictoriaLogs and VictoriaMetrics admit every namespace by design. Nothing changes. |
| `open` | The service's port admits every namespace, because its package version predates the narrowing or because it was opened by hand. Ankra leaves it as it is. |
| `changed_by_hand` | The service's client access was changed by hand, so Ankra does not change it. Take the namespace off yourself if it should lose access. |
| `not_admitted` | The port does not admit the namespace now. Nothing changes. |
| `not_rendered` | The service's stack is not on the cluster, so there is no network policy to change. |
| `other_cluster` | The environment runs on another cluster, and the service admits only namespaces on its own cluster. Nothing changes. |

***

## Names such as DATABASE\_URL

Of each kind of service connected to an application environment, one gives the names without a prefix, such as `DATABASE_URL` or `REDIS_URL`, as under [Variable names](/guides/connect-to-a-managed-service#variable-names). Ankra never moves those names to another service by itself: that would make the application read and write a different database without anyone choosing it. So when the service you disconnect gives them:

* **No other service of that kind is connected to the environment.** The next deploy stops delivering those names, with the service's other variables.
* **Another service of that kind is connected.** The review asks you to choose which service gives the names from now on, or none: `choice_required` is `true` and `choices` lists the services you can choose. Prepare the review again with your choice, in `connection_names_instance_id` or with `connection_names_none` set to `true`. Confirming without a choice is refused. Ankra records the choice for the environment when you confirm. From the next deploy the chosen service gives the names, or none does, and that deploy rolls the workloads onto the change. A choice marked `installing` is a service still being set up, so it is a new, empty service.

A choice in a review that does not ask for one is refused.

***

## Disconnect in the new Ankra portal

**1. Open the service**

In the new Ankra portal (`/next` on your portal's address), open **Managed services**, then **My services**, choose the service, then open **Connections**.

**2. Choose the environment**

Under **Disconnect an application**, choose **Disconnect `<application>`** beside the environment. The section is shown only when your role holds the [permissions](#prerequisites) for at least one environment the service serves.

**3. Review the plan**

The page prepares the review as it opens and shows each part of the plan, as under [What the review shows](#what-the-review-shows). When the review asks who gives names such as `DATABASE_URL` from now on, or you tick **Keep network access for `<namespace>`** where it is offered, answer and choose **Update the review**: it prepares a new review, which is the one you confirm.

**4. Confirm**

Confirm with **Disconnect `<application>`** before the time the page shows, 10 minutes after the review was prepared, or choose **Review again** for a fresh review once that time has passed.

**5. Deploy the application**

Choose **Deploy now** when the page offers it, or let the environment's next deploy run. Until the disconnection has finished, the service's **Connections** lists the application under **Applications being disconnected**, with the step it is in.

***

## Disconnect with the Ankra CLI

`ankra services disconnect` takes both steps in one command. It prepares the review and prints every part of it in the platform's own words, then asks you to confirm. Preparing changes nothing.

```bash theme={null}
ankra services disconnect <service> --application <application>
```

The application is disconnected only when you confirm the review: at the prompt, or with `--yes`. Answering no, or running without a terminal and without `--yes`, exits with status 4 and changes nothing.

* `--application` takes the application's name or id, and `--environment` chooses the environment when the application uses the service from more than one. `--consumer` names one consumer by its id instead, for example a namespace no environment is deployed to; `ankra services get <service>` lists them.
* `--review-only` shows the review and confirms nothing. A review you do not confirm expires after 10 minutes and changes nothing.
* When the review asks who gives names such as `DATABASE_URL` from now on, nothing is confirmed until you choose: run the command again with `--names-from <service>`, or with `--names-from none` for no service. See [Names such as DATABASE\_URL](#names-such-as-database_url).
* `--keep-network-access` keeps the application's namespace allowed on the service's port, as under [Network access](#network-access).
* `-o json` or `-o yaml` prints the review, or the confirmed disconnection, on stdout.

```bash theme={null}
ankra services disconnect orders-db --application storefront --environment staging --review-only
ankra services disconnect orders-db --application storefront --names-from orders-db-v2 --yes
```

Then deploy the application environment, or let its next deploy run. Until the disconnection has finished, `ankra services get <service>` lists the application under `Disconnecting`, with its phase. Every flag is in the [CLI reference](/reference/cli/services#ankra-services-disconnect).

***

## Disconnect through the API

Disconnecting takes two calls, a prepare and a confirm, with an [API token](/api-reference/introduction) whose holder has the [permissions](#prerequisites) above.

**1. Read the service**

Read the service with [Get a managed service instance](/api-reference/services/get-a-managed-service-instance) for its `generation` and the `id` of the environment among its `consumers`.

**2. Prepare the review**

[Prepare a managed-service disconnection review](/api-reference/services/prepare-a-managed-service-disconnection-review). Every field is required:

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/org/service-admission/instances/<instance-id>/disconnections \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"consumer_id": "<consumer-id>", "expected_generation": <generation>, "timing": "after_next_deploy", "keep_network_access": false, "connection_names_instance_id": null, "connection_names_none": false}'
```

The answer carries the disconnection's `id`, its `plan`, its `digest` and its `expires_at`, 10 minutes later. Nothing changes. If `plan.connection_names.choice_required` is `true`, prepare it again with your choice, as under [Names such as DATABASE\_URL](#names-such-as-database_url).

**3. Confirm it by its digest**

[Confirm a managed-service disconnection by its digest](/api-reference/services/confirm-a-managed-service-disconnection-by-its-digest) within the 10 minutes:

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/org/service-admission/instances/<instance-id>/disconnections/<disconnection-id>/confirm \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"digest": "<digest>"}'
```

The platform resolves the plan again and refuses when anything it covers changed since the review. Confirming again with the same digest returns the same disconnection, never a second one.

**4. Deploy the application**

Deploy the application environment, or let its next deploy run. Until then the application keeps working against the service.

Each person can hold at most 10 disconnection reviews waiting for confirmation, and each organisation 50. A review you do not confirm expires on its own and changes nothing.

***

## Follow the disconnection

While the disconnection has not finished, [Get a managed service instance](/api-reference/services/get-a-managed-service-instance) lists it under `disconnections`, with its `phase`:

| `phase` | Meaning |
| - | - |
| `draining` | The environment's deploys keep the connection Secret while pods started before the disconnection still read it. `keeps_connection_secret` is `true` while those deploys keep writing that Secret unchanged, and `false` when the environment's deploys never delivered one. |
| `removing` | Ankra is removing the connection Secret and waits to see it gone. |
| `revoking` | Ankra is taking the namespace off the service's client port. |

`disconnections.state` reads `unknown` when the platform could not read them; `items` is then empty and says nothing about whether a disconnection is in progress. A finished disconnection leaves the list.

The person who prepared the disconnection can read it at any time, while they still hold the [permissions](#prerequisites), by confirming it again with the same digest. The answer carries its `state` (`in_progress`, then `settled`), its `phase`, the `running_pods` that still read the Secret while it waits, and, once it has finished, its `outcome`. The outcome records only what Ankra observed:

| Field | Values |
| - | - |
| `connection_secret` | `removed`: the Secret was removed and seen gone. `not_delivered`: there was no Secret to remove. `record_only`: the environment is on another cluster, so only the service's record of it was removed. `not_confirmed`: Ankra could not observe it, and claims nothing. |
| `network` | `narrowed`: the namespaces in `removed_namespaces` were taken off the service's port. `left`: nothing was changed, and `network_reason` says why, with a `reason` from [Network access](#network-access). `not_confirmed`: Ankra could not observe it. |

## Verify

Once the outcome reads `removed`, check the application's namespace yourself:

```bash theme={null}
ankra cluster select <cluster>
ankra cluster get secrets -n <namespace>
```

`<service>-connection` is no longer listed.

***

## What is refused

### While you prepare or confirm

| What you see | Cause | Remedy |
| - | - | - |
| `The service's installation has not finished; disconnect the application once it has` | The service is still being installed | Wait until the installation has finished |
| `The service is being retired, which disconnects every application` | The service's deletion was confirmed | Nothing to do: deleting the service disconnects every application |
| `The service is retired, so there is nothing to disconnect` | The service was deleted | Nothing to do |
| `A deploy of this application environment is in progress; disconnect it once the deploy has finished` | A deploy of the environment was accepted or is running | Wait for the deploy to finish, then review again |
| `This application environment is already being disconnected from the service` | A disconnection of the environment has not finished | [Follow it](#follow-the-disconnection) |
| `The service does not serve this application environment` | The consumer is not one of the service's | Read the service again for its `consumers` |
| `The service changed since it was read; reload it and review the disconnection again` | The service's `generation` moved | Read the service again and prepare a new review |
| `The disconnection review has expired; review it again` | The 10-minute window passed | Prepare a new review |
| `The disconnection changed since it was reviewed; review it again` | Something the review covers changed, or the digest is not the one prepared | Prepare a new review |
| `Disconnecting now is not available: ...` | `timing` was `now` | Use `after_next_deploy` |
| `This service gives the application its conventional connection names (such as DATABASE_URL) and another service of the same kind is connected; ...` | The review asks for a choice and none was made | Prepare the review again with a choice |
| `Choose one of the services the disconnection review lists for the connection names, or none, and only when the review asks for it` | The choice is not one the review offers, or the review asks for none | Prepare the review again without it, or with one of `choices` |
| `Too many open disconnection reviews; confirm one or let it expire before preparing another` | 10 reviews of yours, or 50 in the organisation, are waiting | Confirm one, or let them expire after 10 minutes |
| `Ankra cannot tell what the application's connection release renders for this service ...` | The release that delivers the application's connections was changed outside Ankra, or cannot be read back, so Ankra cannot keep the Secret in place while pods stop reading it | Deploy the application again, then review the disconnection again |

### While a disconnection is in progress

* **Connecting the same environment to the service again** is refused with `This application environment is still being disconnected from the service; connect it again once the disconnection has finished`.
* **Deleting the service** is refused with `An application is still being disconnected from the service; retire it once the disconnection has finished`. Deleting the service would remove the source of the Secret the disconnection keeps in place for pods that still read it.
* **A deploy of the environment** is refused, and deploys nothing, when the release that delivers the application's connections renders the Secret in another form than the one kept when the service was disconnected, because its values were changed outside Ankra. The refusal names the release and the Secret. Restore the release's values from the stack's version history, the version before the change, and deploy again. If they cannot be restored, contact Ankra support.

### Deleting an application or removing its binding

While a service still serves an application environment, deleting the application is refused, and so is removing the environment's binding (`ankra services consumers unbind`, or the MCP tool `unbind_service_consumer`). The refusals say to disconnect first:

```text theme={null}
This application uses managed service 'orders-db'. Disconnect the application from it (or retire it) before deleting the application, so no service is left serving an application that is gone. Disconnecting needs the applications.deploy permission, clusters.operate on the service's cluster, and clusters.operate and clusters.read on the application's cluster; the operator, admin and owner roles have them.
```

```text theme={null}
A service still uses this binding; disconnect the application from the service (or retire the service) before removing it
```

Disconnect each of the application's environments from each service the refusal names, or delete those services. A confirmed disconnection takes the environment off the service at once, so that service no longer holds the deletion or the binding.

***

## Next steps

> [card] [Connect to a managed service](/guides/connect-to-a-managed-service)
>
> How applications receive a connection, and the variable names for each service.

> [card] [Delete a managed service](/guides/delete-a-managed-service)
>
> Remove the service itself, with its data, through a reviewed plan.


# DigitalOcean Kubernetes (DOKS)
Source: https://docs.ankra.ai/guides/doks-clusters

Provision, import, and operate DigitalOcean Kubernetes (DOKS) clusters with Ankra - live pricing, node pools, upgrades, GitOps, and AI-assisted operations.

[DigitalOcean Kubernetes (DOKS)](https://www.digitalocean.com/products/kubernetes) is DigitalOcean's managed Kubernetes service. DigitalOcean runs the control plane; Ankra provisions the cluster, then manages everything on top - node pools, Kubernetes upgrades, addons, stacks, GitOps, and AI-assisted operations.

This page covers DOKS specifically. For the shared concepts across all managed providers - live options, discovery/import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes).

## Why DOKS with Ankra

* **Live pricing and options** - regions, Kubernetes versions with support windows, and droplet sizes are fetched live with your DigitalOcean token, with a monthly cost summary as you build the cluster.
* **Highly available control plane** - opt into DigitalOcean's HA control plane at creation.
* **Full day-2 from the CLI, portal, or API** - add and scale node pools, upgrade Kubernetes, and manage addons and stacks the same way as any Ankra cluster.

## Prerequisites

A **DigitalOcean API token** with read/write, stored in Ankra. See [DigitalOcean API Credentials](/platform/credentials/digitalocean).

GitOps is optional: connect a repository at creation and Ankra commits the cluster's stack definitions to Git.

## Creating a DOKS cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick DigitalOcean's **Cloud Managed** action.
>
> **2. Credential & Region**
>
> Select the DigitalOcean credential and a region (for example `fra1`). Regions load live from DigitalOcean.
>
> **3. Node Pools**
>
> Define one or more worker pools: name, droplet size (with live pricing), count, labels, and autoscaling bounds.
>
> **4. Kubernetes**
>
> Pick a Kubernetes version or keep the default, and optionally enable the **HA control plane**.
>
> **5. GitOps (optional) & Create**
>
> Optionally connect a Git repository, then create. Ankra runs DigitalOcean preflight checks, provisions the cluster, retrieves the kubeconfig, and installs the Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider doks \
>   --name my-doks-cluster \
>   --credential-id <do-credential-id> \
>   --location fra1 \
>   --node-pool-name workers \
>   --node-pool-size s-2vcpu-4gb \
>   --node-pool-count 2
> ```
>
> The HA control plane is set from the portal or the API; `--autoscaling` with `--autoscaling-min` and `--autoscaling-max` sets the initial pool's bounds.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/org/clusters/managed/doks \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-doks-cluster",
>     "credential_id": "<do-credential-id>",
>     "location": "fra1",
>     "kubernetes_version": "1.33.1-do.0",
>     "node_pools": [
>       {"name": "workers", "size": "s-2vcpu-4gb", "count": 2}
>     ],
>     "ha": true
>   }'
> ```

### DOKS options

| Field | Description |
| - | - |
| `ha` | Highly available control plane (top-level field) |

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

Node pools, upgrades, and deletion work from the CLI, portal, or API. The CLI examples use `--provider doks`:

```bash theme={null}
# scale a pool to a fixed count
ankra cluster managed node-pool scale <cluster_id> workers --provider doks --count 5

# upgrade the cluster
ankra cluster managed upgrade <cluster_id> --provider doks --version 1.33.1-do.0

# delete the cluster
ankra cluster managed delete <cluster_id> --provider doks
```

Autoscaling bounds are set from the portal, with `ankra cluster managed node-pool update --autoscaling --autoscaling-min <n> --autoscaling-max <n>`, or with the `PATCH .../node-pools/{name}` endpoint. See [Managed Kubernetes - day-2 operations](/guides/managed-kubernetes#day-2-operations) for the shared node-pool and upgrade mechanics.

## Importing an existing DOKS cluster

Already running DOKS? Discover clusters at DigitalOcean and adopt them into Ankra without touching them. Discovery and import run from the portal, the CLI (`ankra cluster managed discover|import --provider doks`) or the API - see [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters).

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [DigitalOcean API Credentials](/platform/credentials/digitalocean)
* [Cluster settings](/platform/cluster-settings)


# Amazon EKS
Source: https://docs.ankra.ai/guides/eks-clusters

Provision, import, and operate Amazon EKS clusters with Ankra - automatic IAM setup, subnets and control-plane logging, node groups, upgrades, GitOps, and AI-assisted operations.

[Amazon EKS](https://aws.amazon.com/eks/) is AWS's managed Kubernetes service. AWS runs the control plane; Ankra provisions the cluster, then manages everything on top - node groups, Kubernetes upgrades, addons, stacks, GitOps, and AI-assisted operations.

This page covers EKS specifically. For the shared concepts across all managed providers - live options, discovery/import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes).

> [!TIP]
>
> **Already running EKS?** You can bring it into Ankra two ways. A **managed import** uses your AWS credential: in **Clusters**, click **Create cluster** and choose **Import existing**, or run `ankra cluster managed discover --provider eks` and `ankra cluster managed import --provider eks`. Ankra fetches the kubeconfig and installs the agent, so there is nothing to run on the cluster, and the cluster gains the same node-pool and upgrade operations as clusters Ankra created. The **Helm import** needs no cloud credential and works for any cluster: run the one `helm` command the Import dialog gives you - see [Import an existing cluster](/guides/import-cluster#import-an-existing-cluster).

## Why EKS with Ankra

* **Automatic IAM setup** - Ankra creates the required IAM roles for the cluster and node groups, so you do not have to wire them by hand.
* **Bring your own network, or don't** - specify `subnet_ids` and `security_group_ids`, or let Ankra use your default VPC subnets.
* **Live pricing and options** - regions, Kubernetes versions, and EC2 instance types are fetched live with your AWS credential, including spot and autoscaling where available.

## Prerequisites

An **AWS credential** stored in Ankra (access keys or an IAM role) with permissions for **EKS**, **EC2**, and **IAM role management**. The IAM-role wizard's **Provisioning (EKS clusters)** access level creates a correctly scoped role for you. See [AWS Credentials](/platform/credentials/aws).

GitOps is optional: connect a repository at creation and Ankra commits the cluster's stack definitions to Git.

## Creating an EKS cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick AWS's **Cloud Managed** action.
>
> **2. Credential & Region**
>
> Select the AWS credential and a region (for example `eu-west-1`). Regions load live from AWS.
>
> **3. Node Groups**
>
> Define one or more worker groups: name, instance type (with live pricing), count, labels, and autoscaling bounds.
>
> **4. Kubernetes & Networking**
>
> Pick a Kubernetes version or keep the default, optionally set subnets and security groups, and enable control-plane logging if you want it.
>
> **5. GitOps (optional) & Create**
>
> Optionally connect a Git repository, then create. Ankra runs EKS preflight checks, creates the IAM roles, provisions the cluster, retrieves the kubeconfig, and installs the Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider eks \
>   --name my-eks-cluster \
>   --credential-id <aws-credential-id> \
>   --location eu-west-1 \
>   --node-pool-name workers \
>   --node-pool-size m5.large \
>   --node-pool-count 2
> ```
>
> Subnets, security groups and control-plane logging are set from the portal or the API. Node-group autoscaling bounds take `--autoscaling --autoscaling-min <n> --autoscaling-max <n>` (CLI v0.9.0 or later).

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/org/clusters/managed/eks \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-eks-cluster",
>     "credential_id": "<aws-credential-id>",
>     "location": "eu-west-1",
>     "kubernetes_version": "1.32",
>     "node_pools": [
>       {
>         "name": "workers",
>         "size": "m5.large",
>         "count": 2,
>         "autoscaling": {"enabled": true, "min_count": 2, "max_count": 5}
>       }
>     ],
>     "eks": {"enable_control_plane_logging": true}
>   }'
> ```

### EKS options

| Field | Description |
| - | - |
| `eks.subnet_ids` | Subnets to place the cluster in (defaults to your default VPC subnets) |
| `eks.security_group_ids` | Security groups to attach |
| `eks.enable_control_plane_logging` | Enable EKS control-plane logging |

> [!NOTE]
>
> EKS creates the IAM roles for the cluster and node groups automatically and uses your default VPC subnets when `subnet_ids` is omitted. Control planes routinely take 10-15 minutes to provision; node groups follow after.

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

Node groups, upgrades, and deletion work from the CLI, portal, or API. The CLI examples use `--provider eks`:

```bash theme={null}
# scale a pool to a fixed count
ankra cluster managed node-pool scale <cluster_id> workers --provider eks --count 5

# upgrade the cluster
ankra cluster managed upgrade <cluster_id> --provider eks --version 1.32

# delete the cluster
ankra cluster managed delete <cluster_id> --provider eks
```

Autoscaling bounds are set from the portal, with `ankra cluster managed node-pool update --autoscaling --autoscaling-min <n> --autoscaling-max <n>`, or with the `PATCH .../node-pools/{name}` endpoint. See [Managed Kubernetes - day-2 operations](/guides/managed-kubernetes#day-2-operations) for the shared mechanics.

## Importing an existing EKS cluster

Already running EKS? Discover clusters in your AWS account and adopt them into Ankra without touching them. Discovery and import run from the portal, the CLI (`ankra cluster managed discover|import --provider eks`) or the API - see [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters).

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [AWS Credentials](/platform/credentials/aws)
* [Cluster settings](/platform/cluster-settings)


# GitLab CI/CD Pipeline
Source: https://docs.ankra.ai/guides/gitlab-cicd-pipeline

Build images with GitLab CI and deploy them by committing the new tag to a GitOps repository on GitHub or Bitbucket Cloud

> [!NOTE]
>
> This guide shows you how to build a CI/CD pipeline with GitLab CI that automatically deploys your applications to Kubernetes when you push code. Your pipeline builds container images and updates the GitOps repository. Ankra handles the rest.

> [!WARNING]
>
> **The GitOps repository cannot be on GitLab.** Ankra syncs a cluster's GitOps repository from GitHub or Bitbucket Cloud only. Your application code and GitLab CI stay on GitLab; the pipeline in this guide commits the new image tag to a GitOps repository on GitHub. For the other routes from a repository to a running application, see [Ship Your App](/guides/deliver-your-app).

***

## Architecture Overview

```mermaid theme={null}
flowchart TB
    subgraph AppRepos [Application Repositories]
        ServiceA[Service A]
        ServiceB[Service B]
        ServiceC[Service C]
    end

    subgraph CI [GitLab CI Pipeline]
        Build[Build and Push Image]
        Update[Update GitOps Repo]
    end

    GitOps[(GitOps Repo)]

    subgraph Ankra [Ankra Platform]
        StackBuilder[Stack Builder]
        Engine[GitOps Engine]
    end

    Agent[Ankra Agent]
    Cluster[Your Cluster]

    ServiceA --> Build
    ServiceB --> Build
    ServiceC --> Build
    Build --> Update
    Update -->|commit image tag| GitOps
    StackBuilder --> Engine
    Engine -->|sync| GitOps
    Engine --> Agent
    Agent --> Cluster
```

The flow works like this:

1. **You push code** to your GitLab application repository
2. **GitLab CI builds and pushes** a container image to your registry
3. **GitLab CI updates the GitOps repo** with the new image tag
4. **Ankra detects the change** and triggers a deployment
5. **Ankra Agent deploys** the updated manifest to your cluster

***

## What You'll Build

A complete CI/CD pipeline with:

| Component | Purpose |
| - | - |
| **Application Repo** | Your app code with Dockerfile and `.gitlab-ci.yml` |
| **GitOps Repo** | Kubernetes manifests managed by Ankra, on GitHub or Bitbucket Cloud |
| **Container Registry** | Stores your built images (GitLab Container Registry, GCR, ECR, etc.) |
| **GitLab CI** | Builds images and updates the GitOps repo |

***

## Prerequisites

* A cluster imported into Ankra with the agent connected
* A GitOps repository on GitHub (this guide) or Bitbucket Cloud
* A container registry (GitLab Container Registry, Google Artifact Registry, AWS ECR, Docker Hub, etc.)
* An application repository on GitLab with a Dockerfile

***

## Step 1: Connect a GitOps Repository to the Cluster

Connect the repository that will hold the cluster's configuration. It must be on GitHub or Bitbucket Cloud.

**1. Open the cluster's GitOps settings**

Go to your cluster → **Settings** → **GitOps**.

**2. Connect the repository**

Pick a GitHub or Bitbucket Cloud credential, then the repository and branch, and click **Connect Repository**. The [GitHub](/integrations/github#connecting-github) and [Bitbucket Cloud](/integrations/bitbucket-cloud#connecting-a-repository-to-a-cluster) guides cover the credential and each screen.

> [!TIP]
>
> We recommend a dedicated repository (for example `my-org/infrastructure-gitops`) to keep cluster configuration separate from application code.

Once connected, Ankra writes the cluster's configuration to a `clusters/<cluster-name>-<short-id>/` folder in the repository and keeps it in sync.

***

## Step 2: Create a Stack for Your Application

In Ankra, manifests are organized into **Stacks**. A Stack is a collection of related Kubernetes resources that are deployed together.

**1. Open the Stacks Page**

Navigate to your cluster → **Stacks**.

**2. Create a New Stack**

Click **Create** to open the Stack Builder.

**3. Name Your Stack**

Give your stack a descriptive name, like `backend-services` or `production-apps`.

**4. Add a Manifest Using AI**

Press `⌘+J` (or `Ctrl+J`) to open the AI Assistant and describe your deployment:

```
Create a deployment manifest for my backend service:
- Image: registry.gitlab.com/my-group/my-app/backend:sha-1a2b3c4d
- Namespace: production
- 2 replicas
- Port 8080
- Health check on /health
- 256Mi memory, 100m CPU requests
```

The AI will provide a manifest you can add to your stack.

**5. Create the Stack**

Review your configuration in the Builder tab, then click **Create Stack**.

Ankra will commit the manifests to your GitOps repository and deploy them to your cluster.

> [!TIP]
>
> You can view your stack's manifests in the GitOps repository under `clusters/<cluster-name>-<short-id>/stacks/<stack-name>/manifests/`.

***

## Step 3: Set Up CI Deploy Key

Your GitLab CI pipeline needs write access to the GitOps repository to update image tags when new builds complete.

**1. Generate an SSH Key**

On your local machine, generate a deploy key:

```bash theme={null}
ssh-keygen -t ed25519 -C "ci-deploy-key" -f deploy_key -N ""
```

This creates `deploy_key` (private) and `deploy_key.pub` (public).

**2. Add Public Key to GitOps Repo**

Go to your GitOps repository on GitHub → **Settings** → **Deploy keys** → **Add deploy key**.

Add the contents of `deploy_key.pub` and check **Allow write access**.

> [!NOTE]
>
> On Bitbucket Cloud, repository access keys are read-only, so they cannot push. Use a repository access token with write permission over HTTPS instead.

**3. Add Private Key to App Repo**

Go to your application repository → **Settings** → **CI/CD** → **Variables**.

Create a new variable:

* **Key:** `GITOPS_DEPLOY_KEY`
* **Value:** Contents of `deploy_key`
* **Type:** File
* **Flags:** Check **Mask variable** and **Protect variable**

***

## Step 4: Create the GitLab CI Pipeline

Add a `.gitlab-ci.yml` file to your application repository that builds your container and updates the GitOps repo.

**1. Create the Pipeline File**

In your application repository, create `.gitlab-ci.yml` at the root.

**2. Use the AI to Generate the Pipeline**

Open the AI Assistant (`⌘+J`) and describe your pipeline:

```
Generate a GitLab CI pipeline that:
- Triggers on push to main branch
- Builds a Docker image from my Dockerfile
- Pushes to GitLab Container Registry
- Tags with the git SHA, never latest
- Updates my GitOps repo at github.com/my-org/infrastructure-gitops
- Updates the image tag in clusters/my-cluster-<short-id>/stacks/backend-services/manifests/backend-deployment.yaml
```

The AI will generate a complete pipeline tailored to your setup.

**3. Add Registry Variables**

If using an external registry (not GitLab Container Registry), add these variables under **Settings** → **CI/CD** → **Variables**:

| Variable | Description |
| - | - |
| `REGISTRY_USERNAME` | Registry username (or `_json_key` for GCP) |
| `REGISTRY_PASSWORD` | Registry password or service account key |
| `GITOPS_DEPLOY_KEY` | The SSH private key from Step 3 |

> [!TIP]
>
> GitLab Container Registry is available by default in GitLab CI via `$CI_REGISTRY`, `$CI_REGISTRY_USER`, and `$CI_REGISTRY_PASSWORD` - no extra variables needed.

> [accordion] Example Pipeline: GitLab Container Registry
>
> Here's a pipeline using GitLab's built-in container registry. It tags every image with the commit SHA, never `latest`, so each deploy names exactly one build. Use the AI to customise it for your setup:
>
> ```yaml theme={null}
> stages:
>   - build
>   - deploy
>
> variables:
>   IMAGE_NAME: $CI_REGISTRY_IMAGE/backend
>   GITOPS_REPO: git@github.com:my-org/infrastructure-gitops.git
>   MANIFEST_PATH: clusters/my-cluster-<short-id>/stacks/backend-services/manifests/backend-deployment.yaml
>
> build:
>   stage: build
>   image: docker:27
>   services:
>     - docker:27-dind
>   rules:
>     - if: $CI_COMMIT_BRANCH == "main"
>       changes:
>         - src/**/*
>         - Dockerfile
>   script:
>     - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
>     - docker build -t $IMAGE_NAME:$CI_COMMIT_SHA .
>     - docker push $IMAGE_NAME:$CI_COMMIT_SHA
>
> update-gitops:
>   stage: deploy
>   image: alpine:3.20
>   needs: [build]
>   rules:
>     - if: $CI_COMMIT_BRANCH == "main"
>       changes:
>         - src/**/*
>         - Dockerfile
>   before_script:
>     - apk add --no-cache git openssh-client sed
>     - eval $(ssh-agent -s)
>     - chmod 600 $GITOPS_DEPLOY_KEY
>     - ssh-add $GITOPS_DEPLOY_KEY
>     - mkdir -p ~/.ssh
>     - ssh-keyscan github.com >> ~/.ssh/known_hosts
>   script:
>     - git clone $GITOPS_REPO gitops-repo
>     - cd gitops-repo
>     - "sed -i \"s|image: .*backend:.*|image: ${IMAGE_NAME}:${CI_COMMIT_SHA}|\" $MANIFEST_PATH"
>     - git config user.name "GitLab CI"
>     - git config user.email "gitlab-ci@users.noreply.gitlab.com"
>     - git add $MANIFEST_PATH
>     - git commit -m "Deploy backend: $CI_COMMIT_SHA"
>     - git push origin main
> ```

> [accordion] Example Pipeline: Google Artifact Registry
>
> Here's a pipeline pushing to Google Artifact Registry:
>
> ```yaml theme={null}
> stages:
>   - build
>   - deploy
>
> variables:
>   IMAGE_NAME: europe-west1-docker.pkg.dev/my-project/docker-images/backend
>   GITOPS_REPO: git@github.com:my-org/infrastructure-gitops.git
>   MANIFEST_PATH: clusters/my-cluster-<short-id>/stacks/backend-services/manifests/backend-deployment.yaml
>
> build:
>   stage: build
>   image: docker:27
>   services:
>     - docker:27-dind
>   rules:
>     - if: $CI_COMMIT_BRANCH == "main"
>       changes:
>         - src/**/*
>         - Dockerfile
>   script:
>     - echo "$GCP_SERVICE_ACCOUNT_KEY" | docker login -u _json_key --password-stdin https://europe-west1-docker.pkg.dev
>     - docker build -t $IMAGE_NAME:$CI_COMMIT_SHA .
>     - docker push $IMAGE_NAME:$CI_COMMIT_SHA
>
> update-gitops:
>   stage: deploy
>   image: alpine:3.20
>   needs: [build]
>   rules:
>     - if: $CI_COMMIT_BRANCH == "main"
>       changes:
>         - src/**/*
>         - Dockerfile
>   before_script:
>     - apk add --no-cache git openssh-client sed
>     - eval $(ssh-agent -s)
>     - chmod 600 $GITOPS_DEPLOY_KEY
>     - ssh-add $GITOPS_DEPLOY_KEY
>     - mkdir -p ~/.ssh
>     - ssh-keyscan github.com >> ~/.ssh/known_hosts
>   script:
>     - git clone $GITOPS_REPO gitops-repo
>     - cd gitops-repo
>     - "sed -i \"s|image: .*backend:.*|image: ${IMAGE_NAME}:${CI_COMMIT_SHA}|\" $MANIFEST_PATH"
>     - git config user.name "GitLab CI"
>     - git config user.email "gitlab-ci@users.noreply.gitlab.com"
>     - git add $MANIFEST_PATH
>     - git commit -m "Deploy backend: $CI_COMMIT_SHA"
>     - git push origin main
> ```

***

## Step 5: Configure Registry Access in Your Cluster

If your container registry is private, your cluster needs credentials to pull images.

**1. Open the AI Assistant**

Press `⌘+J` to open the AI Assistant.

**2. Ask for an Image Pull Secret**

```
Create an image pull secret for my private registry:
- Registry: registry.gitlab.com
- Namespace: production
- Name: gitlab-pull-secret
```

**3. Add the Secret Value**

The AI will provide a Secret manifest template. You'll need to provide your registry credentials:

* For GitLab: Use a [Deploy Token](https://docs.gitlab.com/ee/user/project/deploy_tokens/) with `read_registry` scope
* For GCP: Use a service account JSON key with `Artifact Registry Reader` role
* For AWS ECR: Use an IAM access key

**4. Link to Your Deployment**

Ask the AI to update your deployment to use the pull secret:

```
Update my backend deployment to use the gitlab-pull-secret for pulling images
```

> [!TIP]
>
> Use [SOPS encryption](/guides/sops) to safely store registry credentials in your GitOps repository.

***

## Step 6: Test the Pipeline

**1. Push a Code Change**

Make a change to your application code and push to main:

```bash theme={null}
git add .
git commit -m "Add new feature"
git push origin main
```

**2. Monitor CI Progress**

Go to **CI/CD** → **Pipelines** in your GitLab project to watch the pipeline run.

**3. Verify GitOps Update**

After CI completes, check your GitOps repository. You should see a new commit updating the image tag.

**4. Watch the Deployment**

In Ankra, go to your cluster → **Operations** to see the deployment in progress. The new image will roll out automatically.

***

## Step 7: Monitor GitOps Sync Status

Ankra provides visibility into your GitOps sync status.

**1. View GitOps Status**

Navigate to your cluster → **GitOps** to see:

* Current sync status
* Recent sync history
* Any sync errors

**2. Trigger Manual Sync**

If needed, click **Sync** to manually trigger a sync from your repository.

**3. View in Operations**

Check the **Operations** page for detailed deployment history and job status.

***

## Adding More Services

To add CI/CD for additional services, use the AI Assistant to scaffold everything:

**1. Add to Existing Stack or Create New**

Either edit your existing stack or create a new one for the service.

**2. Generate the Deployment Manifest**

Open the AI Assistant (`⌘+J`) and describe your service:

```
Add a deployment for my frontend service:
- Image: registry.gitlab.com/my-group/my-app/frontend
- Namespace: production
- 3 replicas
- Port 3000
- Expose via a Service on port 80
```

**3. Generate the CI Pipeline**

In your frontend app repo, create a `.gitlab-ci.yml` or ask the AI:

```
Generate a GitLab CI pipeline to build and deploy my frontend:
- Build from ./frontend/Dockerfile
- Push to GitLab Container Registry
- Update clusters/my-cluster/manifests/frontend-deployment.yaml in my GitOps repo
```

**4. Add the Variables**

Copy the same CI/CD variables (`GITOPS_DEPLOY_KEY`, registry credentials) to the new project.

***

## Troubleshooting

Having issues? Open the AI Assistant (`⌘+J`) and describe your problem:

> [accordion] CI Can't Push to GitOps Repo
>
> Ask the AI:
>
> ```
> My GitLab CI pipeline is failing to push to the GitOps repo with a permission denied error.
> Help me troubleshoot the deploy key setup.
> ```
>
> Common causes:
>
> * Deploy key doesn't have write permissions on the GitOps repo
> * `GITOPS_DEPLOY_KEY` variable is not set as **File** type
> * `ssh-keyscan` is missing for `github.com`

> [accordion] Image Not Updating
>
> Ask the AI:
>
> ```
> I pushed a new image tag to my GitOps repo but the pods aren't updating.
> What could be wrong?
> ```

> [accordion] Pods Can't Pull Image
>
> Ask the AI:
>
> ```
> My pods are stuck in ImagePullBackOff. Help me fix the registry authentication.
> ```
>
> For GitLab Container Registry, ensure your image pull secret uses a Deploy Token with `read_registry` scope.

> [accordion] Pipeline Fails on Docker Build
>
> Ensure your GitLab Runner supports Docker-in-Docker:
>
> * Use `docker:27` as the job image
> * Add `docker:27-dind` as a service
> * If using Kubernetes executors, ensure privileged mode is enabled or use Kaniko instead

> [accordion] GitOps Sync Not Triggering
>
> Check the **GitOps** page in your cluster to see sync status. If sync isn't triggering:
>
> * Verify the GitOps repository is still connected under the cluster's **Settings** → **GitOps**
> * Check that your commit was pushed to the correct branch
> * Look for webhook configuration issues in the GitOps status

> [!NOTE]
>
> The AI has access to your pod logs, events, and deployment status. It can pinpoint exactly what's going wrong and suggest fixes.

***

## Next Steps

> [card] [Ship Your App](/guides/deliver-your-app)
>
> Compare the routes from a repository to a running application, including GitHub Actions.

> [card] [GitOps Reference](/concepts/gitops)
>
> Learn more about GitOps file formats and the cluster directory.

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt secrets in your GitOps repository.

> [card] [Operations](/platform/operations)
>
> Monitor deployment progress and history.


# Google Kubernetes Engine (GKE)
Source: https://docs.ankra.ai/guides/gke-clusters

Provision, import, and operate Google Kubernetes Engine (GKE) clusters with Ankra - Standard and Autopilot, live pricing, node pools, upgrades, GitOps, and AI-assisted operations.

[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) is Google Cloud's managed Kubernetes service. Google runs the control plane; Ankra provisions the cluster, then manages everything on top - node pools, Kubernetes upgrades, addons, stacks, GitOps, and AI-assisted operations.

This page covers GKE specifically. For the shared concepts across all managed providers - live options, discovery/import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes).

> [!TIP]
>
> **Already running GKE?** You can bring it into Ankra two ways. A **managed import** uses your GCP credential: in **Clusters**, click **Create cluster** and choose **Import existing**, or run `ankra cluster managed discover --provider gke` and `ankra cluster managed import --provider gke`. Ankra fetches the kubeconfig and installs the agent, so there is nothing to run on the cluster, and the cluster gains the same node-pool and upgrade operations as clusters Ankra created. The **Helm import** needs no cloud credential and works for any cluster: run the one `helm` command the Import dialog gives you - see [Import an existing cluster](/guides/import-cluster#import-an-existing-cluster).

## Why GKE with Ankra

* **Standard or Autopilot** - run node pools you size yourself, or let Google manage nodes with Autopilot.
* **Release channels** - pin the cluster to the `RAPID`, `REGULAR`, or `STABLE` channel.
* **Live pricing and options** - locations, Kubernetes versions, and machine types are fetched live with your service account, including GPU and spot capacity where available.

## Prerequisites

A **GCP service account key** stored in Ankra, with the **Kubernetes Engine Admin** (`roles/container.admin`) and **Service Account User** (`roles/iam.serviceAccountUser`) roles, and the **Kubernetes Engine API** enabled on the project. To create VPC networks from the cluster wizard, the service account additionally needs **Compute Network Admin** (`roles/compute.networkAdmin`) for the `compute.networks.create` permission. See [Google Cloud (GCP) Credentials](/platform/credentials/gcp).

GitOps is optional: connect a repository at creation and Ankra commits the cluster's stack definitions to Git.

## Creating a GKE cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick Google Cloud's **Cloud Managed** action.
>
> **2. Credential & Location**
>
> Select the GCP credential and a location - a zone (`europe-west1-b`) or a region (`europe-west1`). Locations load live from Google Cloud.
>
> Then pick the **VPC Network** the cluster attaches to. Ankra lists the project's networks live; if the project has a `default` network it is preselected. **Create new network** provisions a fresh VPC from Ankra without leaving the wizard - see [VPC networking](#vpc-networking).
>
> **3. Mode & Node Pools**
>
> Choose **Standard** and define worker pools (name, machine type with live pricing, count, labels, autoscaling), or choose **Autopilot** and let Google manage the nodes.
>
> **4. Kubernetes**
>
> Pick a Kubernetes version or keep the default, and select a release channel.
>
> **5. GitOps (optional) & Create**
>
> Optionally connect a Git repository, then create. Ankra runs GKE preflight checks, provisions the cluster, retrieves the kubeconfig, and installs the Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider gke \
>   --name my-gke-cluster \
>   --credential-id <gcp-credential-id> \
>   --location europe-west1 \
>   --node-pool-name workers \
>   --node-pool-size e2-standard-4 \
>   --node-pool-count 2
> ```
>
> The release channel and Autopilot mode are set from the portal or the API; `--autoscaling` with `--autoscaling-min` and `--autoscaling-max` sets the initial pool's bounds.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/org/clusters/managed/gke \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-gke-cluster",
>     "credential_id": "<gcp-credential-id>",
>     "location": "europe-west1",
>     "kubernetes_version": "1.32.3",
>     "node_pools": [
>       {
>         "name": "workers",
>         "size": "e2-standard-4",
>         "count": 2,
>         "autoscaling": {"enabled": true, "min_count": 2, "max_count": 5}
>       }
>     ],
>     "gke": {"release_channel": "REGULAR", "mode": "standard"}
>   }'
> ```

### GKE options

| Field | Description |
| - | - |
| `gke.release_channel` | `RAPID`, `REGULAR`, or `STABLE` |
| `gke.mode` | `standard` (you manage node pools) or `autopilot` (Google manages nodes) |
| `gke.network` | The VPC network the cluster attaches to, by name. Omitted, GKE assumes a network literally named `default` - which many projects don't have, so pick one explicitly |
| `gke.subnetwork` | Optional subnetwork override. For custom-mode networks Ankra resolves the subnetwork in the cluster's region automatically when this is omitted |

> [!NOTE]
>
> **Autopilot** clusters ignore node-pool sizing - Google manages the nodes automatically. Cluster names are lowercase letters, numbers, and hyphens, and must start with a letter.

## VPC networking

Every GKE cluster attaches to a VPC network. The wizard lists the project's networks live with your credential and preselects `default` when the project has one; projects without a `default` network must pick one explicitly - otherwise the GKE API fails the create with "no network named default". The subnetwork for the cluster's region is resolved automatically (auto-mode networks have one per region; for custom-mode networks Ankra picks the region's subnetwork).

Don't have a usable network? **Create new network** in the wizard provisions one from Ankra: the VPC is created in **auto subnet mode** - Google creates a subnetwork in every region, exactly like the built-in `default` network - so the cluster can attach in any location with no further subnet setup. The same flow is available on the API:

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/managed/gke/networks \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"credential_id": "<gcp-credential-id>", "name": "my-vpc"}'
```

> [!WARNING]
>
> Creating a network requires the `compute.networks.create` permission, which is **not** part of the base GKE provisioning roles. Grant **Compute Network Admin** (`roles/compute.networkAdmin`) to the service account - see [Google Cloud (GCP) Credentials](/platform/credentials/gcp). Without it, the create fails with `Required 'compute.networks.create' permission`; attaching to an existing network keeps working.

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

Node pools, upgrades, and deletion work from the CLI, portal, or API. The CLI examples use `--provider gke`:

```bash theme={null}
# scale a pool to a fixed count
ankra cluster managed node-pool scale <cluster_id> workers --provider gke --count 5

# upgrade the cluster
ankra cluster managed upgrade <cluster_id> --provider gke --version 1.32.3

# delete the cluster
ankra cluster managed delete <cluster_id> --provider gke
```

Autoscaling bounds are set from the portal, with `ankra cluster managed node-pool update --autoscaling --autoscaling-min <n> --autoscaling-max <n>`, or with the `PATCH .../node-pools/{name}` endpoint. See [Managed Kubernetes - day-2 operations](/guides/managed-kubernetes#day-2-operations) for the shared mechanics.

## Importing an existing GKE cluster

Already running GKE? Discover clusters in your project and adopt them into Ankra without touching them. Discovery and import run from the portal, the CLI (`ankra cluster managed discover|import --provider gke`) or the API - see [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters).

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [Google Cloud (GCP) Credentials](/platform/credentials/gcp)
* [Cluster settings](/platform/cluster-settings)


# Harbor as your application registry
Source: https://docs.ankra.ai/guides/harbor-registry

Publish application images to a Harbor you operate, with Ankra minting, rotating and revoking a push robot per application and wiring the pull secret into every cluster.

An application publishes to your organisation's private Ankra registry unless you say otherwise. If you already run Harbor, declare it on the application and Ankra publishes there, reads the published tags back from there, and pulls from there - including minting the robot account the build logs in with, if you let it.

This guide is the operator's side of [Using your own registry](/concepts/applications#using-your-own-registry): what Harbor needs to look like before you point an application at it, what Ankra creates once you do, and how to check it from the Harbor end.

***

## The two credentials

Ankra talks to your Harbor with [registry credentials](/platform/credentials/registry) of your organisation. A declaration names up to two of them, and they do different jobs.

| Credential | Declared as | What Ankra does with it | Rights it needs |
| - | - | - | - |
| **Read / pull** | `credential_name` (`--credential`) | Reads published tags for publish readiness, the deploy gate, image listings and demos, and builds the `dockerconfigjson` pull secret every cluster uses | Pull and read on the project: `repository` pull/list/read, `artifact` list/read, `tag` list, `project` read |
| **Project administrator** | `admin_credential_name` (`--admin-credential`) | Checks that the declared project exists and creates it when it does not; mints, rotates and revokes the application's own push robot | A **system** robot with the permission set below, or a Harbor **user** with Project Admin on the project (which can create projects only when Harbor's *Project creation* setting is *Everyone*) |

> [!WARNING]
>
> The read credential is what makes a declaration usable rather than merely descriptive. Without one, Ankra records where the images live but cannot read their tags or pull them - so publish readiness, the demo build check and the deploy gate all keep reporting the application as never built, while it publishes healthily to a registry Ankra simply cannot see. It is also what the cluster pull secret is built from: declare a registry with no read credential and no pull secret is created at all.

**Ankra does not mint robots for a registry you operate unless you hand it the keys.** With no `admin_credential_name`, setup names the two Actions secrets the workflow reads and leaves them to you; your robots stay yours and untouched.

***

## What Harbor needs first

**1. Have the project, or let Ankra create it**

Ankra publishes into the project the declaration's `oci://<host>/<project>` names. With an `admin_credential_name` it checks the project exists when you declare it, and creates it if it does not - private, or public with `--project-public` - when that credential may create projects. A credential that may not is refused with the project and host named, so a declaration no build could publish to is never accepted. Without an admin credential nothing is checked: create the project yourself, and decide whether it is public or private - Ankra works with either, and a private project is why the pull secret exists.

**2. Mint the project-administrator credential**

The account behind `admin_credential_name` is what Ankra checks and creates projects with, and mints robots with. A **system-level robot** is the tidiest on **Harbor 2.14.1 or later**; this is the set Ankra calls Harbor with for the application's registry, by level (rotation is the exception, below):

| Level | Resource | Actions | Used for |
| - | - | - | - |
| System (`/`) | `project` | `list`, `create` | Checking whether the declared project exists (the listing filtered by name) and creating it when it does not |
| System (`/`) | `robot` | `create`, `read`, `list`, `delete` | Robots you create yourself through the portal or API that span several projects, which are system-level robots; the application's push robot is a robot of the project and needs no system-level right |
| Project (`*`) | `project` | `read` | Reading the declared project before Ankra mints, finds or revokes the push robot on it |
| Project (`*`) | `repository` | `push`, `pull` | Granting them to the push robot Ankra mints: Harbor lets a robot grant another robot only the rights it holds itself |
| Project (`*`) | `robot` | `create`, `read`, `list`, `delete` | Minting, finding and revoking the push robot, which is a robot of the project |

The admin credential itself never pushes an image; the `repository` row exists because Harbor caps a robot a robot creates at its creator's own permissions, and the push robot Ankra mints holds `repository` push and pull. If you also name this robot with `--admin-credential` for [robots you create yourself](#robots-on-a-harbor-you-run-yourself), it must hold at Project (`*`), or on that project for a project-scoped robot, every [permission](#exactly-the-permissions-a-job-needs) those robots are given as well. Harbor refuses `project:read` at the system level (`bad request permission: project:read`), and project-level read on `*` covers only projects that exist. Ankra therefore checks a project it cannot read by listing projects by name, which system `project:list` covers; a name the listing lacks is created with `project:create`. Store the robot as a registry credential in Ankra.

Rotating needs `robot` update, which Harbor grants no robot: with a robot as the admin credential, `ankra application registry robot rotate` and the self-heal that re-adopts a robot are refused, and a Harbor user with Project Admin holds it. Until the credential is a user, revoke the robot and ensure it again, which mints a new secret.

> [!WARNING]
>
> Which robot can administer robots depends on the Harbor release. Harbor added `robot` permissions for robots in 2.12.0, so on an older Harbor the admin credential is a Harbor **user** with Project Admin. From 2.12.0 a **project-scoped** robot of the declared project can mint the application's robot when it holds the Project-level rows above on that project; one without `robot` create, list and delete is refused. A **system** robot is refused minting a project's robot on every 2.12 and 2.13 release and on 2.14.0 (Harbor answers `denied`, [goharbor/harbor#21406](https://github.com/goharbor/harbor/issues/21406)), and can from 2.14.1. Ankra reports each of these refusals as a credential that cannot manage robot accounts. A Harbor **user** with Project Admin works on every release for an existing project, and can create a missing one only when Harbor's *Project creation* setting is *Everyone*.

**3. Store a read credential**

Create the pull account - a system robot with pull/list/read across the projects Ankra reads is the tidiest - and store it as a second registry credential. This is the one that ends up inside every cluster's pull secret, so scope it to pull, not push.

***

## Declaring it on an application

Declare the registry when you create the application where you can: the setup job generates the build workflow from the declaration the application is created with, so a registry added afterwards leaves a workflow that logs in to the wrong one until the application is reconciled and its setup pull request merged.

```bash theme={null}
# At creation
ankra application add . \
  --registry-url oci://artifact.example.com/commerce-images \
  --registry-credential example-harbor-pull \
  --registry-admin-credential example-harbor-admin

# On an existing application
ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce-images \
  --credential example-harbor-pull \
  --admin-credential example-harbor-admin \
  --pull-secret harbor-registry

# What the declaration resolved to, and where each component is expected to publish
ankra application registry get <application-id>
```

Where your Harbor's repository layout is not Ankra's `<project>/<app>/<component>` nesting, say so rather than reorganising Harbor: `--flat-repositories` addresses components as `<project>/<component>`, and `--component-repository backend=commerce-backend` names one outright. Both are used by publish readiness, the deploy gate and the generated workflow, so they describe what your pipeline already pushes.

***

## The robot Ankra mints

With a project-administrator credential in the declaration, every application gets a push robot of its own.

| | |
| - | - |
| **Name** | `robot$<project>+app-<application-id>` |
| **Rights** | `push` and `pull` on that one project - nothing else |
| **Expiry** | Non-expiring, so a build never fails at 2am because a token aged out |
| **Stored as** | The platform-managed registry credential `ankra-harbor-app-<application-id>` |
| **Delivered to** | The repository's Actions secrets, `ANKRA_REGISTRY_USERNAME` / `ANKRA_REGISTRY_PASSWORD` by default |

Nothing else shares that login, so a leaked repository secret is rotated or revoked for that one application, and a deleted application takes its robot with it.

```bash theme={null}
# Mint it (or confirm the existing one) and write its login into the repository
ankra application registry robot ensure <application-id>

# Show it: name, registry, created and last-rotated timestamps
ankra application registry robot get <application-id>

# Rotate after a leak - the old secret stops working the moment Harbor answers (refused when the admin credential is a robot, see the Step above)
ankra application registry robot rotate <application-id>

# Revoke: deletes the robot from Harbor and drops its credential
ankra application registry robot revoke <application-id> --yes
```

The same lives under **Settings** → **Image registry** in the portal, and on the API at `/api/v1/org/applications/{application_id}/registry-robot` (`GET`, `POST` with `{"rotate": true|false}`, `DELETE`).

### Checking it from the Harbor end

Project robots are not returned by Harbor's system robot listing; query them with the project id.

```bash theme={null}
# Find the project id
curl -u '<admin>' 'https://artifact.example.com/api/v2.0/projects/commerce-images' \
  -H 'X-Is-Resource-Name: true'

# List the project's robots (id from the previous call)
curl -u '<admin>' 'https://artifact.example.com/api/v2.0/robots?q=Level%3Dproject%2CProjectID%3D<id>'
```

A healthy application robot comes back enabled, with `expires_at: -1` and exactly `push repository` plus `pull repository` on its own project.

***

## Robot accounts you create yourself

The robots above are Ankra's: one push robot per application, and the organisation's `ankra-harbor-ci` and `ankra-harbor-pull` logins. For anything that logs in to your project without Ankra in the loop - a CI system you run yourself, a laptop pushing an image by hand, a cluster Ankra does not manage pulling from the project - create a robot of your own.

A robot is a named login bound to **one project**: your organisation's own, unless you [pick another](#scoping-a-robot-to-one-project). It is a project-level robot on the registry, so whatever it is allowed to do, it does it on that project and reaches nothing else on the registry. Its secret is shown exactly once, when it is created or rotated. The login is also stored as the managed registry credential `ankra-harbor-robot-<name>`, so clusters and applications can reference it like any other registry credential; it cannot be edited or deleted through the generic credential lanes, only revoked here.

```bash theme={null}
# Mint one. The secret is printed once, with the docker login that uses it.
ankra registry robots create jenkins --description "Jenkins on the office server"

# Pull-only, for a cluster outside Ankra
ankra registry robots create edge-cluster --scope pull

# Script it: the secret rides -o json as `secret`
ankra registry robots create jenkins -o json | jq -r .secret

# What exists (secrets are never listed)
ankra registry robots list
ankra registry robots get jenkins

# Lost or leaked: mint a new secret, the old one stops working
ankra registry robots rotate jenkins

# Done with it: deletes the robot from the registry and drops its credential
ankra registry robots delete jenkins --yes
```

| Field | Value |
| - | - |
| **Login** | `robot$org-<organisation-id>+user-<name>` |
| **Project** | One project: your organisation's own, or an [extra project](#scoping-a-robot-to-one-project) you pick |
| **Rights** | `push` = push and pull; `pull` = pull only; or your own list of permissions |
| **Expiry** | Never, unless you set one when creating it |
| **Credential** | `ankra-harbor-robot-<name>`, managed, revoked with the robot |

On the API the same lives at `/api/v1/org/registry-robots`; creating and rotating need `credentials.write`, revoking `credentials.delete`. Names are 2 to 32 lower-case letters, digits and hyphens.

### Exactly the permissions a job needs

Push-and-pull fits a build and pull fits a cluster. A cleanup job that deletes old artifacts, a release job that moves a tag, or a scanner that reads reports needs something else, and should not be handed a login that can also push. State the permissions instead of a scope:

```bash theme={null}
# What can be granted
ankra registry robots permissions

# A cleanup job: read what is there, delete what is old, nothing else
ankra registry robots create cleanup \
  --permission repository:pull,artifact:list,artifact:delete

# A contractor's pull login that stops working after 30 days
ankra registry robots create contractor --scope pull --expires-in-days 30
```

| Permission | Allows |
| - | - |
| `repository:pull` | Pulling images and charts |
| `repository:push` | Pushing images and charts. Pull comes with it, because a client pushing asks the registry for both |
| `repository:list`, `repository:read` | Listing the project's repositories and reading one through the registry API |
| `repository:delete` | Deleting a whole repository and every artifact in it |
| `artifact:list`, `artifact:read` | Listing a repository's artifacts and reading one: digest, size, labels, scan summary |
| `artifact:delete` | Deleting artifacts |
| `tag:list`, `tag:create`, `tag:delete` | Listing tags, adding a tag to an artifact that is already pushed, and removing one |
| `scan:create`, `scan:read` | Starting a vulnerability scan and reading its report |

Every permission is a right on the **content** of your project. None of them administers the project - its members, robots, quota or retention stay with Ankra - and none of them reaches another project. `--scope` and `--permission` are alternatives; stating both is refused.

Because some of these permissions delete images, creating a robot with any permission other than pull and push needs the `credentials.reveal` permission as well as `credentials.write`. Administrators and owners hold both; a preset robot, or one that lists only pull and push, needs only `credentials.write`.

`--expires-in-days` is enforced by the registry: after that many days the login stops working. Rotating a robot gives it a new secret and never more time, so an expired robot is revoked and created again rather than rotated.

### Scoping a robot to one project

Everything your organisation publishes lands in one registry project, so a robot bound to it can reach all of it. To give a login less, keep some images apart: create an extra project, push those images there, and bind the robot to that project. A robot reaches the one project it is bound to and nothing else on the registry.

```bash theme={null}
# Your projects: your organisation's own is called default
ankra registry projects list

# An extra project for what the staging pipeline builds
ankra registry projects create staging

# A robot that can push and pull there, and nowhere else
ankra registry robots create staging-ci --registry-project staging
```

`ankra registry projects list` prints where to push for each project. An extra project named `staging` is `org-<organisation-id>-staging` on the registry, so its images are `<registry host>/org-<organisation-id>-staging/<repository>`.

| | |
| - | - |
| **Names** | 2 to 30 lower-case letters, digits and single hyphens, starting and ending on a letter or digit. `default` is your organisation's own project |
| **How many** | Up to 5 extra projects per organisation |
| **Settings** | Private, with the same scan policy, retention policy and storage quota as your own project |
| **Robots** | One project per robot. A job that needs two projects uses two robots |
| **Permissions** | Listing needs `credentials.read`, creating `credentials.write`, deleting `credentials.delete` |

Deleting a project never deletes anything else on the way. `ankra registry projects delete staging` is refused while the project still holds repositories, and while robot accounts are still bound to it: delete the repositories from the registry and revoke the robots first. Your organisation's own project cannot be deleted.

Ankra's own lanes keep using your organisation's own project: applications build into it, and clusters pull from it with the `pull` robot. An extra project is for what you push yourself, and a cluster pulls from it with a robot you bind to it, referenced through its credential `ankra-harbor-robot-<name>`.

### Robots on a Harbor you run yourself

If your organisation runs its own Harbor and has connected it to Ankra as an OCI registry, the same commands create robots there too. Name the registry entry, a credential of yours that may manage robot accounts on it, and the **one project** of that registry the robot is bound to. Ankra mints, rotates and revokes the robot with that credential, and never uses its own registry administrator on a registry it does not run. On the **Registry robots** page, pick the registry under **Registry** in the create dialog: the projects it offers are the ones your Harbor holds.

```bash theme={null}
# The OCI registry entries your organisation has connected (a connected
# Harbor is an OCI Helm registry to Ankra, so it is listed with them)
ankra helm registries list

# The projects that registry holds, as the admin credential sees them
ankra registry projects list \
  --registry smartoptics-harbor \
  --admin-credential smartoptics-harbor-robot-admin

# A push robot that reaches only the collectorcharts project
ankra registry robots create collector-ci \
  --registry smartoptics-harbor \
  --admin-credential smartoptics-harbor-robot-admin \
  --registry-project collectorcharts

# Inspect and revoke it like any other robot, and rotate it when the admin
# credential is a Harbor user (a robot admin cannot, see above). A robot's
# name is unique across your organisation's registries, so the name alone
# says which robot, and which registry, these act on.
ankra registry robots rotate collector-ci
ankra registry robots get collector-ci
ankra registry robots delete collector-ci --yes
```

| Setting | What it is |
| - | - |
| **Registry** | An OCI registry entry of your organisation, other than the Ankra registry |
| **Admin credential** | A registry credential you stored, with project administrator rights (robot accounts) on the project. A robot login Ankra manages cannot be used |
| **Project** | Required: one project of that registry, by its name there (such as `collectorcharts`). The robot reaches that project and no other |
| **Login** | `robot$<project>+user-<name>`, with your registry's robot prefix |
| **Permissions** | The same scopes, permissions and expiry as on the Ankra registry. Creating one, and listing that registry's projects, also needs `credentials.reveal`, because Ankra acts as your admin credential. So does connecting the registry entry itself with a stored credential, which Ankra then sends to that registry's host |

A robot of the same name that already exists on your registry is left alone, and the create is refused: pick another name or delete it in Harbor first. If the registry entry is deleted, or now points at another host, rotating the robot is refused and revoking it removes Ankra's copy of the login only; delete the robot in Harbor yourself if it still exists. A registry that refuses the admin credential is reported as such, so check the credential's rights on the project.

### Seeing every robot, including Ankra's

`ankra registry robots list` and the **Registry robots** page list every login your project honours, not only the ones you created: yours first, then the ones Ankra manages.

| Kind | Robots | Who rotates it |
| - | - | - |
| `user` | The ones you created | You, with `robots rotate` |
| `organisation` | `ci` (push and pull, behind `ankra-harbor-ci`) and `pull` (behind `ankra-harbor-pull`) | Ankra |
| `application` | One push robot per application, on the registry that application publishes to | Ankra, or you with `ankra application registry robot rotate <application>` |

`--kind` narrows the listing to one kind, or to `managed`, which is shorthand for everything Ankra minted: the `organisation` and `application` robots together.

```bash theme={null}
ankra registry robots list                      # everything
ankra registry robots list --kind user          # only yours
ankra registry robots list --kind managed       # organisation and application robots
ankra registry robots list --kind application   # one push robot per application
ankra registry robots get ci
```

Managed robots are read-only here. Ankra hands each one's secret to the builds and clusters that use it, so rotating or revoking one from this lane would strand them; `rotate` and `delete` refuse a managed robot and say so. An application robot minted on a registry you run yourself shows that registry's host and project.

## Pull secrets in your clusters

The generated manifests reference the pull secret through `imagePullSecrets`, and Ankra keeps that Secret in place for you - **per cluster and per namespace**, without you registering anything.

* On **every deploy**, the target namespace is added to that cluster's registry pull-secret resource for the Secret the declaration names (`harbor-registry` above, `ankra-registry-pull` by default), and the resource is re-applied so the Secret exists in the new namespace.
* A cluster carries **one resource per Secret name**, so an application pulling from your Harbor coexists with every other application pulling from Ankra's own registry - registering a namespace on one never rewrites the other's.
* **Rotation fans out**: rotating the robot flips the deployed resources so the new login replaces the old one in each cluster.
* Clusters imported before the registry existed get the resource created on the spot.

```bash theme={null}
# What the cluster actually holds
ankra cluster select <cluster>
ankra cluster get secrets --all-namespaces
```

```
harbor-registry        commerce    kubernetes.io/dockerconfigjson
harbor-registry        insight     kubernetes.io/dockerconfigjson
ankra-registry-pull    default     kubernetes.io/dockerconfigjson
```

> [!NOTE]
>
> The Secret is built from the declaration's **read** credential, at the declared host. A declaration with no read credential registers no namespace and creates no Secret, which surfaces in the cluster as `ImagePullBackOff` on a private project rather than as an error in Ankra.

***

## Verifying the whole path

`ankra application publish-readiness <application-id>` answers the four questions that matter, and distinguishes "nothing published" from "cannot see", so an unreadable registry never reads as an empty one.

| Check | `ok` means | Common warning |
| - | - | - |
| Image registry | The declaration resolved and Ankra can read the project with the named credential | No credential named, or the project is not visible to it |
| Registry login secrets | The repository carries the two Actions secrets the workflow logs in with | Missing - mint the robot, or write them yourself |
| Publish workflow | The workflow on the default branch publishes to the declared repository | Publishes somewhere else: the declaration changed after setup. Reconcile the application and merge its setup pull request |
| Image artifact | At least one image exists in the repository | `No image has been pushed yet` - the first successful build publishes it, and deploy stays blocked until it exists |

***

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| `robot ensure` fails with a Harbor permission error | `admin_credential_name` points at a robot Harbor does not let mint robots on that project: one without `robot` create, list and delete, a system robot before Harbor 2.14.1, or any robot before 2.12.0 | Use a Harbor user with Project Admin, or a robot with the permission set above on a Harbor release that allows it |
| `registry set` is refused: `The project 'x' does not exist on 'host', and the registry credential ... may not create it` | The project is missing and the admin credential has no project-creation right | Create the project in Harbor and make the credential its Project Admin, or allow the credential to create projects (a user under *Project creation: Everyone*, or a system robot with `project` create) |
| `registry set` is refused: `... may not read or list projects on 'host', so the project 'x' could not be checked` | The admin credential has neither project read on `x` nor system-level `project:list` | Grant the robot system `project` list (and create), as in the permission table above |
| `registry set` is refused: `The project 'x' exists on 'host' but the registry credential ... cannot see it` | The project is private and the admin credential is not a member of it | Make the credential a Project Admin of that project |
| A build fails at the push with `project x not found`, and the declaration was set without `--admin-credential` | The project was never checked, because nothing could check it | Create the project, or redeclare with `--admin-credential` so Ankra checks or creates it |
| Publish readiness says the application never published, but images are in Harbor | No read credential on the declaration, or the credential cannot see the project | Name a read credential with project read + repository list/read |
| Publish readiness says the workflow publishes elsewhere | The registry was declared after the application was created | `ankra application reconcile <application-id>`, then merge the setup pull request it raises |
| Pods report `ImagePullBackOff` on a private project | No read credential, so no pull secret was created | Add `--credential` to the declaration and redeploy |
| Images land at unexpected repository paths | Your Harbor's layout is not Ankra's nesting | `--flat-repositories`, or `--component-repository <component>=<repository>` |

***

## Related

> [card] [Using your own registry](/concepts/applications#using-your-own-registry)
>
> The declaration's every field, and how components inherit it.

> [card] [Robot accounts](/concepts/applications#robot-accounts)
>
> The per-application robot on Ankra's own registry.

> [card] [Registry credentials](/platform/credentials/registry)
>
> Storing the credentials this guide names.

> [card] [CI/CD pipeline](/guides/cicd-pipeline)
>
> The build workflow that logs in with the robot.


# Hetzner Clusters
Source: https://docs.ankra.ai/guides/hetzner-clusters

Create a Kubernetes cluster on servers in your own Hetzner Cloud project, with Ankra installing and operating Kubernetes, ingress, TLS and DNS.

Choose Hetzner when you want a multi-node Kubernetes cluster on Hetzner Cloud servers in Germany, Finland, the US or Singapore, in a project you own. Ankra creates the servers, private network and bastion in your Hetzner Cloud project, installs Kubernetes and the Hetzner cloud integration, and then operates the cluster for you - this is an **Ankra Managed** cluster. Hetzner bills you directly for the servers.

[Kubernetes on Hetzner Cloud in five minutes with Ankra](https://www.youtube-nocookie.com/embed/9haqDULB6Pk?rel=0)

## Before you start

> [!NOTE]
>
> **Add a payment method first.** Creating a Hetzner cluster needs a payment method on your Ankra organisation. Without one, the create is refused with "The cluster was not created ... Add a payment method". Save a card from [guided setup](/get-started/guided-setup) or **Billing** - see [Credit and payment method](/platform/billing#credit-and-payment-method). The free [playground](/guides/cluster-sandbox) is the only cluster that works without one.

* A **payment method** on the organisation, as above.
* A **Hetzner Cloud API token** with **Read & Write** permissions, stored as a [Hetzner credential](/platform/credentials/hetzner): in the new Ankra portal, **Integrations & alerts → Credentials → Add credential → Hetzner Cloud**. No Hetzner account yet? [Sign up for Hetzner Cloud](https://www.hetzner.com/cloud).
* At least one **SSH key credential** - required for every Hetzner cluster. Add it at **Integrations & alerts → Credentials → Add credential → SSH key**: paste a public key, or generate a 4096-bit RSA key pair in the browser, which downloads the private key once. See [SSH Key Credentials](/platform/credentials/ssh-key).
* Room in your Hetzner project's limits for the servers, a network and the SSH keys. Check them in the [Hetzner Console](https://console.hetzner.cloud); Hetzner support raises them.

## Create the cluster

> [tab] Dashboard
>
> The new Ankra portal (`/next` on your portal's address, for example `https://platform.ankra.app/next/clusters/new?provider=hetzner`) walks you through one form:
>
> **1. Open the Hetzner wizard**
>
> Go to **Infrastructure → Clusters**, click **Add a cluster** and pick **Hetzner**.
>
> **2. Name and purpose**
>
> Name the cluster and pick its purpose: **Production**, **Staging**, **Development**, **Testing** or **Local**.
>
> **3. Credential, SSH key and location**
>
> Pick the Hetzner credential, one or more SSH keys, and the location, for example `fsn1`, `nbg1` or `hel1`.
>
> **4. Control plane and servers**
>
> Choose **1** or **3** control plane nodes, the management (bastion) server type, and one or more node groups of workers. Pick server types the location can provision right now - the `cx` line is often unavailable; see [Server types](#server-types). A cheap set that works: `cpx12` for the management server, `cpx22` for the control plane and workers.
>
> **5. Kubernetes**
>
> Keep **kubeadm** (the default, with Cilium) or pick **k3s**, and optionally the version. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) for the CNI and etcd options.
>
> **6. Git repository (optional)**
>
> Optionally connect a Git repository; Ankra commits the cluster's stacks to it. By default the cluster also gets the networking stack (Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind a Hetzner Load Balancer) and a delegated subdomain on `ankra.cc` with external-dns wired, so an ingress hostname under it gets its DNS record and TLS certificate automatically.
>
> **7. Review and create**
>
> **Review** shows the choices and a cost estimate. Click **Create**. A progress view follows the network, bastion, servers, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials hetzner create --name my-hetzner-token   # prompts for the token
> ankra credentials hetzner ssh-key create --name my-ssh-key --generate
>
> # Check what the location can provision now; use rows with AVAILABLE=yes
> ankra cluster hetzner server-types --credential-id <hetzner-credential-id> --location fsn1
>
> ankra cluster hetzner create \
>   --name my-cluster \
>   --credential-id <hetzner-credential-id> \
>   --ssh-key-credential-ids <key-id-1>,<key-id-2> \
>   --location fsn1 \
>   --control-plane-count 1 \
>   --worker-count 2 \
>   --bastion-server-type cpx12 \
>   --control-plane-server-type cpx22 \
>   --worker-server-type cpx22
> ```
>
> `cx` types are often unavailable in `fsn1` and other locations, so pick the `--bastion-server-type`, `--control-plane-server-type` and `--worker-server-type` values from the `AVAILABLE=yes` rows of `server-types` (`--available-only` hides the rest). Leave a flag out and Ankra picks a type for that role from what the location can provision at that moment (see [Server types](#server-types)). `ankra cluster hetzner locations` lists the locations your credential can use. `--distribution k3s`, `--etcd-topology external`, `--include-networking=false` and the `--gitops-*` flags cover the other choices.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/hetzner \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<hetzner-credential-id>",
>     "ssh_key_credential_ids": ["<key-id-1>", "<key-id-2>"],
>     "location": "fsn1",
>     "control_plane_count": 1,
>     "control_plane_server_type": "cpx32",
>     "node_groups": [
>       {"name": "default", "instance_type": "cpx32", "count": 2},
>       {"name": "gpu-workers", "instance_type": "ccx33", "count": 1, "labels": {"gpu": "true"}, "taints": [{"key": "gpu", "value": "true", "effect": "NoSchedule"}]}
>     ],
>     "include_networking": true,
>     "include_dns": true,
>     "gitops_credential_name": "my-github-token",
>     "gitops_repository": "my-org/my-repo",
>     "gitops_branch": "main"
>   }'
> ```
>
> The `gitops_*` fields are optional; with them, Ankra commits the hcloud stack (and the networking stack, when included) to the repository after creation. `worker_count` and `worker_server_type` are still accepted, and `node_groups` wins when both are given; the singular `ssh_key_credential_id` is merged with `ssh_key_credential_ids`. Leave out `bastion_server_type` (as here), `control_plane_server_type` or `worker_server_type` and Ankra picks one for that role; the response's `server_types` object names the type each role got. Every field and default is in the [Hetzner Reference](/reference/hetzner).

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created in your project

* **A private network** that every server joins. Nodes have private addresses only.
* **A bastion** - the only server with a public IP. It is the SSH jump host and also the NAT gateway for all node egress, so stopping or deleting it cuts the nodes off from the internet.
* **Control plane and worker servers**, and your SSH keys registered in the project.
* **The hcloud stack** in the `hcloud` namespace: the Hetzner cloud controller manager (Load Balancers for `LoadBalancer` Services, node metadata) and the CSI driver (Hetzner Volumes through the `hcloud-volumes` StorageClass), both using your credential's token.

The [Hetzner Reference](/reference/hetzner#architecture) has the full layout and the CCM and CSI configuration.

## Server types

Hetzner's stock of a server type changes by location and by hour. The cost-optimised `cx` line is sold in limited quantities and is often unavailable altogether: on 2026-10-28 `fsn1` offered only `cpx`, `ccx` and `cax` types. `cpx12` for the bastion and `cpx22` for the control plane and workers is a cheap set that was available. A type that is out of stock is refused when you create the cluster, add a node group, or resize one, so check what a location sells right now with `ankra cluster hetzner server-types --credential-id <hetzner-credential-id> --location fsn1 --available-only` rather than relying on that example.

* **Leave a server type out** and Ankra picks it when the cluster is created, from what the location can provision at that moment: the cheapest x86 type with at least 2 vCPU and 4 GB for the bastion and workers, and at least 4 vCPU and 8 GB for the control plane and dedicated etcd nodes. Out-of-stock and deprecated types are skipped. The create response and the AI's create result name the type each role got.
* **Name a type** and Ankra checks it against the location first. If the location cannot provision it, the create is refused with the types of at least that size it can provision instead, cheapest first. The sizes above are only what Ankra picks by default, not a minimum for a type you name: `cpx22` (2 vCPU, 4 GB) runs a small control plane, and `cpx32` (4 vCPU, 8 GB) matches the default.
* **For a node group that autoscales**, pick a type the location sells reliably. Each scale-up orders a new server of the group's type, so a group on a type that goes out of stock cannot grow until it is back.

## Hetzner specifics

* **Disk growth is irreversible.** Moving a node group to a larger server type enlarges each server's disk, which Hetzner cannot shrink, so a group can never move back to a smaller type. Each node is powered off, resized and powered on, with brief downtime for its workloads. For smaller nodes, create a new group and delete the old one.
* **A single control plane can be resized while the cluster runs.** Hetzner changes the server type in place and keeps its disk and IP address, so Ankra can resize the only controller of a running cluster. The Kubernetes API is down for a few minutes while it reboots, workloads on the workers keep running, and you accept the downtime first. A larger type grows the controller's disk too, and that is also one-way. See [Change the control plane instance type](/guides/operate-ankra-managed-clusters#change-the-control-plane-instance-type).
* **Restart** is a native reboot, falling back to a power cycle when the server does not respond.
* **SSH keys are shared by fingerprint.** Hetzner registers a public key once per project, so a key used on several Ankra Hetzner clusters is one Hetzner key object, and terminating any of those clusters deletes it. Running nodes keep working (their `authorized_keys` are already written), and the next key sync registers it again.
* **What a terminate touches.** Servers, the network and SSH keys are deleted by the IDs Ankra recorded - Ankra never lists your project and deletes what it finds. Just before the network is deleted, three scoped sweeps run: servers carrying this cluster's `ankra-cluster-id` label **and** attached to its network, volumes carrying that label, and Load Balancers attached to its network **or** carrying that label. That last filter is a union, so a Load Balancer you attached to the cluster's network by hand is removed too. Load Balancers are deleted on every terminate, because an attached one blocks the network delete. Your Hetzner API token is never touched.
* **Keeping a volume.** A Hetzner Volume labelled `ankra-retain` is kept when the cluster is terminated.

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `hetzner`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Cluster stuck in provisioning | Check the token's permissions and your project limits in the [Hetzner Console](https://console.hetzner.cloud) |
| Invalid API token | Create a new read and write token and [rotate the credential](/platform/credentials/hetzner) |
| Server type unavailable | Run `ankra cluster hetzner server-types --credential-id <id> --location <location>` and pick a type marked available, often from the `cpx` line |
| "The cluster was not created ... Add a payment method" | Save a payment method on the organisation under **Billing**, then create the cluster again |
| `412: error during placement` | Hetzner has no capacity for that type at that location. Retry later or pick another server type |
| Cannot move a node group to a smaller type | Hetzner disks cannot shrink. Create a new node group and delete the old one |
| Node keeps the `uninitialized` taint | The CCM removes it once it has initialised the node. Check that the CCM pods run: `kubectl get pods -n hcloud` |
| `LoadBalancer` Service stuck in `Pending` | Check the CCM pods in `hcloud` and their logs for Hetzner API errors |
| PVCs stuck in `Pending` | Check the CSI pods in `hcloud` and that the `hcloud-volumes` StorageClass exists |
| CCM or CSI pods in `CrashLoopBackOff` | Check that the `hcloud-token` Secret in `hcloud` holds a valid token: `kubectl get secret -n hcloud hcloud-token -o yaml` |
| Ankra Agent pod `Pending` | The agent tolerates the `uninitialized` taint; if every node is unschedulable for another reason, check `kubectl describe nodes` |


# Ankra Hosted Logs
Source: https://docs.ankra.ai/guides/hosted-logs

Keep a cluster's container logs in Ankra for 7 days, with no log store of your own, and search them from an application's log history. Turn it on from the application, the cluster's settings or the CLI.

An application's log **History** searches the logs its cluster keeps. Ankra hosted logs keeps them for you: the cluster's agent sends the log lines of every running container on the cluster to Ankra, where they are kept for 7 days and can be searched from each application's log history. There is no logging stack to install, run or connect.

Hosted logs are off by default and turned on per cluster. Nothing leaves a cluster until someone with permission to change it turns them on.

| | |
| - | - |
| **What is sent** | The log lines of every running container on the cluster |
| **Kept for** | 7 days, in Ankra's own log store |
| **Price** | Included during the pilot. The bytes and lines accepted are recorded as [usage](/platform/usage). |
| **Who can read them** | Members of your organisation, in each application's log history |
| **Who can turn them on or off** | People with the `clusters.write` permission on the cluster |

* **History starts when you turn it on.** Lines written while hosted logs are off are never sent later.
* **Your own log store comes first.** While a [log source](/integrations/log-sources) of your own is connected to the cluster, log history searches that store instead.
* **Live logs need none of this.** **Live** reads the running containers through the cluster's agent, with or without hosted logs.

> [!NOTE]
>
> Ankra turns hosted logs on platform by platform. Where they are not offered yet, you can still turn them on for a cluster, and nothing is sent until they are. The cluster's settings and `ankra cluster logs-ship status` say which applies to yours.

***

## Before you start

* **The cluster's agent must follow the switch.** An agent that is too old, or that has log shipping turned off in its own Helm values (`logs_ship.enabled`), sends nothing whatever the switch says. Upgrade it with `ankra cluster agent upgrade --cluster <cluster>`, or turn on automatic agent upgrades in the cluster's settings.
* **Your role needs `clusters.write` on the cluster.** Anyone else is told which roles can turn hosted logs on. See [Roles and access](/guides/roles-and-access).

***

## Turn it on from an application

**1. Open the application's logs**

In the new Ankra portal, open the application, choose **Health**, then **Logs**.

**2. Choose History**

When the cluster keeps no logs, History says so instead of showing an empty list: **Ankra hosted logs are off for this cluster.**, or **No log store is connected to this cluster.**

**3. Choose Turn on Ankra hosted logs**

A dialog says what is sent, how long it is kept, that it is included during the pilot, and that lines written while it is off are never sent later.

**4. Confirm**

Choose **Turn on hosted logs**. History then reads **Waiting for the first logs from \<cluster>.** and checks again every few seconds. The agent starts sending within a minute or two.

Hosted logs are turned on for the whole cluster, so every application with an environment on that cluster gets log history from then on.

***

## Turn it on from the cluster's settings

In the new Ankra portal, open the cluster, choose **Settings** and find **Ankra hosted logs**. It says in one sentence whether the cluster sends its logs to Ankra, and when that was last changed. Choose **Turn on hosted logs**, read the dialog, and confirm with **Turn on hosted logs**.

The same section turns hosted logs off: see [Turn it off](#turn-it-off).

***

## Turn it on with the CLI

Check the cluster first:

```bash theme={null}
ankra cluster logs-ship status --cluster <cluster>
```

The status says whether the cluster ships its logs, whether hosted logs are offered on your platform yet, and whether the cluster's agent follows the switch. Then turn it on:

```bash theme={null}
ankra cluster logs-ship enable --cluster <cluster>
```

`enable` says what is sent and asks before it turns anything on. `--yes` answers the question for scripts.

***

## What History tells you

When History has nothing to show, it says why, with the next step:

| What you see | What it means | What to do |
| - | - | - |
| **Ankra hosted logs are off for this cluster.** | Hosted logs are offered here but turned off for this cluster | **Turn on Ankra hosted logs**, or ask someone with one of the roles it names |
| **No log store is connected to this cluster.** | Neither hosted logs nor a store of your own keeps this cluster's logs | **Turn on Ankra hosted logs**, or **Connect your own log store**. Where hosted logs are not offered yet, History says so and offers only a store of your own. |
| **This cluster's agent cannot send logs to Ankra yet.** | The agent is too old to follow the switch, or log shipping is off in its own settings | Upgrade the agent with the command shown |
| **Waiting for the first logs from \<cluster>.** | Hosted logs were just turned on | Wait a minute or two. Lines written before it was turned on are not sent. |
| **Nothing from \<cluster> reached Ankra in the \<time range>.** | Hosted logs are on, but no line from the cluster arrived | **Check the cluster**: its agent sends the lines, so make sure it is connected |
| **Ankra's hosted logs hold nothing from \<namespace> in the \<time range>.** | Lines from the cluster arrive, but the application's containers wrote nothing in this window or were not running | Choose a longer time range, or read **Live** logs |

***

## Turn it off

In the cluster's **Settings**, under **Ankra hosted logs**, choose **Turn off hosted logs** and confirm. With the CLI:

```bash theme={null}
ankra cluster logs-ship disable --cluster <cluster>
```

The cluster stops sending its container logs to Ankra within a minute. Lines already sent stay readable until they are 7 days old. Lines written while hosted logs are off are never sent later.

***

## Related

> [card] [Logs](/platform/logs)
>
> Stream live logs from any workload through the cluster's agent.

> [card] [Log sources](/integrations/log-sources)
>
> Connect Loki, Elasticsearch or OpenSearch instead.

> [card] [Usage](/platform/usage)
>
> The hosted logs bytes and lines Ankra accepted, per cluster and period.

> [card] [Cluster settings](/platform/cluster-settings)
>
> The agent version, automatic upgrades and other per-cluster settings.


# Add a Cluster
Source: https://docs.ankra.ai/guides/import-cluster

Choose how to get a cluster into Ankra - import one you already run with a single helm command, have Ankra build one on your own cloud account, or create a provider-managed cluster such as EKS, GKE or AKS - and import an existing cluster step by step.

There are three ways to get a cluster into Ankra. If you already run one - EKS, GKE, AKS, k3s, on-premises, even minikube on your laptop - import it in a couple of minutes with one `helm` command. If you need a new one, Ankra can build it on your own cloud account, or create a cluster your cloud provider runs for you. A cluster you import, or one built on your own account, stays yours along with its servers: they keep running if you ever disconnect from Ankra. A [Playground](/guides/cluster-sandbox) and [Ankra Cloud](/guides/ankra-cloud-clusters) (Closed Beta) are the exceptions, because they run on servers Ankra operates.

## Which path is mine?

| You have... | You want... | Choose | Start here |
| - | - | - | - |
| A running cluster, anywhere | To manage it with Ankra | **Import** | [Import an existing cluster](#import-an-existing-cluster) below |
| A cloud or server account | A new cluster where Ankra installs, upgrades and operates Kubernetes for you | **Ankra Managed** | A provider guide under [Build a new cluster](#build-a-new-cluster) |
| An AWS, Google Cloud, Azure, DigitalOcean, OVHcloud, UpCloud or Scaleway (Closed Beta) account | A new cluster that your cloud provider runs (EKS, GKE, AKS, DOKS, MKS, UKS, Kapsule) | **Cloud Managed** | [Managed Kubernetes](/guides/managed-kubernetes) |
| Nothing yet | To try Ankra first | **Playground** | [Playground](/guides/cluster-sandbox) - a real cluster in about two minutes, no cloud account needed |

> [!TIP]
>
> **Already running EKS, GKE or AKS?** You can import it either way. The `helm` import below needs no cloud credential. A [managed import](/guides/managed-kubernetes#importing-existing-clusters) uses your cloud credential instead: Ankra fetches the kubeconfig, installs the agent for you, and the cluster gains the same node-pool and upgrade operations as clusters Ankra created.

## Import an existing cluster

Importing installs the Ankra agent in your cluster. The agent only makes outbound connections to Ankra, so the cluster can sit behind a firewall, NAT or a private network.

**You need:** `helm` and a kubeconfig for the cluster with permission to create a namespace and cluster-wide RBAC. The agent's permissions are described in [Agent compliance](/security/agent-compliance) and can be narrowed with [agent hardening](/security/agent-hardening).

A new organisation also needs a [payment method](/platform/billing#credit-and-payment-method) saved before it can import a cluster; only the free [playground](/guides/cluster-sandbox) runs without one.

**1. Create the cluster in Ankra**

Go to **Clusters**, click **Import**, give the cluster a name, and click **Import cluster**. The Git repository and add-on fields are optional - you can connect a repository and add Stacks later.

**2. Run the install command**

Ankra shows a `helm` command for this cluster. Copy it exactly as shown - it carries the cluster's own token and pins the agent version - and run it with your kubeconfig pointing at the cluster:

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --version <version> \
  --set config.ankra_url=https://platform.ankra.app \
  --set config.token=<your-cluster-token> \
  --namespace=ankra --create-namespace
```

**3. Check it is connected**

The cluster's status changes from **Awaiting Connection** to **Healthy**, usually within a minute. Open the cluster to browse its workloads, events and logs.

If it stays on **Awaiting Connection**, check the agent pod:

```bash theme={null}
kubectl get pods -n ankra
kubectl logs -n ankra -l app.kubernetes.io/name=ankra-agent --tail=50
```

The most common causes are egress to `platform.ankra.app` on port 443 being blocked, or a token copied from a different cluster. See [Ankra Agent](/concepts/cluster-agent) for more.

Watch an existing cluster being connected and its first Stack deployed:

[Getting Started with your existing cluster](https://www.youtube-nocookie.com/embed/ipZM7MMA_EU?rel=0)

Running Kubernetes on your laptop? [Run Kubernetes locally](/guides/minikube) sets up minikube and imports it.

## Build a new cluster

### Ankra Managed

Ankra creates the servers, private network and bastion on your own account, installs Kubernetes (kubeadm with Cilium by default, or k3s), and then operates it for you: upgrades, node groups, stop and start. The provider bills you directly. Creating one needs a [payment method](/platform/billing#credit-and-payment-method) on your Ankra organisation.

> [card] [Hetzner](/guides/hetzner-clusters)
>
> Hetzner Cloud servers in your Hetzner project.

> [card] [OVHcloud](/guides/ovh-clusters)
>
> Public Cloud instances in your OVHcloud project.

> [card] [UpCloud](/guides/upcloud-clusters)
>
> Cloud servers in your UpCloud account.

> [card] [DigitalOcean](/guides/digitalocean-clusters)
>
> Droplets in your DigitalOcean team.

> [card] [Scaleway (Closed Beta)](/guides/scaleway-clusters)
>
> Scaleway Instances in your Scaleway project.

> [card] [AWS EC2](/guides/aws-clusters)
>
> Self-managed Kubernetes on EC2 instances in your AWS account.

> [card] [Proxmox VE](/guides/proxmox-clusters)
>
> Virtual machines in your own Proxmox datacenter.

> [card] [HPE Morpheus (Closed Beta)](/guides/morpheus-clusters)
>
> Virtual machines through your Morpheus appliance.

> [card] [Ankra Cloud (Closed Beta)](/guides/ankra-cloud-clusters)
>
> Servers Ankra runs for you, with no cloud account of your own.

### Cloud Managed

Your cloud provider runs the Kubernetes control plane; Ankra creates the cluster and its node pools through your cloud credential, connects the agent, and manages what runs on it. Start with [Managed Kubernetes](/guides/managed-kubernetes), which compares the options, or go straight to [EKS](/guides/eks-clusters), [GKE](/guides/gke-clusters), [AKS](/guides/aks-clusters), [DOKS](/guides/doks-clusters), [OVHcloud MKS](/guides/ovh-mks-clusters), [UKS](/guides/uks-clusters), [Scaleway Kapsule](/guides/managed-kubernetes#scaleway-kapsule-closed-beta) (closed beta) or [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes) (closed beta).

## Next: deploy your first Stack

With the cluster showing **Healthy**, give it something to run. Step 2 of the [Quickstart](/get-started/quickstart) deploys a first Stack in a few minutes, and [Stacks](/concepts/stacks) explains the model behind it.


# Accessing Clusters with kubectl
Source: https://docs.ankra.ai/guides/kubeconfig

Run kubectl against your clusters through Ankra's authenticated API proxy - with short-lived, SSO-backed credentials and no inbound network access.

Once you have [Cluster Access](/guides/cluster-access) to a cluster, you can use your existing `kubectl` against it through Ankra. Ankra mints a short-lived token and points your kubeconfig at the **Ankra API proxy**, which forwards your requests through the agent to the cluster's API server. You never need direct network access to the cluster, and there are no static credentials to manage.

> [!NOTE]
>
> This works for clusters that have **no public API endpoint at all**. Because the agent dials out to Ankra (no inbound ports), the proxy reaches private clusters that `kubectl` could never hit directly.

***

## Prerequisites

* **The access gateway is enabled** for your deployment. When it isn't, the token and proxy endpoints return `404`.
* **The cluster has a connected Ankra agent.** Every request flows through the agent, so `kubectl` stops working while the cluster is offline and resumes when it reconnects.
* **You have a [Cluster Access grant](/guides/cluster-access) on the cluster.** Without one, `ankra cluster kubeconfig add` and `ankra cluster kube-token` fail with *"You do not have access to this cluster"*. This applies to **organisation admins too** - managing access does not itself include kubectl access, so admins must grant themselves a role first.
* **The grant has reconciled to `applied`.** A token can be minted as soon as the grant exists, but `kubectl` returns `Forbidden` until the RBAC is live on the cluster - check with `ankra cluster access list` or the cluster's **Access** view.
* **Ankra CLI v0.3.0 or later** for the `kubeconfig` and `kube-token` commands (run `ankra upgrade` to update).
* [Sandbox clusters](/guides/cluster-sandbox) do not support Cluster Access and cannot be reached this way.

***

## How it works

```mermaid theme={null}
flowchart LR
    kubectl[kubectl] -->|"minted kube-token"| Proxy[Ankra API proxy]
    Proxy -->|NATS| Agent[Ankra Agent]
    Agent -->|Kubernetes API| ApiServer[Cluster API server]
```

* Your kubeconfig server URL points at `…/api/v1/clusters/{cluster_id}/k8s` on the Ankra API host - not at the cluster directly.
* Each request carries a short-lived token. Ankra authenticates it, checks your [access grant](/guides/cluster-access), and forwards the call over NATS to the agent, which executes it against the API server.
* Standard `kubectl` behaviours work through the proxy, including `watch`, `kubectl logs -f`, and `kubectl exec` (these use streaming/websocket connections).

Your effective permissions are exactly the Kubernetes RBAC that your access grant created - a `view` grant can't mutate anything, a namespace-scoped grant can't see other namespaces.

You always act as yourself. The gateway strips any `Impersonate-*` headers from your requests, so `kubectl --as` and `--as-group` have no effect through Ankra, and the Ankra ClusterRoles your grant binds to carry no `impersonate` verb (see [No impersonation, escalation or bind](/guides/cluster-access#no-impersonation-escalation-or-bind)).

***

## With the Ankra CLI (recommended)

The [CLI](/integrations/ankra-cli) manages the Ankra entries in your kubeconfig for you. By default it writes an **exec-based** context that fetches a fresh token on demand via `ankra cluster kube-token`, so credentials stay ephemeral and SSO-backed.

**1. Log in once**

```bash theme={null}
ankra login
```

**2. Add a cluster context**

```bash theme={null}
# Add the selected cluster and make it active
ankra cluster kubeconfig add --cluster my-cluster --use

# Or add every cluster you can access
ankra cluster kubeconfig add --all
```

**3. Use kubectl as normal**

```bash theme={null}
kubectl --context ankra-my-cluster get pods
```

The CLI only ever touches the Ankra-managed contexts - other clusters, users, and contexts already in your kubeconfig are left untouched. It writes to `--kubeconfig` if given, otherwise the first entry of `$KUBECONFIG`, otherwise `~/.kube/config`.

### `ankra cluster kubeconfig` commands

| Command | Description |
| - | - |
| `add` | Add or update an Ankra context |
| `remove` | Remove Ankra-managed contexts |
| `list` | List Ankra-managed contexts in the kubeconfig |

### `add` flags

| Flag | Description |
| - | - |
| `--cluster <name\|id>` | Cluster to add (defaults to the selected cluster) |
| `--all` | Add every cluster you can access |
| `--use` | Set the added context as the active `current-context` (single cluster only) |
| `--namespace <ns>` | Default namespace for the context |
| `--print` | Print a standalone kubeconfig to stdout instead of writing the file |
| `--embed-token` | Embed a short-lived token instead of the auto-refreshing exec plugin |
| `--exec-command <bin>` | Executable kubectl invokes for credentials in exec mode (default `ankra`; use an absolute path if `ankra` isn't on `PATH`) |
| `--kubeconfig <path>` | Path to the kubeconfig file |
| `--insecure-skip-tls-verify` | Skip TLS verification (development only) |

> [!TIP]
>
> Prefer the default **exec mode** for day-to-day use - kubectl transparently refreshes the token as it expires. Use `--embed-token` only when you need a self-contained file for a tool that doesn't support exec credential plugins; the embedded token is short-lived and you'll re-run the command to refresh it.

> [!TIP]
>
> If your grant is **namespace-scoped**, add the context with `--namespace <ns>` set to that namespace. Otherwise plain `kubectl get pods` targets the `default` namespace and returns `Forbidden`, which looks like the grant is broken when it isn't.

### Remove a context

```bash theme={null}
ankra cluster kubeconfig remove --cluster my-cluster
ankra cluster kubeconfig remove --all
```

***

## From the portal

You can also generate a kubeconfig from a cluster's **Access** view in the portal. Ankra mints a short-lived token and returns a ready-to-use kubeconfig document with the proxy server URL and token already filled in. Save it and point `kubectl` at it:

```bash theme={null}
export KUBECONFIG=./ankra-my-cluster.yaml
kubectl get nodes
```

The downloaded kubeconfig embeds a short-lived token and stops working when the token expires - regenerate it when needed.

***

## Tokens, expiry, and rate limits

* **Short-lived tokens.** Both the exec-plugin token and the embedded kubeconfig token are time-boxed and expire automatically. The response includes an `expires_at`.
* **Capped by the grant.** A token cannot outlive the grant it was minted under. If your grant is [time-boxed](/guides/cluster-access#time-boxed-grants), a token minted under it stops working no later than the grant's expiry.
* **Rate limited.** Token and kubeconfig minting is rate limited per user; on large fleets prefer the default exec mode (which mints once) over `--embed-token --all` (which mints one token per cluster).
* **Revocable.** An admin can revoke a member's access at any time from [Cluster Access](/guides/cluster-access) (delete the grant, or revoke all). Existing tokens stop working.

***

## API

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/v1/clusters/{cluster_id}/k8s-token` | Mint a short-lived token (used by the kubectl exec credential plugin) |
| `POST` | `/api/v1/clusters/{cluster_id}/kubeconfig` | Generate a complete kubeconfig document |
| `*` | `/api/v1/clusters/{cluster_id}/k8s/...` | The Kubernetes API proxy endpoint your kubeconfig targets |

These are the **token-authenticated user-API** paths the CLI uses. The portal manages the same access through session-authenticated endpoints under `/org/clusters/{cluster_id}/access/...` - see the [Cluster Access API table](/guides/cluster-access#api).

The proxy requires the access gateway to be enabled; when it isn't, these endpoints return `404`. See [Cluster Access](/guides/cluster-access) for grants and the [CLI reference](/integrations/ankra-cli) for the full command set.


# Upgrade Kubernetes on a Cluster
Source: https://docs.ankra.ai/guides/kubernetes-upgrades

Move a cluster Ankra provisioned to a newer Kubernetes version one node at a time, know what to expect while it runs, resume a hop that stopped, and recover the cluster from a restore point.

Ankra upgrades Kubernetes in place on the clusters it provisions on a cloud provider: Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, Ankra Cloud, AWS EC2, Proxmox VE and HPE Morpheus, running k3s or kubeadm. This page covers what an upgrade does, how long it takes, which restore points exist, how to prepare, how to resume a hop that stopped, and how a cluster is recovered.

> [!NOTE]
>
> Clusters whose control plane your cloud runs (EKS, GKE, AKS, DOKS, UKS, OVHcloud MKS, Kapsule) are upgraded by the provider - see [Managed Kubernetes](/guides/managed-kubernetes#kubernetes-upgrades). Imported clusters are upgraded however you run them today.

***

## What an upgrade does

You start an upgrade from **Settings** → **General** → **Kubernetes Version** in the dashboard, with `ankra cluster upgrade <cluster> <version>` on the CLI, or with the MCP `upgrade_cluster` tool. All three start the same operation.

* **Only catalogue versions.** The target must be one Ankra lists: `ankra cluster k3s-versions` or `ankra cluster kubeadm-versions`.
* **One minor version per upgrade, never down.** 1.35 to 1.36 is one upgrade. To reach 1.37, run a second upgrade (a second hop) once the first has finished on every node. Downgrades are refused.
* **One node at a time.** Control planes go first, then workers. Each node is cordoned and drained, honouring PodDisruptionBudgets with a 300-second drain timeout. Its Kubernetes binary is then replaced in place and the node restarted. The virtual machine is not rebuilt, so its disks and attached volumes stay. The node must report `Ready` at the new version, and a control plane must also be etcd-healthy, before the next node starts.
* **Nodes already there are skipped.** A node at or above the target version is left alone; nothing is ever downgraded.
* **Workloads keep serving.** Pods move with each drain as they would for any reschedule. On a single control plane the Kubernetes API is unavailable for a few seconds while that node restarts; only changes and reads through the API wait.
* **k3s may restart once early.** A k3s upgrade can restart k3s on a node once early in the run, before the drain, which is a second short API gap.

### What to expect

Measured on a k3s cluster on Hetzner with one control plane and three workers:

| Phase | Typical duration |
| - | - |
| Each control-plane hop | About 2 minutes |
| Kubernetes API gap per control-plane hop | A few seconds (6 to 11 seconds measured), plus sometimes one early restart of about 8 seconds |
| Each worker | About 2 to 3.5 minutes, mostly the drain |
| A drain blocked by a PodDisruptionBudget | About 10 minutes of retrying before the upgrade parks at that node |

Total time grows with the node count and with how long your pods take to stop and start.

***

## Backups and restore points

An upgrade has up to three kinds of restore point for the cluster's state, and none of them covers application data.

### Scheduled Cluster State Snapshots

Ankra captures an encrypted etcd snapshot of every running cluster it provisions - every Secret, ConfigMap, custom resource and PersistentVolume binding - as a **Cluster State Snapshot**: once right after the cluster is created, then every 6 hours. It is stored off the cluster in your [backup vault](/concepts/backup-vaults), or in an Ankra-managed default vault when you have registered none. Each capture appears in `ankra cluster operations list` as **Scheduled etcd Snapshot**. This is the same snapshot a [stop and start](/platform/cluster-power-schedules#what-a-stop-does) uses. Scheduled captures pause while an operation such as an upgrade is running.

Ankra keeps the 4 newest snapshots plus the newest of each UTC day for 7 days, or for the window you set below. The newest snapshot from before the cluster's last start or recovery is kept whatever the window.

#### Set the retention window

You can set the window per cluster, between 1 and 90 days.

```bash theme={null}
ankra cluster state-snapshots retention              # show the window
ankra cluster state-snapshots retention --days 30    # keep 30 days of daily snapshots
```

A longer window keeps snapshots from then on; it cannot bring back ones already deleted. A shorter window deletes the daily snapshots outside it from the vault, so the command asks first (`--yes` skips the question). Setting the window needs permission to change cluster settings.

### A verified copy before each control-plane hop (Hetzner k3s)

On Hetzner clusters running k3s, before it upgrades the first control plane of a hop, Ankra writes an off-cluster copy of the cluster state to the vault and reads it back to check it. The other control planes of the hop, and a retry, reuse that verified copy for an hour. If the copy or the check fails, the step stops before the node is drained or its Kubernetes binary is replaced, and Ankra retries it on its own with backoff. Fix the cause, usually the backup vault; to retry at once, run `ankra cluster operations retry <operation-id>`. The step result shows the copy's id and checksum: `ankra cluster operations steps <operation-id> --results`. Other providers and kubeadm clusters take no copy before the hop; the scheduled snapshots above and the local snapshot below are their restore points.

### A local snapshot on the node's disk

On k3s, each control plane saves an etcd snapshot on its own disk before it is upgraded, named `ankra-pre-upgrade-<timestamp>`. On kubeadm, only the cluster's first control plane saves one, before it is upgraded; with a dedicated etcd cluster, each etcd node saves its own before it is upgraded instead. The newest three are kept on each node.

### Application data is yours to protect

> [!WARNING]
>
> None of these restore points contain the data on your volumes. Databases, queues and anything else on a PersistentVolume are covered only by an application backup. Protect stateful Stacks with [Ankra backups](/guides/backups#protect-a-stack) or your own tooling (for example CloudNativePG with Barman) before you upgrade, and confirm a recent restore point exists.

```bash theme={null}
ankra cluster backups status --cluster my-cluster
```

***

## Before you upgrade

* **Choose the target.** List versions with `ankra cluster k3s-versions` or `ankra cluster kubeadm-versions` and pick the next minor version, or a newer patch of the current one.
* **Check every node's version.** `ankra cluster get nodes` shows each node's version. Nodes already at the target are skipped.
* **Confirm the restore points.** Every stateful Stack is protected with a recent restore point (`ankra cluster backups status`), and the cluster has a recent **Scheduled etcd Snapshot** in `ankra cluster operations list`.
* **Check PodDisruptionBudgets.** A budget that allows zero disruptions - for example on a single-replica database - parks the upgrade at that node. Relax it for the window, scale the workload up, or move it to a node the hop skips.
* **Make databases stop in time.** A pod being evicted must shut down within the 300-second drain timeout. CloudNativePG's default stop delay is longer: lower it for the window, or move the primary off the node first.
* **Freeze other changes.** No scaling, node-group changes or other cluster operations during the window.
* **Leave control planes memory headroom.** Each hop restarts the Kubernetes server. A control plane running close to its memory limit may not come back cleanly; resize it first if it is tight.
* **Pick a window.** Plan for the timings in [What to expect](#what-to-expect).

### Run the upgrade preflight

`ankra cluster upgrade preflight my-cluster <version>` checks the hop without changing anything: the hop plan per node, running operations, PodDisruptionBudgets that would park the drain, CloudNativePG settings, control-plane memory, restore points, control-plane reachability and, on k3s, the address pins. Each check answers pass, warn, block or skipped. A block exits with code 8. The MCP `upgrade_preflight` tool returns the same report. Ankra runs the same preflight first on every upgrade you start, however you start it, and a block stops the upgrade before anything changes; `--force` goes past only a PodDisruptionBudget block; sent again with the version of an upgrade that is already running, it switches that upgrade to forced drains. If the preflight cannot run, the upgrade stops and changes nothing. The hop plan also blocks while Ankra has not yet read the Kubernetes version a control plane runs, which is normal for a few minutes after the cluster is created or a control plane is added: the refusal names the control plane and clears on the next read pass. If it does not clear, check that the node is reachable over SSH through the cluster's bastion.

***

## Run the upgrade

**1. Start the upgrade**

```bash theme={null}
ankra cluster upgrade my-cluster v1.36.4            # kubeadm: a plain upstream tag
ankra cluster upgrade my-cluster v1.36.4+k3s1       # k3s
```

In the dashboard, open **Settings** → **General**, pick the target under **Kubernetes Version** and confirm.

**2. Follow it**

```bash theme={null}
ankra cluster operations list --watch
ankra cluster operations steps <operation-id>
```

The steps show which node is being upgraded and where a hop stopped.

**3. Verify**

When the operation has finished, `ankra cluster get nodes` shows every node at the target version and `Ready`.

**4. Two minor versions? Run the second hop**

Start the next upgrade only once every node reports the first target. Then repeat from the first step.

***

## When a hop stops

A stopped upgrade can leave the control planes on the new version and some workers on the old one. That mixed state is supported: workloads keep running, and you can resume when the cause is fixed. While nodes are mid-rollout, running `ankra cluster upgrade` again with the same version is refused with "Kubernetes nodes are currently being reconciled"; resume the stopped operation instead:

```bash theme={null}
ankra cluster operations retry <operation-id>
```

| What happened | What Ankra does | What you do |
| - | - | - |
| A drain is blocked by a PodDisruptionBudget | Retries the drain for about 10 minutes, then parks the upgrade at that node and uncordons it. The other workers' steps are cancelled and planned again on their own within about 10 minutes; they park too while the blocker remains | Relax the budget or add replicas, then `ankra cluster operations retry <operation-id>` |
| You cancelled the upgrade (`ankra cluster operations cancel <operation-id>`) | Marks the run cancelled at once, but the node being upgraded finishes its whole upgrade (about 3 minutes) and is uncordoned. A cancel does not stop the upgrade for good: Ankra plans the remaining nodes again on its own, usually within about 10 minutes | Nothing, or `ankra cluster operations retry <operation-id>` to resume sooner, once the node being upgraded has finished (until then the retry is refused with "Execution still has steps stopping"); keeping the upgrade stopped needs an operations hold, which only Ankra staff can place |
| Any other failure | Retries automatically with backoff | Follow it with `ankra cluster operations steps <operation-id>` |

> [!WARNING]
>
> `ankra cluster upgrade --force` drains past PodDisruptionBudgets. That can take down quorum-based workloads such as etcd, ZooKeeper or a replicated database. Use it only when you accept evicting past the budget. The MCP `upgrade_cluster` tool never forces.

While Ankra holds a cluster for a recovery, a new upgrade request is refused with a message naming when the hold ends; run it again after that time.

If a node is still cordoned after you have fixed the cause and nothing is running, put it back with `ankra cluster uncordon <node>`.

***

## Rolling back a failed control plane

Downgrades are not offered through the dashboard, the CLI or the API. If a control plane does not come back on the new version, [contact Ankra support](/platform/support). Ankra performs the rollback in one of two ways:

* **Put the previous binary back.** The control plane returns to the previous Kubernetes version with its data kept, in seconds. This works only when the old and new Kubernetes versions ship the same etcd minor version. 1.35 to 1.36 does. 1.36 to 1.37 does not: 1.37 moves to etcd 3.7 and converts the data as soon as it starts, so 1.36 can no longer read it.
* **Restore the cluster state.** Otherwise Ankra restores the cluster state from the newest snapshot taken before the hop, at the matching Kubernetes version: the local `ankra-pre-upgrade-<timestamp>` snapshot when the control plane's disk is still readable; else, on Hetzner k3s, the verified copy taken before the hop; or else the newest scheduled snapshot, which can be up to 6 hours old because scheduled captures pause while the upgrade runs. In testing the Kubernetes API was unavailable for about 40 seconds.

A state restore reverts every change made through the Kubernetes API after the snapshot, including where pods run: a stateful pod that moved to another node after the snapshot is restarted on its old node, and its volume is reattached there. Data on volumes is not touched. Apply again any changes you made through the API after the snapshot.

With a single control plane there is nothing to fail over to, so the Kubernetes API is unavailable until one of these two ways has brought the control plane back.

After a rollback the cluster reads its previous version and Ankra does not upgrade it again by itself. Fix what made the hop fail, then start the upgrade again when you are ready.

***

## Disaster recovery from the off-cluster copy

You can rebuild a whole cluster from its state captured off-cluster yourself. A stop captures the state and terminates the virtual machines; a start with the state restored builds new ones from it:

```bash theme={null}
ankra cluster hetzner stop my-cluster                          # capture state, then tear down
ankra cluster hetzner start my-cluster --restore-state=true    # require the captured state
```

The same commands exist under `ovh`, `upcloud`, `digitalocean`, `proxmox` and `morpheus`, the providers whose stop terminates the virtual machines. On Scaleway, AWS EC2 and Ankra Cloud a stop powers the servers off and keeps them, so there is nothing to rebuild. With `--restore-state=true` the start is refused if no captured state exists; without the flag, a start restores it when there is one.

The cluster comes back with new virtual machines and new IP addresses, at the same Kubernetes version. StatefulSets reattach their same cloud volumes with their data, Secrets, ConfigMaps and other objects come back as they were at the capture, and the Ankra agent comes back online. In testing on Hetzner a stop with the capture took about 2.5 to 3 minutes and a start with the restore about 6 minutes. See [Stop, Start and Power Schedules](/platform/cluster-power-schedules) for every option.

### Apply conflicts after a restore

After a restore Ankra applies the cluster's Stacks again. An object you changed directly through the Kubernetes API after its Stack deployed - for example with `ankra cluster patch` - can make that apply report server-side apply conflicts. The object itself is correct. Re-apply the Stack, or reconcile it, so Ankra takes the object back under its management; and put lasting changes into the Stack rather than patching live.

***

## FAQ

> [accordion] Does an upgrade touch my volumes?
>
> No. Nodes are upgraded in place, so their disks and attached volumes stay. Pods using a volume move with the drain and reattach as they would for any reschedule.

> [accordion] How long does an upgrade take?
>
> About 2 minutes per control plane and 2 to 3.5 minutes per worker, one node at a time - see [What to expect](#what-to-expect).

> [accordion] Can I skip a minor version?
>
> No. Run one upgrade per minor version and let each finish on every node before starting the next.

> [accordion] Is it safe to leave a cluster half upgraded?
>
> Yes, for as long as it takes to fix what stopped it. Control planes on the new version with workers on the old one is a supported state and workloads keep running. Resume with `ankra cluster operations retry`.

> [accordion] Are patch versions upgraded automatically?
>
> Only if you turn on **Auto upgrade patch versions** under **Settings** → **General** → **Kubernetes Version**. Minor versions are never upgraded automatically.

***

## Next steps

* [Operate an Ankra Managed Cluster](/guides/operate-ankra-managed-clusters) - node groups, control plane, restarts, stop, start and terminate.
* [Backups and Restore Points](/guides/backups) - protect stateful Stacks before an upgrade.
* [Stop, Start and Power Schedules](/platform/cluster-power-schedules) - how Cluster State Snapshots carry a cluster across a stop.
* [CLI reference](/reference/cli/cluster#ankra-cluster-upgrade) - every flag of `ankra cluster upgrade`.


# Managed Kubernetes
Source: https://docs.ankra.ai/guides/managed-kubernetes

Provision, import, and operate Cloud Managed Kubernetes clusters - DOKS, UKS, GKE, OVHcloud MKS, AKS, EKS, Scaleway Kapsule, and Ankra Cloud Kubernetes - with Ankra.

Ankra provisions and manages **Cloud Managed** Kubernetes - the create dialog's term for clusters whose control plane your cloud provider runs. Ankra handles everything on top: node pools, Kubernetes upgrades, add-ons, stacks, GitOps, and AI-assisted operations.

This page is the shared overview. Each provider has its own guide with the specifics:

> [card] [DigitalOcean (DOKS)](/guides/doks-clusters)

> [card] [UpCloud (UKS)](/guides/uks-clusters)

> [card] [Google (GKE)](/guides/gke-clusters)

> [card] [OVHcloud (MKS)](/guides/ovh-mks-clusters)

> [card] [Azure (AKS)](/guides/aks-clusters)

> [card] [Amazon (EKS)](/guides/eks-clusters)

> [card] [Scaleway Kapsule (Closed Beta)](/guides/managed-kubernetes#scaleway-kapsule-closed-beta)

> [card] [Ankra Cloud Kubernetes (Closed Beta)](/guides/ankra-cloud-kubernetes)

| Provider kind | Service | Credential |
| - | - | - |
| `doks` | [DigitalOcean Kubernetes (DOKS)](/guides/doks-clusters) | DigitalOcean API token |
| `uks` | [UpCloud Managed Kubernetes (UKS)](/guides/uks-clusters) | UpCloud API token |
| `gke` | [Google Kubernetes Engine (GKE)](/guides/gke-clusters) | GCP service account key |
| `ovh_mks` | [OVHcloud Managed Kubernetes (MKS)](/guides/ovh-mks-clusters) | OVHcloud application keys + Public Cloud project |
| `aks` | [Azure Kubernetes Service (AKS)](/guides/aks-clusters) | Azure service principal |
| `eks` | [Amazon EKS](/guides/eks-clusters) | AWS credential (access keys or IAM role) |
| `kapsule` | [Scaleway Kapsule](#scaleway-kapsule-closed-beta) (Closed Beta) | [Scaleway API key](/platform/credentials/scaleway) |
| `ankracloud_k8s` | [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes) (Closed Beta), with a [production or development control plane](/guides/ankra-cloud-kubernetes#choosing-a-control-plane) | Ankra Cloud API token |

> [!WARNING]
>
> **Closed beta.** Scaleway - Kapsule and Ankra Managed clusters on Scaleway Instances alike - is in closed beta and enabled per organisation on request; until it is, Scaleway does not appear as a provider. [Contact support](/platform/support) to have it turned on for your organisation.
>
> **Closed beta.** Ankra Cloud - Ankra Cloud Kubernetes and Ankra Managed clusters on Ankra Cloud servers alike - is in closed beta and enabled per organisation on request; until it is, Ankra Cloud does not appear as a provider. [Contact support](/platform/support) to have it turned on for your organisation.

## Cloud Managed or Ankra Managed

The create dialog offers two kinds of cluster. **Cloud Managed** (this page) is usually the fastest path when your provider offers it. **Ankra Managed** clusters are built by Ankra on your own servers or cloud account, give you full control of the control plane, and run anywhere you have compute - see [Build a new cluster](/guides/import-cluster#ankra-managed) and [Operate an Ankra Managed Cluster](/guides/operate-ankra-managed-clusters).

| | Cloud Managed | Ankra Managed |
| - | - | - |
| Providers | DOKS, UKS, GKE, OVHcloud MKS, AKS, EKS, Scaleway Kapsule (Closed Beta), [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes) (Closed Beta) | [Hetzner](/guides/hetzner-clusters), [OVHcloud](/guides/ovh-clusters), [UpCloud](/guides/upcloud-clusters), [DigitalOcean](/guides/digitalocean-clusters), [Scaleway](/guides/scaleway-clusters) (Closed Beta), [AWS EC2](/guides/aws-clusters), [Ankra Cloud](/guides/ankra-cloud-clusters) (Closed Beta), [Proxmox VE](/guides/proxmox-clusters), [HPE Morpheus](/guides/morpheus-clusters) (Closed Beta) |
| Control plane | Operated by the provider | Provisioned and maintained in your account (bastion + control plane nodes) |
| Access model | No bastion, no SSH | SSH via a bastion; you own the nodes |
| Kubernetes distribution | Provider's | k3s or kubeadm, selectable CNI, optional external etcd |
| Cost | Provider's control-plane + node rates. Some control planes have no fee, such as the Ankra Cloud Kubernetes [development control plane](/guides/ankra-cloud-kubernetes#cost) | Your compute only (no managed control-plane fee) |
| Stop / start | Capability-gated (AKS today) | Supported |
| Control-plane editing | Not applicable | Supported |
| Best when | Your cloud offers managed Kubernetes and you want the least to operate | You run on-prem or want full control of the control plane |

Both kinds get the same Ankra surface on top: stacks, GitOps, add-ons, node groups or pools, upgrades, and AI-assisted operations.

> [!NOTE]
>
> **Surface coverage.** The **portal, API, and AI assistant** cover all eight providers. The **`ankra` CLI** covers them too (`--provider doks|uks|gke|ovh_mks|aks|eks|kapsule|ankracloud_k8s`, Ankra Cloud Kubernetes from v0.24.0): create, delete, stop and start (where the provider supports it), node-pool add, scale, update, and delete with autoscaling bounds, upgrades, and cluster **discovery and import** (`ankra cluster managed discover|import`, v0.11.0 or later). AKS control-plane options (network plugin, SKU tier, private cluster, maintenance window) are CLI flags from v0.14.0; other providers' control-plane options (HA, release channel, and so on) are set from the portal or the API.

***

## Prerequisites

One provider credential, stored in Ankra. See [Credentials](/platform/credentials) for the per-provider setup:

* **DOKS** - [DigitalOcean API token](/platform/credentials/digitalocean) with read/write
* **UKS** - [UpCloud API credential](/platform/credentials/upcloud)
* **GKE** - [GCP service account key](/platform/credentials/gcp) with the **Kubernetes Engine Admin** (`roles/container.admin`) and **Service Account User** (`roles/iam.serviceAccountUser`) roles, and the **Kubernetes Engine API** enabled
* **OVH MKS** - [OVHcloud application keys](/platform/credentials/ovh) with a Public Cloud project (`project_id`)
* **AKS** - [Azure service principal](/platform/credentials/azure) with **Contributor** on the target subscription
* **EKS** - [AWS credential](/platform/credentials/aws) with permissions for EKS, EC2, and IAM role management
* **Kapsule** - [Scaleway API key](/platform/credentials/scaleway) with the Kapsule permission sets
* **Ankra Cloud Kubernetes** - [Ankra Cloud API token](/platform/credentials/ankra-cloud)

GitOps is optional: connect a repository during creation and Ankra commits the cluster's stack definitions to Git.

***

## Live options and pricing

Every choice in the create flow is fetched **live from the provider with your credential** - regions, Kubernetes versions (with support windows), node sizes, and prices, including spot capacity and quota-aware availability where the provider exposes it. Nothing is hardcoded, so new instance families and price changes show up automatically. The create wizard renders these options for you; you can also fetch them from the API:

```bash theme={null}
curl "https://platform.ankra.app/org/clusters/managed/eks/options?credential_id=<aws-credential-id>" \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

The response lists `locations`, `versions` / `version_options` (with `supported_until` where the provider publishes it), `sizes` (vCPUs, memory, disk, GPU, monthly price), `cluster_plans`, and `capabilities` (spot, autoscaling, autopilot, private endpoint, HA control plane).

***

## Creating a managed cluster

### Via the Platform UI

**1. Navigate to Clusters**

Go to **Clusters** → **Create Cluster** and pick your provider's **Cloud Managed** action.

**2. Credential & Location**

Select the provider credential and a region. Locations load live from the provider.

**3. Node Pools**

Define one or more worker pools: name, node size (with live pricing and a monthly cost summary), count, labels, and - where supported - autoscaling bounds.

**4. Kubernetes**

Pick a Kubernetes version (or keep the provider default) and any provider-specific control plane options - HA (DOKS), control-plane plan (UKS), release channel / Autopilot (GKE), plan and update policy (OVH MKS), network plugin, private cluster and SKU tier (AKS), or subnets and control-plane logging (EKS).

**5. GitOps (optional)**

Connect a Git repository so the cluster's stacks are committed to Git.

**6. Preflight & Create**

Ankra runs provider preflight checks (credential validity, quota, name availability) before submitting. Failures block creation; warnings are shown for review. A live progress view then tracks control plane provisioning, node pools, kubeconfig retrieval, and Ankra Agent installation.

### Via the CLI

```bash theme={null}
ankra cluster managed create \
  --provider doks \
  --name my-doks-cluster \
  --credential-id <do-credential-id> \
  --location fra1 \
  --node-pool-name workers \
  --node-pool-size s-2vcpu-4gb \
  --node-pool-count 2
```

The latest stable CLI's `--provider` flag accepts **`doks`, `uks`, `gke`, `ovh_mks`, `aks`, `eks` and `kapsule`**. Optional flags include `--kubernetes-version`, the GitOps trio (`--gitops-credential-name`, `--gitops-repository`, `--gitops-branch`), and `--autoscaling` with `--autoscaling-min`/`--autoscaling-max` for the initial pool. The CLI create sends a single initial node pool. AKS takes its control-plane options as flags (`--network-plugin`, `--sku-tier`, `--private-cluster`, `--maintenance-window`); other providers' control-plane options (HA, release channel, and so on) are set from the portal or the API below. See the [CLI reference](/reference/cli/cluster) for every flag.

### Via the API

```bash theme={null}
curl -X POST https://platform.ankra.app/org/clusters/managed/aks \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-aks-cluster",
    "credential_id": "<azure-credential-id>",
    "location": "westeurope",
    "kubernetes_version": "1.32.3",
    "node_pools": [
      {
        "name": "workers",
        "size": "Standard_D2s_v5",
        "count": 2,
        "autoscaling": {"enabled": true, "min_count": 2, "max_count": 5}
      }
    ],
    "aks": {"network_plugin": "azure", "sku_tier": "Standard"}
  }'
```

Run the same payload against `POST /org/clusters/managed/{provider}/preflight` first to get the provider checks without creating anything.

### Provider-specific options

Each provider takes its own control-plane and networking options - HA (DOKS), control-plane plan (UKS), release channel and Autopilot (GKE), plan and update policy (OVH MKS), network plugin and SKU tier (AKS), or subnets and control-plane logging (EKS). The exact fields for each are documented on the per-provider pages and in the [Managed Kubernetes reference](/reference/managed-kubernetes#provider-specific-option-blocks):

[DOKS](/guides/doks-clusters) · [UKS](/guides/uks-clusters) · [GKE](/guides/gke-clusters) · [OVH MKS](/guides/ovh-mks-clusters) · [AKS](/guides/aks-clusters) · [EKS](/guides/eks-clusters)

***

## Importing existing clusters

Already running managed Kubernetes? Discover clusters at the provider and adopt them into Ankra without touching them. Discovery and import run from the **portal, the CLI or the API** for every provider:

```bash CLI theme={null}
# list clusters at the provider for a credential
ankra cluster managed discover --provider eks --credential-id <aws-credential-id>

# adopt one into Ankra
ankra cluster managed import --provider eks --credential-id <aws-credential-id> \
  --provider-cluster-id <provider-cluster-id> --name imported-prod
```

```bash cURL theme={null}
# list clusters at the provider for a credential
curl "https://platform.ankra.app/api/v1/clusters/managed/eks/discover?credential_id=<aws-credential-id>" \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"

# adopt one into Ankra
curl -X POST https://platform.ankra.app/api/v1/clusters/managed/eks/import \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "<aws-credential-id>",
    "provider_cluster_id": "<provider-cluster-id>",
    "name": "imported-prod"
  }'
```

In the portal, click **Create cluster** in **Clusters** and choose **Import existing** at the bottom of the dialog. Discovery marks clusters that are already imported, so you can't adopt the same cluster twice.

After import, Ankra fetches the kubeconfig, installs the Ankra Agent, and the cluster gains the same day-2 operations as clusters Ankra created.

## Scaleway Kapsule (Closed Beta)

> [!WARNING]
>
> **Closed beta.** Scaleway Kapsule is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request - until it is, Kapsule does not appear in the create dialog and its endpoints are not served. [Contact support](/platform/support) to have it turned on for your organisation.

Scaleway runs the Kapsule control plane; Ankra creates the cluster and its pools in your Scaleway Project, or imports one you already run. For Kubernetes that Ankra builds on Scaleway Instances instead, see [Scaleway Clusters](/guides/scaleway-clusters).

**Before you create:**

* A [Scaleway credential](/platform/credentials/scaleway) whose IAM application carries the Kapsule permission sets.
* An existing **Private Network** in the same Project and region. Kapsule clusters always attach to one, and Ankra refuses a network that belongs to an Ankra Managed cluster's own infrastructure (tagged `ankra-cluster-<id>`), because it is deleted with that cluster.
* For pools without public IPs (`public_ip: false`), a Public Gateway attached to that Private Network with masquerade on and the default route pushed. Ankra does not create it; preflight checks for it.

```bash CLI theme={null}
ankra cluster managed create \
  --provider kapsule \
  --name my-kapsule \
  --credential-id <scaleway-credential-id> \
  --location fr-par \
  --private-network-id <private-network-id> \
  --node-pool-size <instance-type> \
  --node-pool-count 2
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/managed/kapsule \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-kapsule",
    "credential_id": "<scaleway-credential-id>",
    "location": "fr-par",
    "cni": "cilium",
    "node_pools": [
      {"name": "default", "size": "<instance-type>", "count": 2, "zone": "fr-par-1",
       "root_volume_type": "sbs_5k", "public_ip": false, "autohealing": true}
    ],
    "kapsule": {"private_network_id": "<private-network-id>", "private_endpoint": false}
  }'
```

* **CNI** is one of the `available_cnis` the chosen Kubernetes version offers (`cilium`, `cilium_native` or `calico`) and cannot be changed later.
* **Pools** take `zone`, `root_volume_type` (`l_ssd`, `b_ssd`, `sbs_5k`, `sbs_15k`), `root_volume_size_gb`, `security_group_id`, `public_ip`, `autohealing` and `upgrade_policy` (`surge`, `unavailable`, `balanced`). Autoscaling needs a minimum of at least 1.
* **Private API endpoints** are refused; leave `private_endpoint` false or out.
* **Stop and start** are not offered for Kapsule.

**Import.** `ankra cluster managed discover --provider kapsule --credential-id <id>` scans `fr-par`, `nl-ams` and `pl-waw`. When a region cannot be read, the result is marked incomplete; fix access to that region before you import, because a partial scan cannot tell whether a cluster is already imported.

***

## Day-2 operations

### Node pools

```bash CLI (any provider) theme={null}
# add a pool
ankra cluster managed node-pool add <cluster_id> --provider doks --name pool-b --size s-4vcpu-8gb --count 2

# scale a pool
ankra cluster managed node-pool scale <cluster_id> workers --provider doks --count 5

# delete a pool
ankra cluster managed node-pool delete <cluster_id> pool-b --provider doks
```

```bash cURL (any provider) theme={null}
# update count and/or autoscaling bounds
curl -X PATCH https://platform.ankra.app/org/clusters/managed/doks/<cluster_id>/node-pools/workers \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"autoscaling_enabled": true, "autoscaling_min": 2, "autoscaling_max": 10}'
```

The CLI scales node pools to a fixed count on any provider, and `ankra cluster managed node-pool add|update` take `--autoscaling` with `--autoscaling-min`/`--autoscaling-max`. Autoscaling bounds are available on every provider except UKS, where Ankra does not manage autoscaling; see [externally managed node pools](#externally-managed-node-pools). AKS pool names are lowercase alphanumeric and at most 12 characters.

### Externally managed node pools

Ankra never changes a managed pool's node count on its own. There is no drift correction on node counts and no scheduled job that writes them, and a Kubernetes upgrade only sets the version. The count changes only when someone scales the pool, sends a `PATCH` with a `count`, or replaces the pool with a different size (which recreates it at the count Ankra has stored).

When something outside Ankra owns a pool's count, such as a cluster autoscaler you run yourself on a provider where Ankra does not manage autoscaling, mark the pool as externally managed so those explicit writes are refused too:

```bash theme={null}
curl -X PATCH https://platform.ankra.app/org/clusters/managed/uks/<cluster_id>/node-pools/autoscaled \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externally_managed": true}'
```

`externally_managed` is sent on its own, not combined with other pool fields, and setting it makes no call to the provider. While it is set:

* Scale, a `count` update, delete and size replacement on that pool are refused with `Node pool is externally managed; clear externally_managed before changing it through Ankra`. This covers the portal, the CLI, the API and Ankra AI, which has no way to clear the flag itself.
* The pool listing returns `externally_managed: true` and an `observed_count` read live from the provider. `count` stays the last value Ankra wrote, and Ankra never copies the observed count over it.

Send `{"externally_managed": false}` to hand the pool back. A pool created directly at the provider after the cluster was imported is not in Ankra's definition at all, so Ankra cannot change it either way.

### Kubernetes upgrades

Ankra lists the upgrade targets the provider actually offers for your cluster's current version. In the portal, **Settings** → **General** → **Kubernetes Version** shows available upgrades with their support windows. You can also upgrade any provider from the CLI:

```bash theme={null}
ankra cluster managed upgrade <cluster_id> --provider doks --version 1.33.0
```

The provider upgrades the control plane first, then rolls node pools. Downgrades are not supported.

### Stopping and starting

Stop/start is capability-gated per provider and is available for **AKS only** today. In the portal, use **Settings** → **General** → **Danger Zone**, or use the CLI:

```bash theme={null}
ankra cluster managed stop <cluster_id> --provider aks
ankra cluster managed start <cluster_id> --provider aks
```

Stopping an AKS cluster deallocates its compute while preserving its configuration. Starting brings the same managed cluster back. The portal, CLI, API, and AI/MCP surfaces only offer these actions when the provider reports `supports_stop_start`.

### Deleting

```bash theme={null}
ankra cluster managed delete <cluster_id> --provider doks
```

> [!WARNING]
>
> Deleting a managed cluster destroys it at the provider - control plane, node pools, and workloads. Clean up provider-created LoadBalancers and volumes first if the CCM/CSI created any outside the cluster's own resource group or VPC.

### What does not apply to managed clusters

Because the provider owns the control plane, some lifecycle operations that exist for [Ankra Managed clusters](/guides/operate-ankra-managed-clusters) are **not applicable** here:

* **Stop / start** - capability-gated and currently available only for AKS, as described above.
* **Control-plane topology editing** (controller count, control-plane instance type) - the provider sizes and manages the control plane. HA control planes, where offered, are selected at creation.
* **Instance-type upgrade in place** - change node sizing by editing or replacing a node pool, not by resizing individual nodes.

***

## Ankra AI

Ankra's AI can operate Cloud Managed Kubernetes on every provider - DOKS, UKS, GKE, OVHcloud MKS, AKS, EKS, Scaleway Kapsule and Ankra Cloud Kubernetes (the closed-beta providers only where they are enabled). Ask it to:

* *"What does a 3-node e2-standard-4 GKE cluster in europe-west1 cost?"* - it fetches live options and pricing with your credential
* *"Create an AKS cluster in West Europe with autoscaling 2 to 5 nodes"* - it proposes the create for your confirmation
* *"What EKS clusters exist in our AWS account?"* - it discovers clusters at the provider and shows which are already imported
* *"Import the staging GKE cluster"* - it adopts a discovered cluster after you confirm
* *"Stop the development AKS cluster"* - it proposes the capability-gated stop operation for your confirmation

Creates, imports, and lifecycle writes always require an explicit confirmation in chat before anything is submitted.

***

## Troubleshooting

| Issue | Solution |
| - | - |
| Options list is empty or fails | The credential is invalid or lacks API permissions - re-run **Test connection** on the credential |
| Preflight reports a quota error | Raise the provider quota (vCPUs, clusters per region) or pick another region/size |
| AKS create rejected with a name error | Pool names must be lowercase alphanumeric, max 12 characters; cluster names max 63 |
| GKE create rejected with a name error | Cluster names are lowercase letters, numbers, hyphens; must start with a letter |
| EKS cluster stuck creating | EKS control planes routinely take 10 to 15 minutes; node groups follow after |
| Cluster shows offline after create | The agent installs as the last step - check the operation timeline on the cluster page |
| Import says "already imported" | The cluster is connected to this or another Ankra organisation; find it in **Clusters** |


# Move a Docker Deployment Into a Cluster
Source: https://docs.ankra.ai/guides/migrate-from-docker

Use ankra migrate to convert a Docker Compose deployment into a stack, deploy it to a cluster, and restore its PostgreSQL, MySQL and MariaDB data in one command.

> [!NOTE]
>
> `ankra migrate up` takes a directory holding a Docker Compose file and moves the whole deployment into a cluster Ankra runs: it converts the services into a stack, applies the stack, and then moves the data out of the deployment's PostgreSQL, MySQL and MariaDB databases into the databases it just deployed. A bare `Dockerfile` and the running Docker daemon work as sources too.

The command is re-runnable, so the usual shape is to rehearse it against a live source, check the result, and then run it once more with `--stop-source` to cut over, adding `--overwrite-database` for each database an earlier run restored.

## Prerequisites

* **A logged-in session**: `ankra login`, or `ANKRA_API_TOKEN` in the environment.
* **A target cluster** in the organisation running an [Ankra agent](/concepts/cluster-agent) new enough to run data restores. An older agent makes the platform refuse the restore with `409`: `The cluster's agent does not support data restores yet; upgrade the agent first.`
* **A [backup vault](/guides/backups)** in the `ready` state. The dumps travel through the vault's bucket. `ankra backup vaults list` shows what you have, `ankra backup vaults provision` creates one. With exactly one ready vault the CLI picks it; with several, name one with `--vault`.
* **Docker reachable** from wherever the command runs. Locally that is the daemon on your machine; for a deployment on another host, point at it with `--option docker-host=ssh://root@host`.

## Plan first

`--plan` prints what the run would do and changes nothing:

```bash theme={null}
ankra migrate up ./app --cluster production --plan
```

The plan names:

* The **module** detected in the source directory, the **target cluster**, the **stack** (new, or an existing one that will be updated) and the **namespace**. The stack defaults to the source directory's name and the namespace to the stack's name. `ankra migrate detect ./app` reports which modules recognise a directory, and `ankra migrate modules` lists the ones available.
* The **output directory** (`--out`, default `ankra-migration`): the conversion is written to `<out>/stack` and the dumps to `<out>/data`. A directory holding nothing but an earlier run's `stack/` and `data/` is reused, so running the same command again needs no `--force`.
* Every **database server** it found, with its engine, version and user, and each database on it with the size read from the running container (`pg_database_size` on PostgreSQL, `information_schema` on MySQL and MariaDB).
* The **estimated dump size** against the free disk where the dumps will be written. The run refuses rather than filling the disk.
* **Warnings**, such as a database above 625 GiB (more than a single upload can carry), or the `postgres` maintenance database being skipped. If `postgres` really is your application database, say so with `--option databases.<workload>=postgres`.
* A **not carried** list: files in the volumes of non-database workloads, and data in engines the export does not dump.

Without `--plan` the same summary is printed and the run waits for a confirmation. `--yes` skips the prompt.

## Run it

```bash theme={null}
ankra migrate up ./app --cluster production
```

**1. Convert**

The source is converted into a stack, exactly as `ankra migrate convert` would, and written to `<out>/stack`.

**2. Deploy**

The stack is applied to the cluster under its name, the same write `ankra cluster apply` performs, and the command waits for the platform to accept it.

**3. Wait for the databases**

Each database workload has to have a running, ready pod before anything is restored into it.

**4. Export**

The dumps are taken from the source, as `ankra migrate export` would, into `<out>/data`.

**5. Restore**

The dumps are uploaded through the vault, verified, restored in-cluster, and the command waits for the restore to finish.

Watch that one command run against a live Compose deployment, from conversion to restored data.

[docker-compose to Kubernetes in one command - Ankra migrate](https://www.youtube-nocookie.com/embed/9sQrvAeJ4tg?rel=0)

The summary at the end says where the deployment now runs, the **import id** for the restore, the URLs for any workload given one with `--option ingress.<workload>=<host>`, what is still running on the source, and whether the run was a rehearsal.

To publish a workload and get TLS for it, pass the host and the issuer:

```bash theme={null}
ankra migrate up ./app --cluster production \
  --option ingress.web=app.example.com \
  --option cluster-issuer=letsencrypt-prod
```

### Flags

| Flag | Description |
| - | - |
| `--cluster` | Cluster to migrate into, by name or id; defaults to the selected cluster |
| `--vault` | Backup vault the data goes through; defaults to the organisation's only ready vault |
| `--module` | Conversion module to use; defaults to the most confident detection |
| `--stack` | Name of the stack on the cluster; defaults to the directory name |
| `--namespace` | Namespace the workloads run in; defaults to the stack name |
| `--out` | Output directory (default `ankra-migration`), holding `stack/` and `data/` |
| `--option k=v` | Repeatable; convert options and export options both apply here |
| `--force` | Overwrite an output directory that holds files no earlier run of this command wrote |
| `--no-data` | Deploy the workloads only; carry no data over |
| `--stop-source` | Stop the source's non-database services before the export, so the dump is final |
| `--overwrite-database` | Repeatable; a database the restore may replace although an earlier restore into this cluster already loaded it, as `<server>/<database>`, or the database name when only one server has it |
| `-y, --yes` | Skip the confirmation prompt |
| `--plan` | Print the plan and stop; change nothing |
| `--timeout` | How long to wait for the run to finish (default `10m`) |
| `-o json\|yaml` | Machine-readable output |

## Rehearse, then cut over

Nothing about the run requires the source to be stopped, so rehearse with it live, look at what landed in the cluster, and repeat until you are happy. A restore replaces everything in a database with the export, so once any earlier run has started a restore into a database in the cluster, whether or not it finished, Ankra refuses to restore into it again unless you name it with `--overwrite-database <server>/<database>`, or the database name alone when only one server has it. Repeat the flag for each database. The check runs before anything is uploaded, and the refusal names every database to add. `ankra migrate restore` and `ankra migrate data` take the same flag. When you are happy, cut over:

```bash theme={null}
# first rehearsal, with the source still serving
ankra migrate up ./app --cluster production

# every later rehearsal replaces what the earlier one restored
ankra migrate up ./app --cluster production --overwrite-database db/shop

# cut over
ankra migrate up ./app --cluster production --stop-source --overwrite-database db/shop --yes
```

> [!NOTE]
>
> Running again over the same output directory needs no `--force`: a directory holding nothing but an earlier run's `stack/` and `data/` is reused. `--force` is only for an output directory that holds something else, and the refusal names the file that is in the way: `<out> holds notes.txt, which no earlier run of this command wrote; pass --force to overwrite it or --out for another directory`.

`--stop-source` stops the source's non-database services before the final dump is taken, so nothing writes to the source databases while they are being read. The databases themselves stay up for the dump. The summary prints the `docker start ...` command that brings the source back if you need to roll back. A run that stops before the restore, such as one missing an `--overwrite-database`, leaves those services stopped; the progress output printed the same command when it stopped them. Once you are satisfied, move DNS to the cluster.

## Running the steps separately

The same work is available as individual commands when you want to inspect what each one produced:

```bash theme={null}
# 1. Convert the compose project into a stack
ankra migrate convert ./app --out ./app-k8s

# 2. Apply it (edit ./app-k8s/cluster.yaml first if you want to)
ankra cluster apply -f ./app-k8s/cluster.yaml

# 3. Dump the databases out of the source
ankra migrate export ./app --out ./app-data

# 4. Upload and restore into the cluster
ankra migrate restore ./app-data --cluster production --wait
```

`ankra migrate data ./app --cluster production --wait` runs steps 3 and 4 together. A restore that was started without `--wait` can be followed with `ankra migrate restore-status <import-id> --wait`.

### Options

`--option` is repeatable, and `ankra migrate up` accepts both sets. The conversion takes:

| Option | Meaning |
| - | - |
| `source=compose\|dockerfile\|daemon` | Which source to read; detected by default |
| `profiles=app,dns` / `all-profiles=true` | Which Compose profiles to include |
| `use-environment=true` | Let your shell satisfy `${VAR}` references |
| `project=<name>` / `containers=a,b` | The Compose project, or specific containers, when reading the daemon |
| `image.<workload>=<ref>` | The image to run for a workload the Compose file builds locally |
| `ingress.<workload>=<host>` | Expose a workload through an Ingress |
| `cluster-issuer=<name>` | Request TLS for every generated Ingress |
| `volume-size=20Gi` / `storage-class=<name>` | Size and storage class for every PersistentVolumeClaim |

The export takes:

| Option | Meaning |
| - | - |
| `docker-host=<host>` | Reach a daemon somewhere else, for example `ssh://root@host` |
| `databases.<workload>=a,b` | Dump exactly these databases from that workload |
| `container.<workload>=<name>` | Dump from a specific container |

## How the data travels

The dump runs **inside each database container**, through the container's own shell. The password is read from the container's environment, `*_FILE` secrets are honoured, and no credential is ever put on the host's command line.

* **PostgreSQL**: `pg_dump -Fc` per database, plus `pg_dumpall --globals-only --no-role-passwords` for the roles.
* **MySQL and MariaDB**: `mysqldump --single-transaction --routines --triggers --events --databases`, as root where a root password exists and otherwise as the application user.

The workloads recognised as databases are the images whose names start with `postgres`, `postgis`, `pgvector` or `timescaledb`, and `mysql`, `mariadb` or `percona`. Sidecars are left alone: an image whose name contains `exporter`, `proxy`, `bouncer`, `backup`, `operator`, `client` or `admin` is never dumped from.

Dumps are written `0600` alongside a `manifest.json` and a `SHA256SUMS`.

On the way in, the CLI uploads straight to the vault's own bucket using presigned URLs the platform mints under `imports/<import-id>/`. A dump above 1 GiB goes up in parts of 64 MiB, each retried on its own, so one stalled part costs a part rather than the whole upload. The platform starts the multipart upload and the CLI completes it, aborting it if it cannot finish, so the vault is never left holding half an artifact. The progress line names the size and the part count:

```
Uploading db/shop.dump (3.0 GiB, 49 parts)
```

The platform verifies each object's size with a `HEAD`, and then the cluster's agent runs a Kubernetes Job in the target namespace: an init container downloads the artifacts and checks them against their SHA-256 sums, and the engine client (`postgres:<major>-alpine`, or `mysql`/`mariadb:<version>`) waits for the database to accept connections and restores into it. Roles and globals go first, then each database, with `pg_restore --clean --if-exists --no-owner` or `mysql < file`. The Job connects using the Service and Secret the conversion generated.

> [!NOTE]
>
> Ankra never holds your data: it goes from your source to your vault's bucket to your cluster. No vault credential is handed to the cluster, and nothing on the machine running the command needs `kubectl` or a database client.

## The dumps a restore leaves in the vault

Every restore keeps its upload under `imports/<import-id>/` in the vault, so the same import can be restored again without dumping the source a second time. That restore replaces what the earlier one loaded, so it is refused until the restore request names each database in `confirmed_overwrite_databases`, the API's form of `--overwrite-database`. The dumps stay there until you remove them.

```bash theme={null}
ankra migrate imports list                  # what the vault holds
ankra migrate imports list --vault offsite  # a particular vault
ankra migrate imports delete <import-id>    # remove the dumps and forget the import
```

`list` gives each import's id, stack, status, databases, size and when it was created. `delete` removes the dumps from the vault and forgets the import, and refuses one whose restore is still running; `--yes` skips its confirmation. A restore that completes prints the `delete` command for the import it just finished, so the cleanup is there when you want it.

Deleting the vault itself also removes the dumps of every import it held, on a bucket you own.

## What is not carried

> [!WARNING]
>
> The migration moves workloads and relational database contents. It does not move everything.

* **Files in the volumes of non-database workloads.** Uploads, caches and other on-disk state have to be copied into the PVC yourself.
* **Data in engines the export does not dump**: Redis, Valkey, MongoDB, Elasticsearch and OpenSearch, RabbitMQ, MinIO, ClickHouse, InfluxDB, Neo4j, Cassandra and CouchDB. Their workloads are converted and deployed; they simply come up empty. The plan names each one it found.
* **A single artifact above 625 GiB**, which is the 10,000 parts of 64 MiB one upload can carry. `ankra migrate restore` refuses a larger one before it registers the import, saying `an upload carries at most 625.0 GiB`.
* **PostgreSQL role passwords.** Roles are restored without them. The application user keeps the password from the cluster Secret, so the application works; any other login role needs an `ALTER ROLE ... PASSWORD` afterwards.

A `pg_restore` that finishes with "errors ignored" (exit code 1) is reported as a warning and the restore is treated as successful, which is the normal outcome when the target database already holds some of the objects.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Exit `2`: `the organisation has no ready backup vault` | Nothing to stage the dumps through | `ankra backup vaults provision`, then run again |
| Exit `2`: `the organisation has N ready backup vaults` | The CLI will not guess between them | Name one with `--vault` |
| Exit `2`: `<out> holds notes.txt, which no earlier run of this command wrote` | The output directory holds a file the migration did not put there | Pass `--force` to overwrite it, or `--out` for another directory |
| `The cluster's agent does not support data restores yet; upgrade the agent first.` | The cluster's agent predates the restore lane | Upgrade the [cluster agent](/concepts/cluster-agent) |
| Restore pod in `CreateContainerConfigError` naming the Secret | The stack was never applied in that namespace | Check the stack deployed, and that `--namespace` matches where it landed |
| `no pod has been created for the restore job`, or `pod ... cannot be scheduled` | After five minutes the namespace still has no room for the restore Job | Free quota or capacity. The Job asks for ephemeral storage of the dump size times 1.1, plus 64 MiB |
| `an upload carries at most 625.0 GiB` | One dump is bigger than a single upload can carry | Dump that database on its own, or split it across smaller databases |

A failed restore keeps its Job in the namespace for an hour. The agent already tails the Job's log into the failed step, so the reason usually travels with the operation, and the CLI reports `the restore of import <import-id> failed: ...`. To read the Job yourself while it is still there, through Ankra (with the
cluster selected via `ankra cluster select <cluster>`):

```bash theme={null}
ankra cluster get k8s-jobs -n <namespace>      # the restore Job is named ankra-restore-<suffix>
ankra cluster logs -n <namespace> -l ankra.io/restore-import=<job-name> --all-containers --follow=false
```

## Writing your own module

The conversion and the export are done by a **module**, and `docker` is the only one built in. Another source format - a Procfile, a Nomad job, an in-house deployment description - is an executable named `ankra-module-<name>` on your `PATH` or in `~/.ankra/modules` that answers `describe`, `detect` and `convert` with JSON on stdin and stdout, and `export` too if it can dump its own databases. `ankra migrate modules` lists the ones you have. See [Write an ankra migrate module](/guides/migrate-modules).

## Next steps

> [card] [Write a module](/guides/migrate-modules)
>
> Teach `ankra migrate` another source format.

> [card] [Backup vaults](/guides/backups)
>
> Provision the vault the dumps travel through.

> [card] [Stacks](/concepts/stacks)
>
> Understand the stack the conversion produced.

> [card] [Ankra CLI](/integrations/ankra-cli)
>
> Install the CLI and browse the rest of its commands.

> [card] [Import a cluster](/guides/import-cluster)
>
> Connect the cluster you are migrating into.


# Migrate from GitHub Actions
Source: https://docs.ankra.ai/guides/migrate-from-github-actions

Convert a GitHub Actions workflow, a GitLab CI file, a Bitbucket pipeline or a CircleCI config into .ankra/pipeline.yaml, read every note the converter leaves, and run both side by side until you trust it.

Ankra converts an existing CI definition into an [Ankra pipeline](/guides/ankra-pipelines) - the `.ankra/pipeline.yaml` its own engine runs inside your cluster. One converter reads four formats: GitHub Actions workflows, a `.gitlab-ci.yml`, a `bitbucket-pipelines.yml` and a `.circleci/config.yml`.

> [!NOTE]
>
> A converted pipeline is a starting point a person reviews, never a drop-in replacement. The rule the converter holds to: something it cannot map is either carried across as a stage that **fails with an explanation**, or reported as a note with the job or step it came from - never dropped silently. A converted pipeline that quietly skipped a toolchain step would go green having built nothing.

## Migrate an existing application with one call

For an application already connected to Ankra, this is the fast path, and it takes effect the moment you ask. An application that still builds from a GitHub Actions workflow - the one Ankra generated at setup, or one your repository wrote itself - shows **Convert to Ankra Pipelines** on its journey card and **Convert** on its row in the Applications list. The same conversion is one command or one call:

```bash theme={null}
ankra application pipeline convert <application-id>
ankra application pipeline convert <application-id> --keep-workflows

curl -X POST https://platform.ankra.app/api/v1/org/applications/<application-id>/pipeline-migration \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

One click does all of this:

* Reads what builds the application today and converts it into `.ankra/pipeline.yaml` through the same converter [Ankra AI uses](#convert-with-ankra-ai), then stores that as the application's pipeline definition of record.
* Records the application as building on Ankra Pipelines (`pipeline_source` becomes `ankra_pipeline`) right away, so the next push to the tracked branch builds through the pipeline. Nothing waits on a merge.
* Switches Ankra's generated workflow off on GitHub, so the workflow and the pipeline never build the same commit twice. If the GitHub App lacks the Actions permission the answer says so, and the workflow stops building when the pull request that removes it merges.
* Opens a pull request on the fixed branch `ankra/pipeline-migration` that commits the pipeline file and removes the generated workflow file. `--keep-workflows` (`{"remove_workflows": false}`) leaves the file in the repository, still switched off. A workflow your repository wrote itself is never touched either way.

The pull request is the repository catching up with what Ankra already runs: merge it when you are happy with the file. Converting again while it is still open answers the same conversion (`already_open`) and re-checks that the workflow is switched off; if you closed the pull request without merging, converting again proposes it afresh. An application with no detected CI, one already on Ankra Pipelines, or an organisation with no CI cluster to run the result on is refused with the reason rather than opening a pull request with nowhere to go. A service token may convert an application exactly as it may dispatch a run. The conversion needs the repository's stored GitHub credential today.

`GET .../pipeline-migration` reads what builds the application today and what a conversion would act on, without changing anything.

## Convert with Ankra AI

Ask Ankra AI in the portal chat, or call the tool through the [MCP server](/platform/mcp-server). Example prompts:

* "Convert `.github/workflows/ci.yml` and `.github/workflows/build-deploy.yml` into an Ankra pipeline and show me every note."
* "Convert this `.gitlab-ci.yml` into `.ankra/pipeline.yaml` for the `orders-api` application."

The tool behind it is `cicd_convert_workflow_to_pipeline`:

| Parameter | Meaning |
| - | - |
| `workflow_files` | The files to convert, each with its repository `path` and its `content`, at most 20 files and 256 KB per call. For GitHub Actions pass every workflow that takes part in the build - they become **one** pipeline, because a repository's workflows share one checkout and one run. For GitLab, Bitbucket and CircleCI pass exactly one file. |
| `format` | Optional: `github_actions`, `gitlab_ci`, `bitbucket_pipelines` or `circleci`. Omitted, it is inferred from the paths - a file named `.gitlab-ci*` selects `gitlab_ci`, `bitbucket-pipelines*` selects `bitbucket_pipelines`, a path under `.circleci/` selects `circleci`, anything else `github_actions`. |
| `application_id` | Optional: when it resolves, the pipeline's `metadata.name` is the application's name; otherwise one is derived from the workflow and the notes say so. |

It answers with the rendered `pipeline_yaml`, the `notes` naming every construct it could not carry across faithfully, and a validation verdict. It writes nothing to the repository: open the pull request yourself, or ask the AI to open one. Its twin, `cicd_validate_pipeline_yaml`, validates a definition you wrote or edited and lists every violation with its key and severity - see [Validation](/guides/pipeline-reference#validation).

## What maps to what

Jobs become stages, `needs` becomes `needs`, conditions keep their `${{ }}` delimiters, and the `steps`, `matrix`, `inputs`, `env` and `needs` references map one to one. A reference to the `github` context does not: the validator reports it with the Ankra equivalent (`github.sha` is `ankra.sha`, `github.event_name` is `event.kind`, and so on) for you to rewrite. See [Expressions](/guides/pipeline-reference#expressions) for the two deliberate departures.

Third-party steps go through one mapping table, so a GitHub action, a Bitbucket pipe and a CircleCI orb command that do the same work become the same stage. A row matches every version of its identifier (`actions/checkout@v4`, `atlassian/slack-notify:2.1.0`).

### Steps that become a stage

| Source | Becomes |
| - | - |
| `actions/checkout` | A `checkout` stage; `ref`, `fetch-depth`, `submodules` and `lfs` are carried as inputs |
| `docker/build-push-action`, `depot/build-push-action`, `circleci/docker/build` | A `build` stage: `file`/`dockerfile`, `context`, `platforms`, `build-args`, `provenance`, `sbom`, `cache-to`. `push: true` is understood and needs nothing - `build` always pushes its digest to the organisation's own CI staging repository, and `publish` is what tags it into your real one, once a `gate` step approves it. Build argument **names** are kept and their values dropped, because a value in a workflow is routinely a secret expression that must not be committed. The `tags` input is reported and left behind: an Ankra build produces a digest, and `publish` is what tags it, always as `sha-<7>` - a workflow's own tag scheme (`latest`, semver, a branch name) is not carried across. |
| `aquasecurity/trivy-action`, `aquasecurity/trivy-pipe` | A `scan` stage running Trivy alone (`scanners: ["trivy"]`) that blocks per the organisation's image gate; a `severity` input is reported, because the scan blocks per the gate and reports every finding either way. `scan` also runs Semgrep and Checkov when you add them to `scanners:` by hand - the converter does not add them for you, because nothing in a Trivy-only action says a repository wants either. |
| `slackapi/slack-github-action`, `8398a7/action-slack`, `atlassian/slack-notify`, `atlassian/microsoft-teams-notify`, `circleci/slack/notify` | A `run` stage carrying a **placeholder that fails until you finish it**: every input the source step declared, carried across as comments so nothing is lost, a commented `curl` to fill in, and `exit 1` at the end. A CircleCI `event` of `pass`, `fail` or `always` still becomes the stage's `if:` (`success()`, `failure()`, `always()`). Failing is deliberate - a script of nothing but comments would conclude the step green, and a green `notify-slack` step that delivered no notification is indistinguishable from one that did |
| A script that only packages and pushes a Helm chart (`helm package`, `helm push`, `helm lint`, `helm dependency`, `helm registry`) | A `run` stage on `alpine/helm:3.16.3` running the same `helm package` and `helm push` the script did - the image is named rather than inherited, because a pipeline's `defaults.image` is its build toolchain and ships no `helm`. The `helm registry login` the script performed is dropped, and the login is declared instead: add `secrets: [{name: registry_login, from: registry}]`, list it on the stage, and pass `--registry-config /run/agent-secrets/registry_login` to `helm push` - see [A registry login in a step](/guides/pipeline-reference#a-registry-login-in-a-step). The workflow's `ANKRA_REGISTRY_USERNAME` and `ANKRA_REGISTRY_PASSWORD` do not travel: they are GitHub Actions repository secrets, and a pipeline step reads none. A script that does anything else stays a script. |
| `circleci/node/install-packages`, `circleci/python/install-packages` | The shell command the selector stands for: `npm ci`, `yarn install --frozen-lockfile`, `yarn install --immutable`, `pnpm install --frozen-lockfile`; `pip install -r requirements.txt`, `pipenv install`, `poetry install`. An unknown package manager becomes a failing stage. |

No converter emits a `uses:` reference any more. Until the built-in step library ships, any `uses:` is refused outright at validation - "Reusable steps are not available yet; write the step as `run:`" - so a converted file carrying one could not be planned at all. Each construct that used to map onto an `ankra/*` step is therefore emitted as the `run:` stage above, with a note naming the library step it stands in for.

### Steps that become the stage image

`actions/setup-node`, `actions/setup-go`, `actions/setup-python`, `actions/setup-java`, `circleci/node/install` and `circleci/go/install` do not become stages. Each becomes the image the job's later stages run in - `node:<version>`, `golang:<version>`, `python:<version>`, `eclipse-temurin:<version>` - because a stage that runs in that image has the toolchain the step installed. `20.x` and `20` both become `node:20`; a matrix expression such as `${{ matrix.node }}` is carried into the image. `lts/*`, `latest`, a range or a version file names a resolution rule rather than a version, so no image is derived and the note tells you to pin one on the job's stages. A setup step with no version at all leaves the job's stages on the runner image below, which ships no language toolchain, so pin the toolchain image on those stages yourself.

### Jobs with no container

A `run` stage that names no image, with no `defaults.image` to inherit, cannot run: `ankra pipeline validate`, the commit gate and the planner refuse the whole definition under `pipeline_image:`, naming the stage. So the converter never leaves one. A GitHub-hosted job with no `container:` runs its stages in an image chosen from its `runs-on`:

| `runs-on` | Image |
| - | - |
| `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-24.04-arm` | `buildpack-deps:noble@sha256:27bdb6ab1ca0df6acfe341752ee4d9c08a341d80e3ee75ccc3b34b79af0dfaf1` (Ubuntu 24.04) |
| `ubuntu-22.04`, `ubuntu-22.04-arm` | `buildpack-deps:jammy@sha256:b28e7724fdddd120588c097871f740efb9ca340cfc4dbc1ef9be5f0065474198` (Ubuntu 22.04) |
| Anything else (an older, Windows or macOS runner, a self-hosted or larger-runner label, an expression) | the Ubuntu 24.04 image above, with a note that the runner was not recognised |

The converter writes the tag together with its digest, so a registry-side retag never changes what the converted file runs. The first such job's image becomes the converted file's `defaults.image`, so every stage that names none inherits it; a job on a different runner names its own image on its stages. The same image is the default for a GitLab job or a Bitbucket step that names no `image:` (GitLab and Bitbucket ran those in a runner default this file cannot see), a CircleCI `machine` or `macos` executor, and the stages the converter emits for a step it could not carry across, which then fail with their own explanation rather than for want of an image. Each placement is a note naming the stages and the image.

`buildpack-deps` is Docker's official Ubuntu image with `git`, `curl`, `wget`, `ssh`, `make`, `gcc` and the common development headers. It is a starting point, not a copy of GitHub's runner, which also ships language toolchains, `docker`, `jq` and cloud CLIs. A step that relied on one of those fails until a setup step (above) or the stage's own `image:` provides it. Installing it at run time is not the way out: a stage runs as a non-root user on a read-only root filesystem. Change `defaults.image`, or set `image:` on a stage, to run it in the image your job needs.

### Steps that are dropped, with a note

| Source | Why |
| - | - |
| `docker/login-action`, `docker/setup-buildx-action`, `docker/setup-qemu-action`, `depot/setup-action`, `circleci/docker/check` | An Ankra run authenticates to the registry with its own credential and the build stage brings its own builder |
| `aws-actions/configure-aws-credentials`, `google-github-actions/auth`, `azure/login`, `circleci/aws-cli/setup` | A cloud credential is materialised through the pipeline's `credentials` block, not configured by a step |
| `azure/setup-helm`, `circleci/helm/install_helm_client` | An Ankra run authenticates to the registry with its own credential, and a chart-push script becomes a `run` stage on the `alpine/helm:3.16.3` image, which already ships helm |

### Everything else

A third-party step the table does not know becomes a `run` stage that stops the run and says what has to be replaced:

```bash theme={null}
echo "This step used <reference>, which the converter could not map to an Ankra stage."
echo "Replace it with an image that already provides what the action did, a script, or an ankra/* step."
exit 1
```

Failing is the point: a dropped step would produce a pipeline that runs green having skipped whatever the step did, and you would have no way to tell a converted step from a discarded one.

## What each source loses

Every item below arrives as a note with the file, job or step it came from. Read the notes before the YAML.

**GitHub Actions**

* The `permissions` block is not converted: a run's authority is the intersection of the pipeline's own `permissions`, the organisation's CI policy and the target environment, not the workflow token's scopes.
* A trigger with no Ankra equivalent is not converted, and a trigger that narrows on something an Ankra trigger cannot (for example pull request `types`) loses the narrowing: the pipeline runs on **more** of those events than the workflow did.
* `defaults.run.shell` is not converted; a stage runs its script with the shell its image provides.
* Several workflows fold into one pipeline whose `on:` is their union - a path filter that one workflow declares and another does not leaves the union unfiltered, so every run the workflows started still starts. Each workflow's own `push` and `pull_request` branches and paths stay on its stages as [event-scoped `when` blocks](/guides/pipeline-reference#event-scoped-filters) wherever they are narrower than the union, and a workflow that does not listen to an event the pipeline does keeps its stages out of it with `when.events`. A note names the workflows this applied to.
* A second `concurrency` block is not converted: a pipeline carries one concurrency group, and the first workflow claimed it.
* A job that calls a reusable workflow (`uses: ./.github/workflows/…`) cannot be followed; its stage fails until it is replaced.
* A workflow that is not valid YAML contributes nothing, and the note says which.

**GitLab CI**

* `workflow:rules` is not converted, so runs it filtered out are not filtered here.
* A top-level `services:` block, which gives every job a sidecar, is not converted: declare the services the stages need in the pipeline's `services` block and list them on each stage, or the jobs that relied on them fail at runtime.
* A job that triggers a downstream pipeline has no equivalent.
* `except:` is not converted: an Ankra stage filters on the branches, paths and events it runs *for*, never on the ones it skips. A `rules:` block carrying `when: never` on a `changes:` list is not converted, and its paths go with it: that rule skips the paths it names, and an Ankra `when.paths` says which paths the stage runs *for*, so carrying them across would invert the meaning. Otherwise its `changes:` paths are carried, onto the stage's flat `when.paths` unless the rule names an event. A rule whose `if:` tests `$CI_PIPELINE_SOURCE == "merge_request_event"` becomes [`when.pull_request.paths`](/guides/pipeline-reference#event-scoped-filters), one testing `== "push"` becomes `when.push.paths` (a matching rule with no `changes:` leaves that event unfiltered), and the rest go to `when.paths`. Any other `if:` condition, and the rules' order, are not carried, and the note says so.

**Bitbucket Pipelines**

* A step `size` of `1x`, `2x`, `4x` or `8x` becomes a memory request; any other value is reported and you declare `resources.memory` yourself.
* `bookmarks:` pipelines belong to Mercurial and are not converted.
* A parallel group's fail-fast is not converted: an Ankra run lets the other stages of a group finish when one fails.
* A pipeline that imports from another repository cannot be followed and contributes nothing.
* `runs-on` labels are not converted: an Ankra stage is placed by the organisation's CI cluster and the stage's own `runs_on` block.
* A manual trigger becomes an `approval` stage approvable by the `admin` and `operator` roles, because anyone with write access could press the Bitbucket button and no Ankra role maps onto that; narrow the roles to whoever actually held the button.
* A `pull-requests:` pattern is not carried as a filter. Bitbucket matches it against the pull request's **source** branch, while an Ankra `pull_request` trigger and a stage's `when.branches` match the **target**, and nothing in a pipeline filters on the source branch. Each section therefore runs for every pull request (`on.pull_request.branches: ['**']`), and the note suggests a push trigger on the pattern if that is the filter you need. A `'**'` section gets no note.
* A step that a branch section shares with a pull request, tag or custom section loses its branch filter, because a stage carries one branch list for all its events; the note names the filter that was dropped.
* `clone: lfs: true` and `clone: enabled: false` are not converted: the checkout stage does not fetch Git LFS objects, and every stage shares the workspace it fills. A step's own `clone:` settings are not converted either, because a run checks the repository out once.

Two Bitbucket settings carry across without a note: `clone: depth` becomes the checkout stage's `with.fetch_depth` (`full` becomes `"0"`, the whole history), and a step's `condition.changesets` becomes its `when.paths` - the `includePaths` entries followed by each `excludePaths` entry negated with `!`. The planner lets the last matching entry decide, so a changed file counts exactly when Bitbucket would count it. As in Bitbucket, a step whose changesets match nothing is skipped on its own: the converted step after it lists it under `skippable_needs`, so it still runs, and waits on the filtered step only when that step runs. A manual step's approval carries the same path filter, so a push that skips the step leaves no approval waiting.

**CircleCI**

* A version 2.0 configuration converts the way a 2.1 one does; any orb, command or parameter it cannot declare is simply absent. A setup configuration's continuation pipeline cannot be followed; only the jobs declared in the file are converted.
* An inline orb is not converted; every step that calls it becomes a stage that fails until it is replaced. An orb job the converter cannot follow is reported the same way.
* A parameter whose name carries a dash is renamed (an input name may not carry one), and every reference to it is renamed the same way.
* An approval job becomes an `approval` stage approvable by the `admin` and `operator` roles, with the same advice to narrow them.
* Anchors and aliases are resolved before conversion, so an anchored executor or step list behaves like an inline one.

## What to review after conversion

1. **The notes, first.** Each is a decision the converter took on your behalf or could not take. Stages that fail by design (`exit 1` with the reference) are in the YAML so you cannot miss them.
2. **Images.** Every stage needs an image the organisation's [image policy](/guides/ankra-pipelines#organisation-ci-settings) allows - and so does every sidecar you declare in the pipeline's `services` block, whose image and `env` are held to the same boundary a step's own are, refusing the whole step rather than running beside it. A policy prefix is matched at a path boundary, and one ending in `/`, `:` or `@` admits only that boundary (`ghcr.io/my-org/` admits `ghcr.io/my-org/api` and not `ghcr.io/my-org:v1`) - the settings API refuses a trailing separator at write time anyway, so write the bare prefix. Pin the toolchain images the notes could not derive, and replace the runner image on any stage that needs more than it ships ([Jobs with no container](#jobs-with-no-container)).
3. **Network.** A `run` stage's tier defaults to `none`, which denies all egress; give `defaults.network: egress-https`, or a `network` on the stage itself, to the ones that install packages or reach a registry. The converted `checkout`, `build` and `scan` stages need nothing said about them: those three kinds default to `egress-https` ([the tier a stage gets by default](/guides/pipeline-reference#the-tier-a-stage-gets-by-default)). That tier reaches public addresses only, so a job that pulled from a VPC-internal mirror, an in-cluster registry or an internal Git host needs its range in [`ci_egress_allowed_cidrs`](/guides/ankra-pipelines#organisation-ci-settings) *before* the converted stage runs, and without it fails on a connection timeout rather than a permission error. Remember that anything above `egress-https` is a protected section - as are a stage's `timeout`, `cache`, `resources` and `with:` block, and the whole `services` block. A converted pipeline that declares any of them runs its pull requests under the last approved authority until an administrator approves the definition on your default branch; see [Logic is open, authority is closed](/guides/ankra-pipelines#logic-is-open-authority-is-closed).
4. **Secrets and credentials.** The converter declares what the workflow referenced; the `secrets` block names a source (`app_env_secret`, `org_variable`, `registry`, `credential`) that has to exist in the organisation. Delivery is live for `secrets` sourced `app_env_secret`, `org_variable` or `registry`, and for `credentials` sourced `git` or `registry` - each revealed once, at step start, to a file the step reads. `secrets: [{from: credential}]` still validates but is not deliverable yet, and a `credentials` binding sourced `cloud` or `object_storage` is refused by name until the run has its own scoped identity - reconsider any converted cloud-credential step against that gap.
5. **Filters.** Where a `rules:`, `except:` or trigger `types` narrowing was lost, add `when:` or `if:` so the pipeline does not run more often than the workflow did.
6. **Resources and timeouts.** A stage takes 500m CPU, 1Gi memory and 30 minutes unless it says otherwise; a Go build or a Playwright suite wants more of the first two. A pull request from a fork gets less than a converted workflow may expect, whatever the file asks for: 2 CPU, 4Gi, a 60-minute step timeout, 8 matrix legs per stage, no sidecar services and no caches, with 256 MiB of artifacts and logs for the whole run. The clamps are applied to the plan, so the pull request's own status comment shows the smaller run rather than the one the file declared - see [Forks](/guides/ankra-pipelines#what-a-step-runs-as).
7. **Caches, if you add one by hand.** A `cache:` block does not behave the way `actions/cache` does across branches. An Ankra cache claim is scoped to the trust of the run that resolved it, so every run that is not on your default branch - a feature branch, a tag, any pull request - shares one non-default scope, and none of them can read or write the claim your default branch's builds use. GitHub restores a default-branch cache into any branch; Ankra deliberately does not, because that is the path a less-trusted ref uses to poison what production builds from. Budget one cold build per cache key on each side of that line, and none at all on a fork's pull request, which resolves no shared cache.
8. **What executes today, and what the converter never adds.** `checkout`, `run`, `build`, `scan`, `gate`, `publish` and `deploy` all execute end to end; `verify` and the kinds with no executor yet (`preview`, `agent`, `approval`, `webhook`, `automation`, `ankra`, `external`) validate with a warning and are **skipped**, so a converted `approval` stage blocks nothing and a converted `webhook` notifies nobody. A `deploy` stage releases only to [host targets](/reference/cli/targets) outside Kubernetes, so a converted job that ran `kubectl` or `helm` does not become one; deploy to a cluster through the application's push to deploy instead - see [What is in place today](/guides/ankra-pipelines#what-is-in-place-today). The converter itself never writes a `gate` or a `publish` stage - no source format has one to map from - so a workflow whose `docker/build-push-action` pushed straight to your registry converts into a pipeline whose `build` stage pushes a digest to Ankra's own **CI staging repository only**, and stops there: without a `gate` stage after `scan` and a `publish` stage after `gate`, nothing ever reaches your real repository. Add both by hand (see the [worked example](/guides/ankra-pipelines#connect-a-repository-push-see-the-run)) rather than assuming the converted file publishes what the workflow did.

Then validate it:

```bash theme={null}
ankra pipeline validate .ankra/pipeline.yaml --application my-service
```

## Run both side by side

Keep the workflow. A pipeline run and a workflow run on the same commit are independent: the workflow's checks keep their names, the pipeline's is `Ankra pipeline`, and both appear on the pull request. But know what actually decides which one a pull request's **preview** deploys from, because it is not a setting you flip: `.ankra/pipeline.yaml` outranks a workflow the moment it is committed on the default branch *and* the organisation has a CI cluster to run it on - the application reads as `ankra_pipeline`-sourced from that point on, whether or not a workflow still runs alongside it, and its previews deploy the pipeline's own digest from then on (one that has not built the head yet answers *build missing* rather than quietly falling back to the workflow's image). A merge to your default branch is more forgiving: your own CI's build observation always outranks the pipeline's, so a workflow that keeps publishing keeps being what gets deployed, and the pipeline's digest is only used once nothing higher-ranked has been observed for that commit. Retire the workflow deliberately, once you have watched the pipeline publish correctly on its own for a while.

Two rules for the overlap:

* Do not make `Ankra pipeline` a required check in branch protection until it has been green for as long as you would trust any new CI system, and never while its stages include a kind that does not execute yet. Such a stage is skipped, not failed, so the check goes **green** having done none of what the stage names - read the run's skipped stages, not only its conclusion.
* Retire the workflow deliberately. Ankra does not delete a workflow for you; when it proposes retiring a generated one, it will be a reviewable pull request that you merge.

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> Prerequisites, the first green run, the security model and limits.

> [card] [pipeline.yaml reference](/guides/pipeline-reference)
>
> Every key, the expression language and the diagnostics the validator reports.


# Write an ankra migrate Module
Source: https://docs.ankra.ai/guides/migrate-modules

Teach ankra migrate a new source format with an executable that answers describe, detect, convert and optionally export as JSON over stdin and stdout.

> [!NOTE]
>
> A module teaches `ankra migrate` one source format. It is an executable named `ankra-module-<name>` that answers three verbs, each with a JSON request on stdin and a JSON reply on stdout, so it can be written in any language. The built-in `docker` module is the same contract implemented in-process, and is the reference implementation.

## When to write one

`ankra migrate convert` turns a deployment description into an [ImportCluster](/guides/import-cluster) manifest plus the [manifests](/concepts/stacks#manifests) its [stack](/concepts/stacks) refers to. The `docker` module reads Compose files, bare Dockerfiles and the running Docker daemon, and is the only module that ships with the CLI. Every other source format is a module somebody writes: a Heroku-style Procfile, a Nomad job specification, a systemd unit directory, or the in-house deployment description your team has been maintaining for years.

Write one when you convert the same format more than once. A module makes the translation repeatable and reviewable: the same input produces the same stack, in a pull request, for every service that uses that format.

## How the CLI finds your module

The executable is named `ankra-module-<name>`, where `<name>` is the token users type after `--module`. The CLI looks in `~/.ankra/modules` first and then in every directory on `PATH`, so a module can be installed without touching `PATH` at all. It must be executable, and a name that collides with a built-in is ignored, so no module can shadow `docker`.

```bash theme={null}
ankra migrate modules install https://example.com/downloads/ankra-module-procfile \
  --sha256 <hex-digest>

ankra migrate modules
```

### Installing a module

`ankra migrate modules install <url-or-file>` fetches one module executable, from an `https` URL or a local file, into `~/.ankra/modules`. There is no index and no registration: the URL is the distribution, and the module's own `describe` answer is the handshake. Nothing is kept until that answer checks out, because the download is staged in a temporary file, run there, and only then moved into place under the name the module calls itself - which is the name you will later type after `--module`.

| Flag | What it does |
| - | - |
| `--sha256 <hex>` | Pin the download. A digest that does not match is refused before anything runs |
| `--name <name>` | Assert the name you expect. A module that calls itself something else is refused rather than installed under a surprise name |
| `--force` | Replace a module of the same name that is already installed. Without it, an existing one is left alone |
| `-y, --yes` | Skip the confirmation prompt |

Plain `http://` is refused, because the network would otherwise choose which executable you run, and a download larger than 256 MiB is refused as well. The confirmation states in as many words that the module's `describe` verb is about to run and that the module later runs with your permissions. The command prints the sha256 of what it installed, so you can record it or compare it with a checksum the author published.

> [!WARNING]
>
> A module is an executable you are choosing to run. It reads your files, and an `export` module reaches whatever the source's data lives behind, such as your Docker socket. Install only modules you trust, and pass `--sha256` whenever the author publishes a digest.

`ankra migrate modules uninstall <name>` removes what `install` put in `~/.ankra/modules`, after a confirmation that `--yes` skips. It never deletes anything else: a module that lives on `PATH` was put there by something other than the CLI, so the command refuses it and names the location, leaving you to remove it the way it was installed.

Placing the executable yourself still works, and discovery does not care how it got there. `install` exists so that fetching, verifying and naming a module is one auditable step rather than four.

`ankra migrate modules` runs the `describe` verb of every candidate it finds and lists the name, version, source (`built-in`, or the path it was found at) and summary. A module that fails to load is reported on stderr as `skipped <path>: <reason>` and the listing carries on, so one broken executable never takes the command down. Pass `-o json` to see the full description, including the capabilities the table does not show.

`ankra migrate convert`, `export` and `up` choose a module by asking every one of them whether it recognises the directory and taking the most confident answer. Ties are broken alphabetically by module name, and a directory nothing recognises is refused with `no module recognises <dir>`. `--module <name>` skips detection and picks one explicitly.

## The protocol

One verb per invocation, as `argv[1]`. The request is JSON on stdin, the reply is JSON on stdout. Exiting non-zero fails the verb, and the module's stderr becomes the reason the user sees (the last five lines of it). The protocol version is `1`; the CLI refuses a module that reports any other, rather than guessing at the shape of its output.

| Verb | Request | Reply | Time limit |
| - | - | - | - |
| `describe` | none | `name`, `version`, `protocol`, `summary`, `file_patterns`, `capabilities` | 15s |
| `detect` | `dir` | `confidence`, `files`, `reason` | 30s |
| `convert` | `dir`, `cluster_name`, `namespace`, `options` | `cluster`, `files`, `warnings` | 5m |
| `export` | `dir`, `output_dir`, `namespace`, `options` | `databases`, `warnings` | 6h |

`export` is optional and answered only by a module that lists `"export"` under `capabilities` in its description. The CLI trusts the capability, so a module that omits it is never asked.

### describe

No input. Report what the module is:

```json theme={null}
{"name": "procfile", "version": "1.0", "protocol": 1,
 "summary": "Heroku-style Procfile (one Deployment per process type)",
 "file_patterns": ["Procfile"]}
```

`version` is the module's own version, not the CLI's. `file_patterns` is shown to users so an empty detection is explainable rather than mysterious. `describe` must not touch the filesystem: it is called for every listing.

### detect

The request is `{"dir": "/absolute/path"}`. Reply with a confidence from 0 (not mine) to 1 (certain), the files found, and a one-line reason - including for a zero score, because "not mine, and here is why" is an answer rather than a failure:

```json theme={null}
{"confidence": 1, "files": ["Procfile"], "reason": "Procfile present"}
```

```json theme={null}
{"confidence": 0, "reason": "no Procfile"}
```

Reserve 1 for an unambiguous marker file. A module working from a heuristic should score itself lower so a more specific module wins the directory: the built-in `docker` module scores a Compose file 1 and a lone Dockerfile 0.6 for exactly that reason.

### convert

The request carries the directory, the names the output will use, and every `--option key=value` the user passed, untouched, so a module can take input the CLI knows nothing about:

```json theme={null}
{"dir": "/absolute/path", "cluster_name": "shop", "namespace": "shop",
 "options": {"image": "ghcr.io/org/shop:1.2"}}
```

The reply is the resources:

```json theme={null}
{"cluster": {"apiVersion": "ankra.io/v1alpha1", "kind": "ImportCluster",
   "metadata": {"name": "shop", "description": "Converted from Procfile"},
   "spec": {"stacks": [{"name": "shop", "manifests": [
     {"name": "namespace", "from_file": "manifests/namespace.yaml"},
     {"name": "web", "from_file": "manifests/web.yaml", "namespace": "shop",
      "parents": [{"name": "namespace", "kind": "manifest"}]}]}]}},
 "files": {"manifests/namespace.yaml": "apiVersion: v1\n...",
           "manifests/web.yaml": "apiVersion: apps/v1\n..."},
 "warnings": ["web listens on 8080; put an Ingress in front of Service web to expose it"]}
```

* `cluster` is the ImportCluster the CLI writes to `cluster.yaml`. Every `from_file` in its stacks must name a key of `files`, and it must have a name; the CLI validates both before it writes anything.
* `files` keys are paths relative to the output directory. An absolute path, or one containing `..`, is rejected before a byte is written.
* `warnings` are for everything the module could not translate faithfully: an unmappable construct, a value the user has to supply, a credential written in plain text. A partial conversion a person can finish beats none, so warn rather than fail wherever you can.

Four rules keep the output reviewable:

* **Never write to the source directory.** Convert reads; the CLI writes.
* **Be deterministic.** Sort everything. Output that reorders itself on each run cannot be reviewed in a pull request.
* **Keep secrets out of ConfigMaps.** Put credentials in a `Secret` and warn that it needs encrypting with [`ankra cluster encrypt`](/guides/sops) before it is committed.
* **Encode dependency order as `parents`.** A workload that must start after another lists it as `parents: [{name, kind: manifest}]`. That is how a source format's start order survives the conversion.

Set `enableServiceLinks: false` on the pods you generate. Kubernetes injects a `<SERVICE>_PORT` variable for every Service in the namespace, and applications that read a variable of the same name break on it.

## export, for a module that can dump its data

A module that can also dump the databases behind its source lists `"capabilities": ["export"]` in `describe` and answers a fourth verb, which backs `ankra migrate export`. The request adds the output directory, which the CLI has already created:

```json theme={null}
{"dir": "/absolute/path", "output_dir": "/absolute/output", "namespace": "shop",
 "options": {"docker-host": "ssh://root@203.0.113.7"}}
```

Write each dump under `output_dir` and reply with what you wrote and where it restores to - the Service and Secret that `convert` generated for the same workload, so the restore needs nothing the user has to look up:

```json theme={null}
{"databases": [{"workload": "db", "engine": "postgres", "server_version": "17.2",
  "target": {"namespace": "shop", "host": "db", "port": 5432, "username": "app",
             "password_secret": "db-secrets", "password_key": "POSTGRES_PASSWORD"},
  "artifacts": [{"path": "db/globals.sql", "kind": "globals", "format": "sql"},
                {"path": "db/app.dump", "kind": "database", "format": "pg_custom",
                 "database": "app"}]}],
 "warnings": ["dumped while the source was live"]}
```

* `engine` is `postgres` or `mysql`, and nothing else can be restored. `format` is `pg_custom` (a `pg_dump -Fc` archive, PostgreSQL only) or `sql` (plain SQL, including `pg_dumpall --globals-only` output and `mysqldump` files). `kind` is `database`, which must name its `database`, or `globals`, which only PostgreSQL has.
* `target.host` must be a Service in `target.namespace`. The platform accepts `db`, `db.shop`, `db.shop.svc` and `db.shop.svc.cluster.local`, and refuses anything else with `Database db target host "..." is not a Service in namespace shop` - the restore Job carries the target's credentials, and a host the manifest could point anywhere would carry them out of the cluster.
* Artifact paths are relative to `output_dir` and may not escape it. `manifest.json` and `SHA256SUMS` are refused as artifact names, because the CLI writes them itself: it measures every file's size and SHA-256 sum, rejects one that is empty or was never written, and finalises the export into a self-contained directory that `sha256sum -c` can verify. Do not report sizes or checksums yourself.
* **Narrate progress on stderr.** It is relayed to the user live while the verb runs, which matters when a dump takes minutes, and it is shown as the reason on failure.
* A single artifact above 625 GiB cannot be uploaded, so split a database that large across smaller dumps.

## A worked example

`examples/modules/ankra-module-procfile` in the CLI repository is a complete module in about a hundred lines of Python. It reads a Heroku-style Procfile - one `name: command` per line - and emits a Deployment per process type, plus a Service for `web`. The shape of it is the whole contract:

```python theme={null}
#!/usr/bin/env python3
import json
import os
import sys

NAME = "procfile"
VERSION = "1.0"
PROTOCOL = 1


def describe():
    return {
        "name": NAME,
        "version": VERSION,
        "protocol": PROTOCOL,
        "summary": "Heroku-style Procfile (one Deployment per process type)",
        "file_patterns": ["Procfile"],
    }


def detect(request):
    if not os.path.isfile(os.path.join(request["dir"], "Procfile")):
        return {"confidence": 0, "reason": "no Procfile"}
    return {"confidence": 1, "files": ["Procfile"], "reason": "Procfile present"}


def convert(request):
    # Read the source, render the manifests, and name them in the cluster's
    # stack. request["options"] holds every --option the user passed.
    return {"cluster": cluster, "files": files, "warnings": warnings}


def main():
    verb = sys.argv[1] if len(sys.argv) > 1 else ""
    if verb == "describe":
        reply = describe()
    elif verb in ("detect", "convert"):
        request = json.load(sys.stdin)
        reply = detect(request) if verb == "detect" else convert(request)
    else:
        sys.stderr.write(f"unknown verb {verb!r}; expected describe, detect, or convert\n")
        sys.exit(2)
    json.dump(reply, sys.stdout)


if __name__ == "__main__":
    main()
```

A Procfile says how to run a process, never what to run it from, so its `convert` exits 2 with `the procfile module needs --option image=<registry/repo:tag>` on stderr when that option is missing. That is the pattern for input the CLI knows nothing about.

Install it and run it end to end:

```bash theme={null}
ankra migrate modules install ./examples/modules/ankra-module-procfile --yes

mkdir -p /tmp/demo
printf 'web: bundle exec puma\nworker: bundle exec sidekiq\n' > /tmp/demo/Procfile

ankra migrate modules
ankra migrate detect /tmp/demo
ankra migrate convert /tmp/demo --module procfile --option image=ghcr.io/org/app:1.0 --dry-run
```

## Testing a module

The verbs are ordinary processes, so test them without the CLI in the way:

```bash theme={null}
ankra-module-procfile describe
echo '{"dir": "/tmp/demo"}' | ankra-module-procfile detect
echo '{"dir": "/tmp/demo", "cluster_name": "demo", "namespace": "demo", "options": {"image": "ghcr.io/org/app:1.0"}}' \
  | ankra-module-procfile convert
```

Then check how the CLI sees it. `ankra migrate detect <dir>` prints every module's confidence, files and reason, most confident first, which is exactly what `convert` picks from. `ankra migrate convert --dry-run` prints the rendered `cluster.yaml` and the files that would be written without writing any of them, and still runs the full validation, so an unsafe path or a manifest pointing at a file you did not return fails there rather than on disk.

## What an external module does not get

> [!WARNING]
>
> Two capabilities of the built-in `docker` module are Go interfaces rather than protocol verbs, so an external module cannot implement them today.

* **No plan preflight in `ankra migrate up`.** The built-in module can describe an export before running it, which is how the plan reports each database's size against your free disk. An external module is exported without that preflight, and the plan says so: `the <name> module does not describe its export up front; sizes are unknown until the dump runs`.
* **No `--stop-source`.** Stopping the source's non-database services before the final dump is the built-in module's, so `ankra migrate up --stop-source` is refused for an external module with `the <name> module cannot stop the source's services; stop them yourself, then run without --stop-source`.
* **Restores are PostgreSQL and MySQL only**, in the `sql` and `pg_custom` formats, into a Service in the target namespace. A module can dump anything it likes, but the platform will only restore that.

## Plugins are a different mechanism

A module teaches `ankra migrate` a source format. If what you want is a new `ankra` command instead, that is a **plugin**, and the CLI dispatches to them the way `kubectl` does.

An executable named `ankra-<command>` in `~/.ankra/plugins` or anywhere on `PATH` runs as `ankra <command>`, with the remaining arguments, this terminal's standard input, output and error, and `ANKRA_CLI_VERSION` in its environment. Its exit code becomes the CLI's, so a plugin is scriptable exactly like a built-in command.

```bash theme={null}
ankra plugins
```

* **Built-in commands always win.** A plugin can extend the CLI but never change it, and `ankra plugins` warns about one that a built-in shadows and will therefore never run.
* **Multi-word names resolve longest first.** With both installed, `ankra foo bar` runs `ankra-foo-bar` rather than `ankra-foo` with `bar` as an argument.
* `~/.ankra/plugins` is searched before `PATH`, the same order `ankra migrate modules` uses for `~/.ankra/modules`.

The two mechanisms never collide, because they are told apart by the file name: `ankra-module-<name>` is a migrate module, listed by `ankra migrate modules`, and anything else beginning with `ankra-` is a plugin, listed by `ankra plugins`. There is no installer for plugins; put the executable in `~/.ankra/plugins` yourself. A plugin runs with your permissions, so the same rule applies as for modules: only install ones you trust.

## Next steps

> [card] [Move a Docker deployment](/guides/migrate-from-docker)
>
> What the built-in module does, end to end.

> [card] [Stacks](/concepts/stacks)
>
> The shape your `cluster` reply has to produce.

> [card] [Import a cluster](/guides/import-cluster)
>
> The ImportCluster manifest a conversion writes.

> [card] [Ankra CLI](/integrations/ankra-cli)
>
> Install the CLI and browse the rest of its commands.


# Run Kubernetes Locally
Source: https://docs.ankra.ai/guides/minikube

A basic tutorial on how to run Kubernetes locally using Minikube.

This tutorial guides you through setting up a local Kubernetes cluster using Minikube, with a focus on exposing services using LoadBalancer and the essential `minikube tunnel`.

***

## Prerequisites

Before you begin, ensure you have the following installed:

* A supported hypervisor or container runtime:
  * [Docker](https://docs.docker.com/get-docker/)
  * [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
  * [Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/)
  * [KVM](https://www.linux-kvm.org/page/Downloads)
  * [Podman](https://podman.io/getting-started/installation)
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (Kubernetes command-line tool)

***

## Installation

### Minikube

> [tab] macOS
>
> ```bash theme={null}
> brew install minikube
> ```

> [tab] Linux
>
> ```bash theme={null}
> curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
> sudo install minikube-linux-amd64 /usr/local/bin/minikube
> ```

> [tab] Windows
>
> Download the [Windows installer](https://github.com/kubernetes/minikube/releases/latest/download/minikube-installer.exe) and run it, or use Chocolatey:
>
> ```powershell theme={null}
> choco install minikube
> ```

For other installation methods, refer to the [official Minikube documentation](https://minikube.sigs.k8s.io/docs/start/).

***

### Installing kubectl

> [tab] macOS
>
> ```bash theme={null}
> brew install kubectl
> ```

> [tab] Linux
>
> ```bash theme={null}
> sudo apt-get update
> sudo apt-get install -y kubectl
> ```

> [tab] Windows
>
> ```powershell theme={null}
> choco install kubernetes-cli
> ```

For other installation methods, visit the [official kubectl installation guide](https://kubernetes.io/docs/tasks/tools/install-kubectl/).

***

## Starting Your Local Cluster

> [tab] macOS / Linux
>
> ```bash theme={null}
> minikube start
> ```

> [tab] Windows
>
> ```powershell theme={null}
> minikube start
> ```

This command will initialize a new Kubernetes cluster in your local environment. The process may take a few minutes as it downloads the necessary components and sets up the virtual machine.

***

## Connecting Ankra to Your Local Cluster

To begin deploying services through Ankra, you need to import your Minikube cluster into the platform by connecting the Ankra Agent to your local cluster.

1. Navigate to the **Clusters** tab in the Ankra UI.
2. Click **Import Cluster**.
3. Enter the **Cluster Name**.
4. Connect a **GitHub Credential** and select a GitHub repository.
   * The chosen repository will be where Ankra stores the YAML configuration files for the services deployed onto your local cluster from the Ankra Library.
5. Run the Helm command provided in the Ankra UI to connect the Ankra Agent to your local cluster.
6. Once your cluster is imported, you will be able to view the cluster dashboard and begin [installing add-ons](/concepts/addons).

***

> **Optional:** If your services will be of type `LoadBalancer`, you will need to start the Minikube tunnel by running the following command in a separate terminal to provide them with a public IP address:

> [tab] macOS / Linux
>
> ```bash theme={null}
> minikube tunnel
> ```

> [tab] Windows
>
> ```powershell theme={null}
> minikube tunnel
> ```

***


# Mobile push notifications
Source: https://docs.ankra.ai/guides/mobile-push

How a notification reaches a phone, what decides whether it interrupts, and why a device can register and still never ring

The Ankra mobile app can receive notifications on iOS and Android. Nothing arrives by default: a notification reaches a phone only when a **routing rule** sends it to a push audience, exactly as it would send one to a webhook.

```mermaid theme={null}
flowchart TD
    Event[Notification recorded] --> Routes[Routing rules evaluated]
    Routes --> Match{A rule with a push destination matches?}
    Match -->|No| Inbox[Inbox only]
    Match -->|Yes| Audience[Audience resolved to members]
    Audience --> Mutes{Member has muted this kind?}
    Mutes -->|Yes| Silent[No delivery]
    Mutes -->|No| Devices[One delivery per registered device]
    Devices --> APNs[iOS via APNs]
    Devices --> FCM[Android via FCM]
```

## Registering a phone

Devices add themselves. Sign in to the app, accept the notification prompt, and the device appears under **Profile → Notifications → Push notifications**. There is no "add device" action, and no credential to copy: the app holds none of its own. It hands the token to the signed-in page, and the page registers it against your session — which is why a device always belongs to exactly the member who signed in on it, and why signing in on a shared phone re-homes that device to you.

Each row shows the platform, OS and app version, and the last characters of the token, which is what tells two of your own phones apart. From the row you can:

* **Mute one device** without signing out of it, or removing it.
* **Remove it**, which stops delivery to that install entirely.
* **Send test**, which delivers straight to that device without consulting any routing rule. This is the one path that bypasses routing, so it proves the device and the credentials work even before a rule exists.

You manage only your own devices. There is no organisation-wide view of who has push enabled, and an administrator cannot revoke someone else's phone.

## Sending to phones

Under **Alerting** → **Destinations** → **Routing rules**, a rule's destination type can be **Push notification** instead of a webhook. The audience decides whose phones:

| Audience | Reaches |
| - | - |
| All cluster members | Everyone who is a member of the cluster the notification is about |
| Organisation admins | Every administrator of the organisation |

A rule filters on kind and severity exactly as any other routing rule does, so "every critical" and "only `bastion_offline`" are both a single rule. The same de-duplication and mute rules apply: a member who has snoozed a kind stays snoozed on their phone, and a notification addressed to one member reaches only that member's devices.

> [!NOTE]
>
> Start narrower than you think you want. A rule for every critical notification is a realistic dozen or more pushes a day on a busy fleet. One or two kinds for a week tells you what the volume actually feels like.

## What decides whether a notification interrupts

Severity, and it behaves differently on each platform because the platforms differ.

| Severity | iOS | Android |
| - | - | - |
| Critical | Sound, time-sensitive — breaks through Focus | Sound, high priority — delivered immediately, even in Doze |
| Warning | Sound, active | Sound, default importance |
| Info | Silent, passive — will not light the screen | Delivered quietly |

On Android the importance comes from the **notification channel**, not from the message. The app creates three — *Critical alerts*, *Warnings* and *Updates* — and Android hands them to you afterwards: change *Warnings* to silent in system settings and it stays silent, through app updates. Ankra cannot override that, which is the point.

Tapping a notification opens the page it is about, on both platforms.

## When a device registers but nothing arrives

The device row is proof that registration worked. It is not proof that delivery will. In order of likelihood:

* **No routing rule sends anything to push.** This is by far the most common answer, and *Send test* will still work, which is exactly why it is confusing. Check **Routing rules** for a rule with a push destination.
* **You have muted the kind.** Mutes are applied before delivery is queued, so a snoozed kind is silent everywhere at once.
* **The row says `sandbox`.** That device is running a development build, whose token belongs to Apple's sandbox APNs host. The two token spaces are separate, and a production notification sent to a sandbox token is silently undelivered. A TestFlight or App Store build registers as production.
* **The row carries a reason.** When Apple or Google reports that a token is dead — the app was removed, or the token rotated — Ankra disables that device and records why, so a stale install is visible rather than a silent gap. Signing in again registers a fresh token.

## What the platform needs configured

Push delivery is a deployment-level capability, and the two platforms are independent: configuring one does not require the other, and a device whose platform has no credential fails only its own deliveries.

| Platform | Secret | Contents |
| - | - | - |
| iOS | `ankra-cluster-apns-secret` | An APNs provider key (`.p8`), its key id, and the team id |
| Android | `ankra-cluster-fcm-secret` | A Firebase service account for the project the app is registered in |

Absent either secret, that platform's deliveries fail with an explanatory status and every other destination — webhook, Slack, Teams — keeps working.


# Build a Monitoring Stack
Source: https://docs.ankra.ai/guides/monitoring-stack

Deploy a complete observability stack with metrics, logs, and alerting using kube-prometheus-stack and Loki

> [!NOTE]
>
> This guide walks you through building a complete observability stack with Prometheus for metrics, Loki for logs, Grafana for visualization, and Alertmanager for notifications.

<video />

Building a Monitoring Stack on Ankra

> [card] [AI Prompts](#ai-prompts)
>
> Use these prompts with the AI Assistant (`⌘+J`) to get recommendations for building your stack.

***

## What You'll Build

A production-ready observability stack:

| Component | Purpose |
| - | - |
| **kube-prometheus-stack** | Prometheus, Grafana, Alertmanager, and exporters in one chart |
| **Loki** | Log aggregation-like Prometheus, but for logs |
| **Promtail** | Ships logs from pods to Loki |

***

## Prerequisites

* A cluster imported into Ankra with the agent connected
* Helm registries added for:
  * **Prometheus Community** (`https://prometheus-community.github.io/helm-charts`)
  * **Grafana** (`https://grafana.github.io/helm-charts`)

***

## Step 1: Create the Stack

**1. Open Stack Builder**

Navigate to your cluster → **Stacks** → **Create Stack**.

**2. Name Your Stack**

Name it `observability` or `monitoring-and-logging`.

***

## Step 2: Add kube-prometheus-stack

This chart bundles everything you need for metrics: Prometheus, Grafana, Alertmanager, node-exporter, and kube-state-metrics.

**1. Add the Chart**

Click **+ Add** → search for `kube-prometheus-stack` from the Prometheus Community repository.

**2. Configure Prometheus**

Click the component and set these values:

```yaml theme={null}
prometheus:
  prometheusSpec:
    retention: 15d
    resources:
      requests:
        memory: 1Gi
        cpu: 500m
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 50Gi
```

**3. Configure Grafana**

```yaml theme={null}
grafana:
  adminPassword: "your-secure-password"  # Change this
  persistence:
    enabled: true
    size: 10Gi
  # Add Loki as a data source (we'll deploy it next)
  additionalDataSources:
    - name: Loki
      type: loki
      url: http://loki-gateway.monitoring.svc.cluster.local
      access: proxy
      isDefault: false
```

**4. Configure Alertmanager for Slack**

```yaml theme={null}
alertmanager:
  config:
    global:
      slack_api_url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL'
    route:
      receiver: 'slack'
      group_by: ['alertname', 'namespace']
      group_wait: 30s
      group_interval: 5m
      repeat_interval: 4h
    receivers:
      - name: 'slack'
        slack_configs:
          - channel: '#alerts'
            send_resolved: true
```

> [!TIP]
>
> **Encrypt sensitive values with SOPS:** In the manifest edit view, click the **SOPS** button to encrypt secrets like `grafana.adminPassword` and `slack_api_url`. This ensures sensitive values are stored encrypted in your GitOps repository. See [SOPS Encryption](/guides/sops) for setup instructions.

***

## Step 3: Add Loki for Logs

Loki is a log aggregation system designed to work seamlessly with Grafana. It's lightweight because it only indexes metadata, not the full log content.

**1. Add Loki**

Click **+ Add** → search for `loki` from the Grafana repository.

Use the **loki** chart (not loki-distributed for simpler setups).

**2. Configure Loki**

```yaml theme={null}
loki:
  auth_enabled: false
  commonConfig:
    replication_factor: 1
  storage:
    type: filesystem
  schemaConfig:
    configs:
      - from: "2024-01-01"
        store: tsdb
        object_store: filesystem
        schema: v13
        index:
          prefix: index_
          period: 24h

# For production, configure object storage:
# storage:
#   type: s3
#   bucketNames:
#     chunks: loki-chunks
#     ruler: loki-ruler
#   s3:
#     endpoint: s3.amazonaws.com
#     region: us-east-1

singleBinary:
  replicas: 1
  resources:
    requests:
      memory: 256Mi
      cpu: 100m
  persistence:
    enabled: true
    size: 20Gi

gateway:
  enabled: true
```

**3. Connect Dependency**

In the Stack Builder, draw a connection from **loki** to **kube-prometheus-stack** to ensure Loki deploys first (so Grafana can connect to it).

***

## Step 4: Add Promtail for Log Collection

Promtail runs as a DaemonSet on every node, collecting logs from all pods and shipping them to Loki.

**1. Add Promtail**

Click **+ Add** → search for `promtail` from the Grafana repository.

**2. Configure Promtail**

```yaml theme={null}
config:
  clients:
    - url: http://loki-gateway.monitoring.svc.cluster.local/loki/api/v1/push
  
  snippets:
    # Add useful labels from pod metadata
    pipelineStages:
      - cri: {}
      - labeldrop:
          - filename
      - match:
          selector: '{app=~".+"}'
          stages:
            - json:
                expressions:
                  level: level
            - labels:
                level:

resources:
  requests:
    memory: 64Mi
    cpu: 50m
  limits:
    memory: 128Mi
    cpu: 100m
```

**3. Connect Dependency**

Draw a connection from **promtail** to **loki**-Promtail needs Loki running to ship logs.

***

## Step 5: Deploy

**1. Review the Stack**

Your Stack Builder should show:

```
promtail → loki → kube-prometheus-stack
```

This ensures correct deployment order.

**2. Save and Deploy**

Click **Save**, then **Deploy**. Watch progress in **Operations**.

**3. Verify Deployment**

After 3-5 minutes, all pods should be running:

* `prometheus-*`
* `grafana-*`
* `alertmanager-*`
* `loki-*`
* `promtail-*` (one per node)

***

## Step 6: Explore in Grafana

**1. Access Grafana**

Port-forward to access locally:

```bash theme={null}
kubectl port-forward svc/kube-prometheus-stack-grafana 3000:80 -n monitoring
```

Or configure an ingress in the values.

**2. Log In**

* **Username:** `admin`
* **Password:** The value you set in `grafana.adminPassword`

**3. Query Metrics**

Go to **Explore** → Select **Prometheus** → Try:

```promql theme={null}
sum(rate(container_cpu_usage_seconds_total{namespace="default"}[5m])) by (pod)
```

**4. Query Logs**

Go to **Explore** → Select **Loki** → Try:

```logql theme={null}
{namespace="default"} |= "error"
```

**5. Correlate Metrics and Logs**

The power of this stack: when you see a spike in metrics, click through to see logs from that exact time range.

***

## Production Considerations

> [accordion] Scale Loki for High Volume
>
> For clusters generating >100GB/day of logs, use distributed mode:
>
> ```yaml theme={null}
> # Use loki-distributed chart instead
> loki:
>   schemaConfig:
>     configs:
>       - from: "2024-01-01"
>         store: tsdb
>         object_store: s3
>         schema: v13
>         index:
>           prefix: index_
>           period: 24h
>   storage:
>     type: s3
>     s3:
>       endpoint: s3.amazonaws.com
>       region: us-east-1
>       bucketnames:
>         chunks: your-loki-chunks-bucket
>         ruler: your-loki-ruler-bucket
> ```

> [accordion] Increase Prometheus Retention
>
> ```yaml theme={null}
> prometheus:
>   prometheusSpec:
>     retention: 30d
>     retentionSize: 80GB
>     storageSpec:
>       volumeClaimTemplate:
>         spec:
>           storageClassName: fast-ssd
>           resources:
>             requests:
>               storage: 100Gi
> ```

> [accordion] Add Recording Rules
>
> Pre-compute expensive queries:
>
> ```yaml theme={null}
> additionalPrometheusRulesMap:
>   recording-rules:
>     groups:
>       - name: resource-usage
>         interval: 30s
>         rules:
>           - record: namespace:container_cpu_usage:sum_rate
>             expr: sum(rate(container_cpu_usage_seconds_total[5m])) by (namespace)
> ```

> [accordion] Configure Log Retention
>
> Set how long Loki keeps logs:
>
> ```yaml theme={null}
> loki:
>   limits_config:
>     retention_period: 168h  # 7 days
>   compactor:
>     retention_enabled: true
> ```

***

## Adding Custom Alerts

> [accordion] Pod Restart Alert
>
> ```yaml theme={null}
> additionalPrometheusRulesMap:
>   pod-alerts:
>     groups:
>       - name: pod-health
>         rules:
>           - alert: PodRestartingTooMuch
>             expr: increase(kube_pod_container_status_restarts_total[1h]) > 3
>             for: 5m
>             labels:
>               severity: warning
>             annotations:
>               summary: "Pod {{ $labels.pod }} restarting frequently"
>               description: "Pod has restarted {{ $value }} times in the last hour"
> ```

> [accordion] High Error Rate Alert
>
> ```yaml theme={null}
> additionalPrometheusRulesMap:
>   app-alerts:
>     groups:
>       - name: application
>         rules:
>           - alert: HighErrorRate
>             expr: |
>               sum(rate(http_requests_total{status=~"5.."}[5m])) 
>               / sum(rate(http_requests_total[5m])) > 0.05
>             for: 5m
>             labels:
>               severity: critical
>             annotations:
>               summary: "High 5xx error rate"
>               description: "Error rate is {{ $value | humanizePercentage }}"
> ```

> [accordion] Disk Space Alert
>
> ```yaml theme={null}
> additionalPrometheusRulesMap:
>   node-alerts:
>     groups:
>       - name: node-health
>         rules:
>           - alert: DiskSpaceLow
>             expr: |
>               (node_filesystem_avail_bytes{mountpoint="/"} 
>               / node_filesystem_size_bytes{mountpoint="/"}) < 0.1
>             for: 10m
>             labels:
>               severity: critical
>             annotations:
>               summary: "Low disk space on {{ $labels.instance }}"
>               description: "Less than 10% disk space remaining"
> ```

***

## Troubleshooting

> [accordion] Logs Not Appearing in Loki
>
> 1. Check Promtail pods are running on all nodes:
>    ```bash theme={null}
>    kubectl get pods -n monitoring -l app.kubernetes.io/name=promtail
>    ```
> 2. Check Promtail logs for errors:
>    ```bash theme={null}
>    kubectl logs -n monitoring -l app.kubernetes.io/name=promtail --tail=50
>    ```
> 3. Verify Loki is reachable from Promtail:
>    ```bash theme={null}
>    kubectl exec -n monitoring -it $(kubectl get pod -n monitoring -l app.kubernetes.io/name=promtail -o name | head -1) -- wget -q -O- http://loki-gateway.monitoring.svc.cluster.local/ready
>    ```

> [accordion] Grafana Can't Connect to Loki
>
> 1. Verify the Loki data source URL matches your service name
> 2. Check Loki gateway is running:
>    ```bash theme={null}
>    kubectl get svc -n monitoring | grep loki
>    ```
> 3. Test from Grafana pod:
>    ```bash theme={null}
>    kubectl exec -n monitoring -it $(kubectl get pod -n monitoring -l app.kubernetes.io/name=grafana -o name) -- curl http://loki-gateway.monitoring.svc.cluster.local/ready
>    ```

> [accordion] High Memory Usage
>
> * **Prometheus:** Reduce scrape frequency, shorten retention, drop unused metrics
> * **Loki:** Reduce retention period, use object storage instead of filesystem
> * **Promtail:** Limit which logs are collected using `pipelineStages` to drop verbose logs

> [accordion] Slow Log Queries
>
> 1. Add more labels in Promtail for better filtering
> 2. Use time range filters in queries
> 3. For production, use Loki distributed mode with more queriers

***

## AI Prompts

Press `⌘+J` to open the AI Assistant and use these prompts to get recommendations for your stack:

> [accordion] Complete Observability Stack
>
> ```
> Build an observability stack with:
> - kube-prometheus-stack for metrics
> - Loki for logs with 7 day retention
> - Promtail to collect logs from all pods
> - Configure Grafana with both data sources
> - Send alerts to Slack
> ```

> [accordion] Production Stack with Object Storage
>
> ```
> Create a production monitoring stack:
> - Prometheus with 30 day retention on 100GB storage
> - Loki configured for S3 storage in us-east-1
> - Alertmanager with Slack notifications to #platform-alerts
> - Include alerts for pod restarts, high CPU, and disk space
> ```

> [accordion] Lightweight Stack for Dev Clusters
>
> ```
> I need a lightweight observability stack for a dev cluster.
> Keep total memory under 2GB. Include Prometheus, Loki, and 
> Grafana but with minimal retention (3 days for both).
> ```

> [accordion] Add Logging to Existing Prometheus
>
> ```
> I already have kube-prometheus-stack running. Add Loki and 
> Promtail to my stack and configure the Loki data source in 
> my existing Grafana.
> ```

> [accordion] Debug Log Collection Issues
>
> ```
> My Promtail isn't sending logs to Loki. Help me troubleshoot
> and fix the configuration.
> ```

> [!TIP]
>
> The AI provides recommendations for components, dependencies, and values. Just describe what you need, build based on the guidance, and deploy.

***

## Next Steps

> [card] [Configure Ankra Alerts](/guides/alerts)
>
> Set up Ankra alerts alongside Prometheus Alertmanager.

> [card] [GitOps Sync](/concepts/gitops)
>
> Store your observability stack configuration in Git.

> [card] [Add Tracing](https://grafana.com/docs/tempo/latest/)
>
> Complete the observability trifecta with Tempo for distributed tracing.

> [card] [Explore with AI](/platform/ai-assistant)
>
> Use the AI to query your logs and metrics in natural language.


# Morpheus Clusters
Source: https://docs.ankra.ai/guides/morpheus-clusters

Create a Kubernetes cluster through your HPE Morpheus appliance, on the groups, clouds, networks and service plans you already manage there, with Ankra installing and operating Kubernetes.

Choose HPE Morpheus when your infrastructure is already governed through a Morpheus appliance and a Kubernetes cluster has to be provisioned the same way. Ankra provisions the instances through your appliance, using the groups, clouds, networks, virtual images and service plans you already manage there, installs Kubernetes, and then operates the cluster for you - this is an **Ankra Managed** cluster.

> [!WARNING]
>
> **Closed beta.** Morpheus cluster provisioning is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request. [Contact support](/platform/support) to have it turned on for your organisation.

## Before you start

* A **Morpheus API credential**: the appliance URL and a long-lived API access token. See [Morpheus Credentials](/platform/credentials/morpheus).
* An **SSH key credential** for instance access - your own public key, or one Ankra generates. See [SSH Key Credentials](/platform/credentials/ssh-key).
* In Morpheus: **a group and a cloud** the token can provision into, **a network with DHCP** (instances get their addresses from it), **an instance layout** based on a Linux cloud image (optionally pinned to a **virtual image**), and **service plans** to size the bastion, control plane and workers.
* **API reachability.** The Morpheus API must be reachable from Ankra, directly or through an [SSH jumphost](#hybrid-connectivity-ssh-jumphost).

### Hybrid connectivity (SSH jumphost)

If Ankra cannot reach the Morpheus appliance and the instance network directly, attach an **SSH jumphost** (host, port, username and private key) to the Morpheus credential; Ankra then tunnels both the Morpheus API calls and the SSH connections to your nodes through it. If the appliance uses a self-signed certificate, enable **TLS insecure** (`tls_insecure`) on the credential. Both are set on the credential - see [Morpheus Credentials](/platform/credentials/morpheus).

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **Morpheus** under **Ankra Managed**.
>
> **2. Credential**
>
> Pick the Morpheus credential and an SSH key, or add either inline.
>
> **3. Placement**
>
> Pick the Morpheus **Group**, **Cloud** and **Network** for the instances, and the **Layout** they are provisioned from. The network must provide DHCP.
>
> **4. Compute**
>
> Pick the bastion's service plan, the control plane count (1 or 3) and service plan, worker node groups, and for kubeadm the etcd topology. The wizard shows each plan's vCPUs and memory; cost estimates are not available for Morpheus.
>
> **5. Kubernetes**
>
> Keep **kubeadm** (the default, with Cilium) or pick **k3s** and its CNI, and optionally the version. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time).
>
> **6. Review**
>
> Name the cluster and set its environment. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik and cert-manager as Ankra-managed stacks. On k3s they run through the built-in service load balancer; unchecked, k3s keeps its bundled Traefik and no certificate manager (a kubeadm cluster gets no ingress controller or certificate manager at all).
> * **Include Public DNS** - a delegated subdomain on `ankra.cc` with external-dns wired, so an ingress hostname under it gets its DNS record and TLS certificate automatically.
>
> Click **Create cluster**. A progress view follows the SSH keys, bastion, instances, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials morpheus create --name my-morpheus --api-url https://morpheus.example   # prompts for the access token
> ankra credentials morpheus ssh-key create --name my-ssh-key --generate
>
> # The numeric IDs the create needs
> ankra cluster morpheus groups --credential-id <morpheus-credential-id>
> ankra cluster morpheus clouds --credential-id <morpheus-credential-id>
> ankra cluster morpheus networks --credential-id <morpheus-credential-id>
> ankra cluster morpheus layouts --credential-id <morpheus-credential-id>
> ankra cluster morpheus plans --credential-id <morpheus-credential-id>
>
> ankra cluster morpheus create \
>   --name my-cluster \
>   --credential-id <morpheus-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --group-id 1 \
>   --cloud-id 1 \
>   --network-id 2 \
>   --layout-id 42 \
>   --bastion-plan-id 101 \
>   --control-plane-count 1 \
>   --control-plane-plan-id 102 \
>   --worker-count 2 \
>   --worker-plan-id 102
> ```
>
> `--virtual-image-id`, `--distribution k3s`, `--etcd-topology external` with `--etcd-node-count` and `--etcd-plan-id`, and `--include-networking=false` cover the other choices. The credential flags `--tls-insecure` and `--jumphost-*` set the options from [Hybrid connectivity](#hybrid-connectivity-ssh-jumphost).

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/morpheus \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<morpheus-credential-id>",
>     "ssh_key_credential_id": "<ssh-key-credential-id>",
>     "group_id": 1,
>     "cloud_id": 1,
>     "network_id": 2,
>     "layout_id": 42,
>     "bastion_plan_id": 101,
>     "control_plane_count": 1,
>     "control_plane_plan_id": 102,
>     "worker_plan_id": 102,
>     "node_groups": [
>       {"name": "default", "plan_id": 102, "count": 2}
>     ],
>     "include_networking": true,
>     "include_dns": true
>   }'
> ```
>
> Every Morpheus ID is the numeric ID from your appliance. `worker_plan_id` is required even when `node_groups` sizes the workers. Every field is in the [Morpheus Reference](/reference/morpheus).

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created through your appliance

* **A bastion instance** - the only SSH access point Ankra uses to reach the nodes. It carries no workload or egress traffic. With a jumphost on the credential, Ankra reaches both the Morpheus API and the bastion through it.
* **Control plane and worker instances** in the group, cloud and network you picked, booting from the layout's image, plus dedicated etcd instances for a kubeadm cluster with external etcd.

Ankra creates **no network**: the instances attach to your existing Morpheus network and get their addresses from its DHCP, and routing and internet egress follow that network's own gateway. There is no cloud controller manager: `LoadBalancer` Services are not provisioned, so expose workloads with `NodePort` Services, an ingress controller, or a load balancer you deploy yourself. The [Morpheus Reference](/reference/morpheus#architecture) has the full layout.

## Morpheus specifics

* **Numeric IDs everywhere.** Groups, clouds, networks, layouts, virtual images and service plans are the numeric IDs from your appliance; node groups are sized by a numeric `plan_id`.
* **Resizing a node group** moves it to a larger service plan: each instance is powered off, resized and powered on again, with brief downtime for its workloads. Plans only grow; for smaller nodes, create a new group and delete the old one.
* **Restarting a single node is not available** for Morpheus clusters. The bastion is resized from the dashboard or the API; `ankra cluster morpheus nodes list|get` lists and inspects the nodes.
* **A stop** captures the cluster's etcd state through the credential's jump host before the instances are deleted. **Terminating** deletes every instance Ankra created (bastion, control planes, workers and etcd instances) and leaves your Morpheus groups, clouds, networks and virtual images untouched.
* **No cost estimate in the create wizard.** Cloud Cost prices running clusters once you set a [rate card](/platform/cloud-cost#private-capacity-rate-cards) on the Morpheus credential; until then they show as not priced.

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `morpheus`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [The bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Morpheus API unreachable from Ankra | Attach an [SSH jumphost](#hybrid-connectivity-ssh-jumphost) to the credential - Ankra tunnels API calls and node SSH through it |
| TLS certificate errors (self-signed) | Enable the **TLS insecure** toggle (`tls_insecure`) on the Morpheus credential |
| Instances never get an IP address | The selected network must provide DHCP - Ankra does not manage IP allocation. Verify a DHCP server answers on that network |
| Cluster stuck in provisioning | Check that the access token can provision into the selected group and cloud, and that the cloud has free capacity |
| Instance creation fails | Verify the virtual image is a Linux cloud image available to the selected cloud, and the service plan is valid for it |
| LoadBalancer service stuck in `Pending` | Morpheus clusters have no cloud controller manager - use `NodePort`, ingress, or your own load balancer |
| No cost estimate in the wizard, or cluster **not priced** in Cloud Cost | Expected in the wizard. For Cloud Cost, set a [rate card](/platform/cloud-cost#private-capacity-rate-cards) on the Morpheus credential |


# Move a team to Ankra CI
Source: https://docs.ankra.ai/guides/move-to-ankra-ci

A rollout plan for moving an organisation's CI from GitHub Actions or GitLab CI to Ankra Pipelines: set up once, prove it on a pilot repository, run both side by side, switch the required check and repeat - with a mapping from GitHub Actions concepts to Ankra.

[Get started with Ankra CI](/get-started/ankra-ci) moves one repository. This page is the plan for the rest of them: what to set up once for the whole organisation, how to prove Ankra CI on one repository before you depend on it, and the checklist to repeat for every repository after that.

## The plan at a glance

```mermaid theme={null}
flowchart LR
    Setup[Set up once: cluster, workers, capacity] --> Pilot[Pilot one repository]
    Pilot --> Side[Run both side by side]
    Side --> Switch[Switch the required check, remove the old workflow]
    Switch --> Repeat[Repeat per repository]
```

Most teams move a repository in an afternoon once the organisation is set up. The side-by-side period is what takes calendar time - give it at least a few days of normal pull requests, so you see the flaky tests and the slow ones before anyone depends on the new check.

## 1. Set up once for the organisation

These are organisation-wide and an administrator does them once. Steps 1 and 2 of [Get started with Ankra CI](/get-started/ankra-ci) walk through the first two.

* **Choose the pipeline cluster** - `ankra org ci-settings set --cluster <cluster-name>`, or **Settings → Pipelines → Pipeline cluster**.
* **Give its agent pipeline workers** - `ankra cluster agent ci set --workers <n> --cluster <cluster-name>`. Each worker runs one step at a time. Size it to how many steps you expect at once across all your repositories at a busy moment, and raise it later - the run page says when a step waited for a free worker.
* **Let the cluster grow under load.** Steps reserve the CPU and memory they ask for, so a busy hour needs nodes, not just workers. Turn on autoscaling for the node group your steps run on, so the cluster adds a node rather than queueing steps. When a step is waiting, the run says why - a provider quota, a node group at its maximum, or a node scaling up - and what to do about it.
* **Decide your image policy.** By default a step may use any image. To limit steps to images you trust, set `ankra org ci-settings set --allowed-image-prefix <prefix>` once per registry or path you allow.
* **Check the image gate.** `ankra org ci-settings get` shows the gate policy that decides which scan findings block a publish. The default, `app`, blocks fixable critical and high findings in your own dependencies.

`ankra org ci-settings get` shows all of this, and how many CI slots are in use right now.

> [!TIP]
>
> When one cluster is no longer enough, add another to the organisation's CI pool and runs go to the least loaded one: `ankra org ci-settings pool add <cluster-name>`, CLI v0.28.0 or later.

## 2. Pilot one repository

Pick a repository that is active enough to give you real pull requests every day, has tests that mostly pass today, and is not the one every release depends on. Then get its pipeline the fastest way that fits:

| The repository today | The fastest way to a pipeline |
| - | - |
| An Ankra application that builds with a GitHub Actions workflow | `ankra application pipeline convert <application-id> --keep-workflows` converts the workflow and opens a pull request with `.ankra/pipeline.yaml`. See [Migrate from GitHub Actions](/guides/migrate-from-github-actions). |
| Any repository with GitHub Actions, GitLab CI, Bitbucket Pipelines or CircleCI | Ask Ankra AI in the portal chat to convert the workflow files, then review every note it leaves. See [Convert with Ankra AI](/guides/migrate-from-github-actions#convert-with-ankra-ai). |
| A repository with simple test commands | Copy a [starter pipeline](/guides/ankra-ci-starter-pipelines) and change the test command. |

A converted pipeline is a starting point a person reviews. Anything the converter cannot map is either a stage that fails with an explanation, or a note naming the step it came from - never dropped silently.

## 3. Run both side by side

Keep the old CI running while the Ankra pipeline runs on the same pull requests, and leave the old check as the required one for now. Compare:

* **Does the Ankra pipeline fail where the old CI passes?** Usually it is one of the [three rules every step follows](/guides/ankra-ci-starter-pipelines#three-rules-every-step-follows) - a tool writing into `HOME`, a step that needs the network, or a missing image tool that the old runner had preinstalled. [Troubleshooting](/guides/ankra-ci-troubleshooting) has the fixes.
* **Is it fast enough?** Add [caches](/guides/ankra-ci-starter-pipelines#make-it-faster-with-caches) for your package manager and give heavy steps the CPU and memory they need. `ankra pipeline get <run-id>` prints, per step, how long it waited for a slot, how long its pod took to start, and its memory and CPU peaks against what it asked for - so you can see whether to ask for more or less.
* **Are the secrets right?** Move each secret into Ankra once and declare it in the pipeline - see [Use a secret in a step](/guides/ankra-ci-starter-pipelines#use-a-secret-in-a-step).

> [!WARNING]
>
> **Publish an image from one system at a time.** While both run, let only one of them push images and deploy - otherwise two builds of the same commit race for the same tag. Leave publishing in the old CI during the comparison, or leave the `publish` stage out of the Ankra pipeline until you switch.

## 4. Switch over

When the Ankra pipeline has been green on a week of pull requests, or as long as your team needs to trust it:

1. **Approve the pipeline on the default branch** if it declares secrets, caches, resources, services or other protected settings, so every run gets them. `ankra pipeline validate` lists any protected setting that is not approved yet.
2. **Make `Ankra pipeline` the required check.** On GitHub that is the branch protection rule or ruleset on your default branch. Remove the old CI's checks from the required list in the same change.
3. **Remove the old workflow** - delete `.github/workflows/*.yml` or `.gitlab-ci.yml` - so every commit is built once.
4. **Add publishing back** to the Ankra pipeline if you held it out, with the `build`, `scan`, `gate` and `publish` stages from [Build, scan and publish an image](/guides/ankra-ci-starter-pipelines#build-scan-and-publish-an-image).
5. **Tell the team what changed** - below.

## 5. Repeat for each repository

Once the organisation is set up, each repository needs only this:

* [ ] Repository connected to Ankra Pipelines
* [ ] `.ankra/pipeline.yaml` committed, validated and approved
* [ ] Green on several pull requests while the old CI still runs
* [ ] `Ankra pipeline` required, old CI checks no longer required
* [ ] Old workflow files removed
* [ ] Publishing and deploys come from the Ankra pipeline

## What changes for developers

Share this with the team when a repository switches:

* **The check is called `Ankra pipeline`.** It has a table of steps and a link to the run in Ankra. GitHub's **Re-run** button on it starts a new run, and **Cancel** stops one.
* **Logs and test results are in Ankra.** Open the run from the check, or use the CLI: `ankra pipeline logs <run-id> --step <step> --follow`.
* **Re-run only what failed** with **Re-run failed steps** on the run page, or `ankra pipeline rerun <run-id> --failed-only`.
* **Pipeline changes in a pull request run on that pull request.** Changing a stage or a script takes effect immediately. Adding a secret, a cache, more memory or a service takes effect after it is merged and an administrator approves it.

## GitHub Actions to Ankra CI

| GitHub Actions | Ankra CI |
| - | - |
| `.github/workflows/*.yml`, one file per workflow | One `.ankra/pipeline.yaml` per repository |
| `on: push`, `pull_request` | `on.push`, `on.pull_request`, with `branches` and `paths` |
| `on: workflow_dispatch` with `inputs` | `on.manual` with `inputs` |
| `on: schedule` | `on.schedule`, plus `ankra pipeline schedules create` |
| `jobs.<id>` | A stage in `stages`, with a `kind` |
| `runs-on` | Your pipeline cluster. `runs_on.node_selector` places a step on particular nodes |
| `actions/checkout` | A `kind: checkout` stage |
| `actions/setup-node`, `setup-python`, `setup-go` | The stage's `image`, for example `node:24-alpine` |
| `steps[].run` | The stage's `run` script, run with `sh -eu` |
| Marketplace actions (`uses:`) | A `run` script that does the same thing; the converter writes these for common actions |
| `needs` | `needs` |
| `if:` | `if:`, with `success()`, `failure()`, `always()` and `cancelled()` |
| `strategy.matrix` | `matrix`, with `include` and `exclude` |
| `services` | A top-level `services` block, named on each stage that uses it |
| `env` | `env` on a stage, or `defaults.env` |
| `secrets.X` | A declared `secrets` entry, delivered as a file under `/run/agent-secrets/` |
| `actions/cache` | A stage's `cache` block |
| `actions/upload-artifact` | A stage's `artifacts` list |
| JUnit or test report actions | A stage's `test_results` list (`junit`, `go-test`, `pytest`, `playwright`) |
| `docker/build-push-action` | The `build`, `scan`, `gate` and `publish` stages |
| `concurrency`, `cancel-in-progress` | `concurrency.group`, `concurrency.cancel_in_progress` |
| `timeout-minutes` | A stage's `timeout`, such as `"45m"` |
| `permissions` | `permissions`, approved by an administrator |

GitLab CI maps the same way: each job becomes a stage, `image` and `script` become the stage's `image` and `run`, `needs` stays `needs`, `services` becomes the `services` block, and `rules` become the stage's `when` and `if`. [Migrate from GitHub Actions](/guides/migrate-from-github-actions) covers what the converter does with each format.

## Related

* [Get started with Ankra CI](/get-started/ankra-ci)
* [Starter pipelines](/guides/ankra-ci-starter-pipelines)
* [Troubleshooting](/guides/ankra-ci-troubleshooting)
* [Organisation CI settings](/guides/ankra-pipelines#organisation-ci-settings) and [capacity](/guides/ankra-pipelines#capacity-and-concurrency)


# Node Group Cloud-init User Data
Source: https://docs.ankra.ai/guides/node-group-user-data

Attach a cloud-init document to an OVH node group so every node it creates, including replacements, is provisioned the same way.

A node group can carry a cloud-init user-data document. Ankra applies it verbatim at first boot on every instance the group ever creates - the nodes you add today and every replacement the group makes later.

That last part is the reason the field exists. Anything you configure by hand after a node boots is lost the first time that node is replaced, so a layout that must survive replacement has to come from the provisioning template rather than from a one-off SSH session. Disk partitioning is the common case: you cannot repartition a running root disk, so the work has to happen before the root filesystem is grown.

> [!NOTE]
>
> User data is currently supported on **OVH** clusters only. Other providers refuse the field with `User data is not supported for <provider> clusters`.

## Prerequisites

* An OVH cluster in your organisation.
* Permission to operate the cluster (`clusters.operate`).
* The Ankra CLI for `--user-data-file` (the version marker below says which release); the API accepts the field regardless of CLI version.

> [!WARNING]
>
> User data is set when a node group is **created**, and cannot be edited afterwards. To change the document, create a new node group with the new user data and move the workload over. Existing nodes are never re-provisioned by a user-data change.

## Attach a document

Write the cloud-init document to a file and pass it with `--user-data-file`. It is a file flag rather than a string flag because the document is normally multi-KB YAML, which does not survive shell quoting well.

```bash CLI theme={null}
ankra cluster node-group add <cluster-id> \
  --name db-par-a \
  --instance-type b2-30 \
  --count 2 \
  --user-data-file ./carve-disk.yaml
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/ovh/<cluster-id>/node-groups \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "name": "db-par-a",
  "instance_type": "b2-30",
  "count": 2,
  "user_data": "#cloud-config\nbootcmd:\n  - echo hello\n"
}
JSON
```

The document is capped at 65535 bytes. The CLI refuses anything larger before sending the request.

Ankra sends no cloud-init of its own to these instances, so your document is not merged with a platform-provided one. What you write is what runs.

## Read the first-boot output

A provisioning script that fails leaves a node that looks healthy to the cloud provider and wrong to you. Read the node's own cloud-init output rather than inferring the failure from symptoms:

```bash CLI theme={null}
ankra cluster ovh nodes cloud-init-log <cluster-id> <node-id>
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/ovh/<cluster-id>/nodes/<node-id>/cloud-init-log \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

This returns `cloud-init status --long` plus the tail of `/var/log/cloud-init-output.log`, fetched over the platform's own bastion lane - you do not need the cluster's SSH key. It runs as a tracked read-only operation; if the fetch outruns the platform's wait it hands back an operation id to poll with `ankra cluster operations list`. Calling it again while a fetch is in flight attaches to that fetch instead of starting a second one.

The same command is available for Hetzner, UpCloud, DigitalOcean and Scaleway clusters.

## Carving a partition at provision time

The motivating case is encryption at rest. LUKS needs a real block device, but on single-disk flavors the only NVMe device is also the boot disk, and the image grows the root filesystem across the whole device - leaving no free partition to encrypt. Falling back to LUKS on a loopback file works but costs materially more overhead than LUKS on a real partition.

The fix is to carve the disk in `bootcmd`, before the root filesystem is grown.

### Leave growpart enabled

> [!WARNING]
>
> Do not set `growpart: mode: off`. Leave growpart enabled and do the carving in `bootcmd`.

This ordering is a safety property, not a style preference. `bootcmd` runs before the `growpart` module, so:

* **When your carve succeeds**, it has already consumed the tail of the disk. growpart finds no free space to expand into and does nothing. Your layout stands.
* **When your carve fails**, growpart still runs and restores an ordinary full-disk root. You get a normal, usable node and a failed script to read in the log.

Disabling growpart removes the second case. A bug in your script then leaves root at the image's own size - a few GiB - and the node is effectively unusable rather than merely unmodified.

### Grow root to its cap before appending

Append the new partitions **after** resizing root to the size you want it capped at, not before.

If you append partitions directly after a small image root, they start immediately behind it, growpart has nowhere to expand into, and root stays at the image size. That failure looks exactly like the bricked node above, except it happens on the path where every command succeeded.

### Tooling present in the image

* `sfdisk` is available. `sgdisk` and `parted` are **not** - do not assume them.
* `sfdisk --append` refuses to run without `--force`.
* Address the resulting partitions by GPT partlabel (`/dev/disk/by-partlabel/<name>`), never by device path. Nodes are replaced, and a partlabel is the part of the layout that reliably comes back with them.

### Example

> [!WARNING]
>
> Sizes, the device name and the filesystem layout below are illustrative. Validate any partitioning document on a scratch node group before pointing it at a group you care about, and read the cloud-init log of the first node it creates.

```yaml theme={null}
#cloud-config
bootcmd:
  - |
    set -eux
    disk=/dev/nvme0n1
    # Idempotent: bootcmd runs on every boot, not only the first.
    if [ ! -e /dev/disk/by-partlabel/pgdata ]; then
      # 1. Cap root at 64 GiB so growpart has a boundary to stop at.
      echo ', 64GiB' | sfdisk --no-reread -N 1 "$disk"
      # 2. Append the data partitions into the tail growpart would have taken.
      printf 'size=200GiB, name=pgdata\nsize=80GiB, name=pgwal\n' \
        | sfdisk --append --force "$disk"
      partx -u "$disk"
    fi
```

With that in place, `/dev/disk/by-partlabel/pgdata` and `/dev/disk/by-partlabel/pgwal` are real partitions that LUKS can take directly, and root settles at its 64 GiB cap.

## Verify

**1. Check cloud-init finished**

Run `ankra cluster ovh nodes cloud-init-log <cluster-id> <node-id>` against the first node the group creates. `cloud-init status --long` should report `status: done`. Anything else, read the output tail below it.

**2. Confirm the layout**

The partitions you carved should be addressable by partlabel, and root should be at the size you capped it to and not the image default.

**3. Replace one node**

Delete a node and let the group recreate it, then repeat the two checks. This is the property the field exists for, so it is worth confirming once per document rather than assuming it.

## Troubleshooting

> [accordion] The node joined but the partitions are missing
>
> Read the cloud-init log. A failed `bootcmd` does not stop the node from joining the cluster: growpart restores a normal root and the node comes up looking healthy. That is the designed fallback, and the log is where the failure is recorded.

> [accordion] Root is only a few GiB
>
> Either growpart was disabled, or partitions were appended before root was resized so growpart had no free space to expand into. Both are covered above; fix the document and create a new node group, since user data cannot be edited on an existing one.

> [accordion] sfdisk did nothing and reported no error
>
> `sfdisk --append` needs `--force`. Without it the command declines to modify the table.

> [accordion] The request was refused
>
> `User data is not supported for <provider> clusters` means the cluster is not OVH. A size complaint means the document is over the 65535-byte cap.


# Notification routing
Source: https://docs.ankra.ai/guides/notification-routing

How Ankra decides which destinations a notification reaches, and why a destination is never notified twice

A notification can reach a destination by two independent paths:

* **An alert's own destinations.** On an alert rule, **Notifications** → **Destinations** attaches destinations directly. When the alert fires, Ankra delivers to every destination on that list.
* **A notification route.** Under **Alerting** → **Destinations** → **Routing rules**, a rule in one project or organisation-wide matches notifications by kind, severity, cluster, and source, and sends them to one destination. Routes cover every notification kind, not only alerts.

Both paths can point at the same destination at the same time. That is a supported configuration, and it delivers once.

```mermaid theme={null}
flowchart TD
    Firing[Alert fires] --> AlertPath[The alert's own destinations]
    Firing --> Inbox[Notification recorded in the inbox]
    Inbox --> Routes[Notification routes are evaluated]
    Routes --> Dedupe{Already covered by the alert's own destinations?}
    Dedupe -->|Yes| Dropped[Route delivery dropped]
    Dedupe -->|No| RoutePath[Route delivers]
    AlertPath --> Teams[Destination receives one message]
    RoutePath --> Teams
```

## One delivery per destination

**A notification is delivered at most once per destination.** This is a guarantee, not a timing accident.

Before it queues anything, Ankra subtracts the destinations the alert's own list already covers from the destinations the routing rules resolved. A destination that both paths point at is queued once, by the alert.

Two consequences follow, and both matter when you are deciding how to configure routing:

* **You do not need to detach destinations from your alerts** to avoid duplicates, and you do not need to delete the routing rule either. Keeping both is safe.
* **The subtraction only runs one way.** Routing rules are netted against the alert's destinations. The alert's own destinations are never netted against anything, so no routing rule - include or exclude, at any priority - can add to them or take them away.

The netting happens before anything is queued, so a de-duplicated rule never produces a delivery at all. The one case where a destination can see the same firing twice is if the alert's trigger record has already been removed by the time routing runs: Ankra then cannot tell what the alert covered, and delivers rather than risk staying silent. It errs towards a duplicate, never towards a missed alert.

## How a rule matches

A routing rule sets any combination of four filters. Every filter it sets must match; a filter it leaves empty matches everything.

| Filter | Empty means | Matches when |
| - | - | - |
| Kind | All kinds | The notification's kind is in the rule's kind list (or, for a negated list, is not in it) |
| Severity | All severities | The notification's severity is exactly the rule's severity |
| Cluster | All clusters | The notification is about that cluster |
| Source | All sources | The notification's source id is exactly the rule's source id - for alert firings, the alert id |

A rule with no filters at all matches every notification. Disabled rules are skipped entirely.

## Routes per project

On top of those filters, a rule is either in one [project](/concepts/projects) or organisation-wide:

* **In a project** - it matches only notifications of that project, never an organisation-level one such as billing. A notification's project is the project of the thing it is about (its ticket, application, pipeline run, repository, automation, workspace, incident, environment or cluster), read when it is delivered, so a moved cluster's notifications follow it.
* **Organisation-wide** - it matches every project's notifications and the organisation's own.

You choose **This project** or **Whole organisation** when you create a rule. A rule created without a choice, including older ones, is in its creator's project at the time, and delivers only that project's notifications. A project rule also counts as more specific in the [evaluation order](#evaluation-order).

### Example: one channel per project

An organisation has projects `core` and `tools`, and wants each project's notifications in its own channel, `#ankra-core` and `#ankra-tools`, on Slack or Teams.

1. Add a destination for each channel under **Alerting** → **Destinations**.
2. In project `core`, create one rule with no filters, **This project**, sending to `#ankra-core`. Do the same in `tools` for `#ankra-tools`.
3. For AI board threads (plan sign-offs, approvals and decisions), bind each project's channel under the AI board's **Project channels** setting. See [Project channels](/platform/ai-board#project-channels).

Anything organisation-level, and any project without a rule, still reaches the organisation's own routes and the [home channel](#the-home-channel-fallback).

> [!NOTE]
>
> Two things do not follow the project yet. When you ask the Ankra bot something in `#ankra-tools`, it answers from your default project. Remediation approval cards still go to the organisation's single Slack remediation destination.

## Kinds: one, several, or everything except

**Kind** takes a list, and the list can be inverted:

* **All kinds** - no kind filter.
* **A list of kinds** - "Operation failed and Reconciliation failing, nothing else" is one rule, not two.
* **All except a list of kinds** - switch the rule to **All kinds except** and name the kinds to leave out. "Route everything except Alert firing to this channel, because alerts already have their own destinations" is one rule, not ten.

Negating a list is not the same as an Exclude rule. A negated list changes which notifications the rule *matches*; Exclude changes what the rule *does* when it matches. See the next section.

> [!NOTE]
>
> The API accepts both spellings. `kinds` is the list, and `kinds_negated: true` inverts it. The older single-value `kind` field still works, and a rule whose list is exactly one kind continues to report that kind in `kind`, so existing API clients and scripts keep working unchanged.

## Opt-in kinds

A few notification kinds are **opt-in**: a rule only matches them if it *names* them. "All kinds" does not cover an opt-in kind, and neither does "All kinds except ...", because that spelling says what a rule skips rather than what it covers. The home channel fallback never picks one up either, whatever its severity.

These kinds report routine, successful work rather than something that needs attention, and they can fire often. Leaving them out of the catch-all rules an organisation already has is what keeps a channel worth reading.

| Kind | What it reports |
| - | - |
| `gitops_repository_write` | Ankra committed to your GitOps repository: the reconciler converging drift, or a save in the portal, the API, the CLI, chat, or a cloud provider publish. The notification names the repository, the branch, the commit, who or what wrote, and the files it re-encrypted, wrote and removed. |

To subscribe, create a rule that names the kind:

```bash CLI theme={null}
ankra alerts routes create --destination-id <destination-id> --kinds gitops_repository_write
ankra alerts routes preview --kind gitops_repository_write --severity info --cluster-id <cluster-id>
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/org/notifications/routes \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"kinds": ["gitops_repository_write"], "destination_id": "<destination-id>"}'
```

Add a `cluster_id` filter to follow one cluster's repository rather than every cluster in the organisation.

> [!NOTE]
>
> The **Kind** picker on the Routing rules page offers a shorter list than the API accepts. A rule for a kind the picker does not offer is created through the CLI, the API, or Ankra chat, and then reads and edits normally on that page.

## Cluster access kinds

Two kinds report changes to who can reach your clusters with `kubectl`. Both are `warning` severity and are **not** opt-in: they reach catch-all rules ("All kinds") and, when no rule matches, the [home channel](#the-home-channel-fallback), with no configuration.

| Kind | What it reports |
| - | - |
| `cluster_access_policy_changed` | Every accepted change to the [organisation access policy](/guides/cluster-access#organisation-access-policy): who changed it, and the policy before and after. |
| `cluster_access_elevated_grant` | Every [break-glass elevation](/guides/cluster-access#break-glass-elevation), at any role, and every `admin` or `cluster-admin` grant, including extensions of one. |

To send them somewhere specific, such as a security channel, create a rule that names them:

```bash theme={null}
ankra alerts routes create --destination-id <destination-id> --kinds cluster_access_policy_changed,cluster_access_elevated_grant
```

## Evaluation order

Rules are evaluated in ascending **priority** - 10 runs before 100. Rules sharing a priority are broken by **specificity**: the rule that names more values runs first.

Specificity counts the filters that name a value:

| Filter | Adds specificity |
| - | - |
| A kind, or a list of kinds | Yes |
| **All kinds except …** | No - it names what the rule skips, not what it covers |
| Severity | Yes |
| Cluster | Yes |
| Source | Yes |
| Project | Yes |

The walk keeps a running set of destinations, starting empty. Each matching rule adds to it or removes from it, and the set that survives is what gets delivered.

## Include and Exclude

| Mode | Effect when the rule matches |
| - | - |
| Include | Adds its destination to the running set |
| Exclude | Removes its destination from the running set - **if an earlier rule put it there** |

**Exclude is not mute.** An Exclude rule can only take back what a higher-precedence rule in the same walk already added. An Exclude rule that runs before anything has added its destination removes nothing.

**Exclude never touches an alert's own destinations.** The walk described here resolves routing rules only. An alert's own destinations are delivered by the alert itself and are not in the running set, so no Exclude rule can remove them - whatever its priority, and whether or not it stops the walk.

Worked example, for a rule at priority 10 that matches everything, is set to Exclude, and has **Stop on match** on:

| What happens | Result |
| - | - |
| The walk starts, running set is empty | - |
| The Exclude rule matches and tries to remove its destination | Nothing to remove; the set stays empty |
| Stop on match halts the walk | Lower-priority Include rules are never evaluated |
| Routing rules deliver | Nothing |
| The alert's own destinations deliver | Unaffected - still delivered |
| The home channel fires | No - a rule matched, so this is a deliberate mute, not an unhandled event |

So that rule is a global mute for route-driven delivery, and only for route-driven delivery. If you want to silence an alert entirely, remove its destinations on the alert itself or disable the alert.

## Stop on match

**Stop on match** halts the walk at the first matching rule that carries it. Rules with a lower priority are never evaluated, whatever their mode. Combined with priority it gives you a first-match-wins rule: put the specific rule at a low priority with Stop on match, and let the catch-all sit at priority 100.

Stop on match does not by itself deliver or suppress anything - it only ends the walk. The running set at that moment is what gets delivered.

## The home channel fallback

If your organisation has a [home channel](/guides/webhooks#home-channel) and a critical or warning notification matches **no** routing rule at all, Ankra posts it to the home channel so nothing important is lost silently.

The fallback is deliberately narrow:

* It fires only when no rule matched. A rule that matched and netted the destinations to nothing is a mute, and the home channel stays quiet.
* It never fires for informational notifications.
* It never fires for an [opt-in kind](#opt-in-kinds), which reaches a destination only through a rule that names it.
* It never fires for an alert firing that already delivers to the alert's own destinations.

## Preview what would be delivered

Rather than reasoning through the walk, ask Ankra. **Preview** on the Routing rules page evaluates a hypothetical notification against your organisation's rules and lists the destinations it would reach, the destinations it would not, and the reason for each - including which rules matched, which were skipped by a Stop on match, and which route deliveries were dropped because an alert's own destination already covers them.

The preview is a dry run. It delivers nothing and changes nothing.

The preview reads the notification's project from its cluster or application, the way delivery does. In the API you can name one with `project_id` instead, and the response says which project it evaluated (`null` for the organisation).

```bash CLI theme={null}
ankra alerts routes preview --kind alert_trigger_fired --severity critical
ankra alerts routes preview --kind alert_trigger_fired --severity critical --alert-id <alert-id>
ankra alerts routes preview --kind gitops_sync_failed --severity warning --cluster-id <cluster-id> -o json
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/org/notifications/routes/preview \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"kind": "alert_trigger_fired", "severity": "critical", "alert_id": "<alert-id>"}'
```

Pass `--alert-id` (or `alert_id`) whenever you are previewing an alert firing: without it the preview cannot know which destinations the alert itself covers, and will show the route deliveries that de-duplication would drop.

## Managing rules from the CLI

```bash CLI theme={null}
ankra alerts routes list
ankra alerts routes create --destination-id <destination-id> --kinds execution_failed,resource_reconcile_failed
ankra alerts routes create --destination-id <destination-id> --exclude-kinds alert_trigger_fired
ankra alerts routes update <route-id> --priority 10 --stop-on-match
ankra alerts routes preview --kind execution_failed --severity critical
ankra alerts routes delete <route-id>
```

`--kinds` takes a comma-separated list and `--exclude-kinds` takes the same list negated; the two are mutually exclusive. The single-value `--kind` flag still works and is equivalent to `--kinds` with one entry.

## Related

> [card] [Alerts](/guides/alerts)
>
> Alert rules, conditions, and the destinations an alert notifies directly.

> [card] [Webhooks](/guides/webhooks)
>
> Destinations, payload templates, and the organisation home channel.


# Bring Your Own OpenRouter API Key
Source: https://docs.ankra.ai/guides/openrouter-api-key

Connect your organisation's OpenRouter account so Ankra's AI runs on your own key - unlimited usage with the same default models and failover.

With your organisation's own OpenRouter API key, Ankra serves the same default models and the same automatic failover chain through **your** OpenRouter account - including background and autonomous AI sessions. Usage on your own key never draws on the [free monthly allowance](/platform/ai-provider#usage-and-the-free-allowance), so AI features are never paused by `AI_ALLOWANCE_EXHAUSTED`.

## Prerequisites

* You are an organisation admin with the `ai.manage` permission.
* An OpenRouter account at [openrouter.ai](https://openrouter.ai) with credits available.

## Add the Key

**1. Create an API key at OpenRouter**

Sign in at [openrouter.ai](https://openrouter.ai) and create a new API key from the **Keys** page. Copy the key - it starts with `sk-or-`.

> [!TIP]
>
> Set a credit limit on the key in OpenRouter. It caps what Ankra can spend through it, independently of Ankra's own [daily spend cap](/platform/ai-provider#daily-spend-cap-vs-monthly-allowance).

**2. Save the key in Ankra**

```bash theme={null}
ankra ai openrouter set
```

The command prompts for the key without echoing it; you can also pipe it on stdin or pass `--api-key`. Ankra validates the key live against OpenRouter before storing it. Two errors can come back:

* **Invalid key** - the key was rejected by OpenRouter. Check you copied the full key and that it has not been revoked.
* **No remaining credits** - the key is valid but its OpenRouter account has no credits left. Top up at OpenRouter, then save again.

**3. Activate the provider**

```bash theme={null}
ankra ai provider openrouter
```

From this point AI usage - interactive and background - is billed to your OpenRouter account.

**4. Verify**

`ankra ai status` shows the active provider and a masked preview of the stored key (for example `sk-or-...wxyz`). Open the AI Assistant (`⌘J` / `Ctrl+J`) and send a message - the run appears in your OpenRouter activity.

### In the portal

Go to **AI** → **Settings** → **Models**, expand **OpenRouter (your own key)**, paste the `sk-or-...` key and save. The same validation runs, and the row then shows the masked preview. If you also hold an Anthropic key, **Prefer this credential** decides which of the two runs the calls both could serve.

## Rotating the Key

Save a new key over the old one - `ankra ai openrouter set` again, or the same row in the portal. The new key goes through the same live validation, and the old one is replaced on save - no downtime and no provider switch needed.

## Removing the Key

Removing the key (`ankra ai openrouter remove`, or **Remove** in the portal) switches the organisation back to the Ankra-managed provider, and the [free monthly allowance](/platform/ai-provider#usage-and-the-free-allowance) rules apply again. If the allowance is already exhausted for the month, AI features pause until it resets or you add a key again.

## Security

* The key is stored **only in Ankra's secret store** (HashiCorp Vault or OpenBao) - never in the database.
* It is never shown again after saving; Ankra only ever displays a masked preview like `sk-or-...wxyz`.
* Viewing the preview, saving, and removing the key all require the `ai.manage` permission.
* The key is never included in exports.

## Related Pages

* [Models and Cost](/platform/ai-provider) - every provider mode, the default models, and what the free allowance covers


# Operate an Ankra Managed Cluster
Source: https://docs.ankra.ai/guides/operate-ankra-managed-clusters

Day-2 tasks for clusters Ankra builds on your own account - node groups, control plane, restarts, the bastion, Kubernetes upgrades, stop and start, and teardown - with the commands for every provider.

Your cluster is running and now it needs to change: more workers, a bigger instance type, a new Kubernetes version, a pause overnight, or a clean teardown. This page covers those tasks for every cluster Ankra builds on your own account - the **Ankra Managed** clusters in the create dialog, on Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, AWS EC2, Ankra Cloud, Proxmox VE and HPE Morpheus. Where a provider behaves differently, the table in each section says so, and the provider's own guide carries the details.

> [!NOTE]
>
> Clusters whose control plane your cloud runs (EKS, GKE, AKS, DOKS, UKS, OVHcloud MKS, Kapsule) are **Cloud Managed**; their node pools, upgrades and deletion are on [Managed Kubernetes](/guides/managed-kubernetes#day-2-operations).

## Before you start

* The cluster shows **Online** and no operation is running on it. Day-2 changes are queued one at a time; follow them under **Operations** or with `ankra cluster operations list`.
* In the dashboard, most controls live under **Nodes** in the cluster sidebar (tabs **Node groups**, **Control plane**, **Bastion & VMs**) and under **Settings → General**. [Nodes](/platform/cluster-nodes) describes every control on those tabs.
* On the CLI, most commands find the provider from the cluster, so they are the same everywhere. The rest take the provider name: `hetzner`, `ovh`, `upcloud`, `digitalocean`, `scaleway`, `aws`, `proxmox` or `morpheus`. Ankra Cloud clusters are operated from the dashboard and the API; the released CLI has no Ankra Cloud commands yet.
* Every command has an API equivalent under `/api/v1/clusters/{provider}/{cluster_id}/...` - see the API reference. Writes answer `202 Accepted` and run in the background; pass `--wait` on the CLI to block until one finishes.

| Provider | CLI name | Restart a node | Resize the bastion | Control plane |
| - | - | - | - | - |
| Hetzner | `hetzner` | CLI | CLI | CLI |
| OVHcloud | `ovh` | CLI | CLI | CLI |
| UpCloud | `upcloud` | CLI | CLI | CLI |
| DigitalOcean | `digitalocean` | CLI | CLI | CLI |
| Scaleway (Closed Beta) | `scaleway` | CLI | Not applicable - the Public Gateway runs the bastion | CLI |
| AWS EC2 | `aws` | CLI | Dashboard or API | CLI |
| Proxmox VE | `proxmox` | CLI | Dashboard or API | CLI |
| HPE Morpheus (Closed Beta) | `morpheus` | Not available | Dashboard or API | CLI |
| Ankra Cloud (Closed Beta) | - | Dashboard or API | Dashboard or API | Dashboard or API |

***

## Node groups

A node group is a set of workers with one instance type, a count, and optional labels and taints. Each group scales, changes type and carries its labels independently. A group holds 0 to 100 nodes; scaling a group to 0 keeps its definition and removes its servers.

**In the dashboard:** open **Nodes → Node groups**. Each card has the group's controls, **Add node group** opens the size picker with live prices, and **Max out** sizes a group to what your cloud account still has room for.

**On the CLI:**

```bash theme={null}
ankra cluster node-group list <cluster>
ankra cluster node-group add <cluster> --name workers-large --instance-type <instance-type> --count 2
ankra cluster node-group scale <cluster> workers-large 4
ankra cluster node-group upgrade <cluster> workers-large <larger-instance-type>
ankra cluster node-group labels <cluster> workers-large --labels env=production,tier=backend
ankra cluster node-group taints <cluster> workers-large --taints dedicated=ml:NoSchedule
ankra cluster node-group delete <cluster> workers-large
```

* **Instance type changes go one way.** A group moves to an equal or larger type only; to get smaller nodes, add a new group with the smaller type and delete the old one. How the change is applied depends on the provider - most power each node off, resize it and power it on again, while AWS replaces each node - so check the provider guide before you resize a group that runs stateful workloads.
* **Labels and taints** apply to every node in the group. `--clear` removes them all; a taint without an effect gets `NoSchedule`.
* **Removing nodes drains them first.** A scale-down, a group delete and a replacement drain each node, honouring PodDisruptionBudgets.
* **Deleting a group removes all its servers.** Workloads on them are evicted.
* **Zones.** On OVHcloud 3-AZ regions (`--availability-zone`), UpCloud zone pools (`--zone`) and multi-zone AWS clusters, a group can be pinned to one zone - do that for groups that run zonal storage.
* **Autoscaling and first-boot scripts.** Set a group's autoscaling range with `ankra cluster node-group autoscaling set` - see [Cluster Autoscaling](/guides/cluster-autoscaling). OVHcloud groups can carry a cloud-init document - see [Node Group Cloud-init User Data](/guides/node-group-user-data).
* **A stopped cluster.** Adding or changing a node group on a stopped cluster brings its infrastructure back first, so the cluster comes online. Use **Start cluster** when you want the full saved topology back.

### Legacy worker scaling

Clusters also keep a single default worker pool that predates node groups. `ankra cluster scale <cluster> <count>` sets its size, and `ankra cluster <provider> workers <cluster>` shows it. Prefer node groups for anything new.

***

## Control plane

**In the dashboard:** **Nodes → Control plane** shows the controller count and instance type, and says for each change whether it runs live or offline, or why it is refused right now.

* **Growing the count is live.** Going from 1 to 3 controllers (3 to 5 on Proxmox VE) provisions the new controllers and joins them to the running cluster.
* **Reducing the count is offline.** Stop the cluster (its state is kept and restored on start), apply the change, then start it.
* **The instance type** changes in one of three ways, described below. `control-plane get` and the **Control plane** tab say which one applies to your cluster right now.
* A cluster spread across several zones or hosts keeps at least three controllers.

```bash theme={null}
ankra cluster <provider> control-plane get <cluster>
ankra cluster <provider> control-plane set-count <cluster> 3
ankra cluster <provider> control-plane set-instance-type <cluster> <instance-type>
```

### Change the control plane instance type

How Ankra changes the instance type depends on how many controllers the cluster has and whether it is running:

| Mode | When it applies | What happens |
| - | - | - |
| `rolling` | A running cluster with three or more controllers, on any provider | Ankra drains and resizes one controller at a time and waits for each to be healthy before the next. The Kubernetes API stays up. |
| `live_with_api_downtime` | A running Hetzner cluster with one controller | Ankra resizes the only controller in place. The Kubernetes API is down for a few minutes while that server reboots on the new type. You have to accept the downtime first. |
| `offline` | A stopped cluster, on any provider | On a paused Hetzner, UpCloud or DigitalOcean k3s cluster the change is refused. Otherwise Ankra saves the new type for the next start. A default stop on Hetzner, OVHcloud, UpCloud, DigitalOcean, Proxmox VE or HPE Morpheus deletes the servers, so the start creates every server again, the controllers on the new type. AWS EC2, Scaleway and Ankra Cloud keep the servers powered off: the start powers those same servers back on with the type they had, so the saved type is not applied to them (see Stop and start below). |

A running cluster with one controller on any other provider cannot change its instance type live. Either grow it to three controllers first and then resize it with no downtime, or stop it and change the type offline.

#### What the API downtime means

While the only controller reboots, the Kubernetes API is not available:

* Pods that are already running on the workers keep running.
* `kubectl`, deployments, Stack and add-on changes, controllers and operators, and the Ankra agent pause until the API is back. Anything that needs the API, such as scaling a Deployment or rescheduling a pod, waits until then.
* Before it changes the server, Ankra takes an etcd snapshot on the node and drains it. Hetzner changes the server type and keeps its disk and IP address, so the node comes back as the same machine with the same cluster state. Ankra then waits for the node to be Ready again. When the new type has a larger disk, the disk grows with it, and Hetzner cannot shrink it again, so the controller cannot move back to a type with a smaller disk.

In a test on 2026-10-28, a Hetzner cluster resized from `cpx22` to `cpx32` finished the whole step in about two and a half minutes, and the workloads on the workers were not restarted. Plan for a few minutes of API downtime. To avoid any downtime, grow the cluster to three controllers first.

Ankra does not start the resize while another change is running on the cluster, for example a [scheduled Cluster State Snapshot](/guides/kubernetes-upgrades#scheduled-cluster-state-snapshots). Start it again when that change has finished.

#### Resize the only controller

**In the dashboard:** open **Nodes → Control plane** and pick the new type. The tab says the Kubernetes API will be unavailable for a few minutes. **Resize with API downtime** in the review dialog accepts the downtime and starts the resize.

**On the CLI:** `control-plane get` shows the change as `Change type: yes - live with a few minutes of API downtime (single controller)`. `set-instance-type` refuses the change unless you pass `--accept-api-downtime`:

```bash theme={null}
ankra cluster hetzner control-plane get <cluster>
ankra cluster hetzner control-plane set-instance-type <cluster> cpx32 --accept-api-downtime
ankra cluster operations list <operation-id>    # show the resize operation the command printed
```

**From the AI or MCP:** the `change_control_plane` tool takes `accept_api_downtime`. The AI tells you about the downtime and sets it only after you have accepted it.

**On the API:** send `accept_api_downtime: true` with the new type. Without it, the request is refused with `409 Conflict` and a message that describes the downtime.

```bash theme={null}
curl -X PUT https://platform.ankra.app/api/v1/clusters/hetzner/<cluster-id>/control-plane/instance-type \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_type": "cpx32", "accept_api_downtime": true}'
```

Sending the type the controller already has changes nothing and needs no acceptance.

***

## Restart a node

Restart one node - a control plane, a worker or the bastion - without waiting for a reconciliation. The restart is a tracked operation, and workloads on the node are briefly unavailable while it reboots.

**In the dashboard:** open **Nodes**, find the machine in the **Machines** table and choose **Restart VM** from its **⋯** menu.

**On the CLI:** find the node ID, restart it, and follow the operation:

```bash theme={null}
ankra cluster <provider> nodes list <cluster>
ankra cluster <provider> nodes get <cluster> <node-id>
ankra cluster <provider> nodes restart <cluster> <node-id>
ankra cluster operations list <operation-id>
```

The node must be `up` with no restart already in flight. If a node never joined, `ankra cluster <provider> nodes cloud-init-log <cluster> <node-id>` shows its cloud-init status and the end of its log, read over the bastion (not on Proxmox VE or HPE Morpheus). You can also ask Ankra's AI, for example "restart worker-2 on my-cluster".

***

## Bastion

The bastion is the machine Ankra and you reach the cluster through: every SSH hop into the private network goes via it. On most providers it carries no workload traffic, so workloads keep running while it is down, but Ankra cannot provision, scale, upgrade or reconcile the cluster until it is back.

**In the dashboard:** **Nodes → Bastion & VMs** shows its state and the last health verdict, with **Diagnose over SSH**, **Restart VM** and **Resize**. The **⋯** menu on the bastion row in the Machines table also has **Resize bastion**.

```bash theme={null}
ankra cluster <provider> bastion status <cluster>                     # last health verdict, without probing
ankra cluster <provider> bastion diagnose <cluster>                   # probe it now, as an operation (not Scaleway)
ankra cluster <provider> bastion resize <cluster> <instance-type>     # Hetzner, OVHcloud, UpCloud, DigitalOcean
```

A resize powers the bastion off, changes its type and powers it on again, so SSH access is interrupted briefly. Where the bastion is also the NAT for the nodes (AWS `bastion_nat` egress), node egress stops until it is back.

### SSH access and keys

**Settings → Access** shows copy-paste SSH commands through the bastion for the cluster's own addresses, and the SSH key credentials attached to the cluster. To change the keys:

```bash theme={null}
ankra cluster ssh-keys get <cluster>
ankra cluster ssh-keys set <cluster> --ssh-key-credential-ids <key-id-1>,<key-id-2>
ankra cluster ssh-keys resync <cluster>
```

The new keys are written to every node on the next reconciliation; `resync` forces it. The key Ankra itself uses is never removed. For everyday `kubectl` you need no SSH at all - see [Accessing Clusters with kubectl](/guides/kubeconfig).

***

## Upgrade Kubernetes

**In the dashboard:** **Settings → General** shows the current Kubernetes version. Pick a target and click **Upgrade**. The same card has **Auto upgrade patch versions**, which moves the cluster to the newest patch of its current minor version on its own; minor versions are never upgraded automatically.

**On the CLI:**

```bash theme={null}
ankra cluster <provider> k8s-version <cluster>     # current version and distribution
ankra cluster kubeadm-versions                     # or: ankra cluster k3s-versions
ankra cluster upgrade <cluster> v1.33.2            # kubeadm: a plain upstream tag
ankra cluster upgrade <cluster> v1.33.2+k3s1       # k3s
```

* Nodes upgrade one at a time, control plane first, then workers. Each node is cordoned, drained honouring PodDisruptionBudgets, upgraded, and must be `Ready` at the target version before the next one starts.
* An etcd snapshot is taken before the control plane upgrade. With external etcd, the dedicated etcd members are upgraded first, one at a time, each saving a snapshot.
* A drain blocked by a PodDisruptionBudget stops the rollout; `--force` proceeds anyway.
* One minor version at a time (1.33 to 1.34, not 1.33 to 1.35), and no downgrades.

Restore points, the pre-upgrade checklist and what to do when a hop stops are in [Upgrade Kubernetes on a Cluster](/guides/kubernetes-upgrades).

***

## Stop and start

Stopping releases the cluster's compute and keeps its configuration, stacks and credentials in Ankra, which is how you park a cluster you do not need right now. Starting re-provisions it and reconciles it back to running. What a stop does to the servers depends on the provider:

| Provider | What a stop does |
| - | - |
| Hetzner, UpCloud, DigitalOcean | Captures an encrypted etcd snapshot, then deletes the servers; the start restores the snapshot. k3s clusters can **Pause** instead: the servers are powered off and kept with their disks, and keep billing. |
| OVHcloud, Proxmox VE, HPE Morpheus | Captures an encrypted etcd snapshot, then deletes the servers; the start restores the snapshot. |
| AWS EC2, Scaleway, Ankra Cloud | Powers the servers off and keeps them with their disks, so the cluster comes back with its state. |

[Stop cluster](/platform/cluster-settings#stop-cluster) explains the snapshot, the pause mode and the restore in full.

**In the dashboard:** **Settings → General → Danger Zone → Stop cluster**, or **Stop cluster** / **Start cluster** in the cluster's **⋯** menu. They also run on a timetable with [Power Schedules](/platform/cluster-power-schedules).

```bash theme={null}
ankra cluster <provider> stop <cluster>
ankra cluster <provider> stop <cluster> --mode pause               # Hetzner, UpCloud, DigitalOcean k3s clusters
ankra cluster <provider> stop <cluster> --preserve-state=false     # tear down without a snapshot
ankra cluster <provider> stop <cluster> --force                    # cancel in-flight operations and stop now
ankra cluster <provider> start <cluster>                           # the whole cluster
ankra cluster <provider> start <cluster> --scope control_plane     # only the control plane, to inspect or repair it
ankra cluster <provider> start <cluster> --restore-state=false     # start fresh instead of restoring the snapshot
```

* A stop never deletes the volumes your workloads provisioned through the CSI driver, forced or not; they keep billing while the cluster is stopped. `--force` also deletes the cluster's load balancers, and never captures a snapshot.
* Stop and start run in the background. A start is refused with `409` while a stop or terminate is still running.
* While the cluster is stopped, `ankra cluster <provider> nodes list` still shows the saved machines that the next start re-provisions.

***

## Terminate a cluster

Terminating deletes the cluster's servers and the network Ankra created, then removes the cluster from Ankra. It cannot be undone.

**In the dashboard:** **Settings → General → Danger Zone → Terminate**. The dialog lists the persistent volumes the teardown deletes, and the button stays disabled until you accept that.

```bash theme={null}
ankra cluster deprovision <cluster>                            # names the volumes and asks
ankra cluster deprovision <cluster> --accept-volume-data-loss  # for scripts
```

* **Volumes are deleted only once you accept it.** `--yes` skips the teardown confirmation but never the volume one. The API lists the volumes with `GET .../deprovision-volumes` and needs `?accept_volume_data_loss=true` on the `DELETE`; without it the answer is `409` naming them.
* **`--force`** deletes leftover load balancers and tolerates infrastructure that no longer answers. It never stands in for accepting the volume loss. On Proxmox VE it finishes the teardown when the host or jumphost is unreachable, leaving the VMs behind.
* **A stopped cluster** can be terminated too: the volumes recorded at stop time are still known and named.

| Provider | What happens to persistent volumes |
| - | - |
| Hetzner, OVHcloud, UpCloud, DigitalOcean | Deleted with the cluster once you accept it. On Hetzner a volume labelled `ankra-retain` is kept. |
| AWS EC2, Scaleway, Ankra Cloud | Follow the cluster's `retention_policy`: `retain` (the default) keeps them in your account, where they keep billing; `delete` removes them once you accept it. |
| Proxmox VE, HPE Morpheus | No volume step. The VMs Ankra created are deleted; your Proxmox nodes, storage and bridges, or your Morpheus groups, clouds and networks, are left untouched. |

[Persistent volumes](/platform/cluster-settings#persistent-volumes) covers every case, including volumes Ankra cannot prove belong to the cluster.

***

## Choices fixed at create time

A few choices cannot be changed on a running cluster. They are made in the create wizard (the **Kubernetes** step) or in the create request, and they shape the upgrade and networking tasks above.

* **Distribution.** `kubeadm` (the default everywhere: wizard, CLI and API) is upstream Kubernetes with containerd; its versions are plain tags such as `v1.33.2`. `k3s` is a single-binary distribution; its versions look like `v1.33.2+k3s1`.
* **CNI** (`cni`). kubeadm clusters always run Cilium. k3s clusters choose `flannel` (the default), `calico` or `cilium`; AWS defaults to Cilium for both distributions. The CNI cannot be changed later.
* **CNI features** (`cni_features`). Cilium offers `kube_proxy_replacement`, `hubble` and `wireguard_encryption`; Calico offers `ebpf_dataplane`; flannel takes none. On k3s, `kube_proxy_replacement` and `ebpf_dataplane` need a single control plane.
* **etcd topology** (kubeadm only). `stacked` (the default) runs etcd on the control plane nodes. `external` runs it on 3 or 5 dedicated machines (`etcd_node_count`), sized by a provider-specific field:

| Provider | Field that sizes the etcd machines |
| - | - |
| Hetzner | `etcd_server_type` |
| OVHcloud | `etcd_flavor_id` |
| UpCloud | `etcd_plan` |
| DigitalOcean | `etcd_size` |
| Scaleway, AWS EC2 | `etcd_type` |
| Proxmox VE | `etcd_instance_type` |
| HPE Morpheus | `etcd_plan_id` |
| Ankra Cloud | `etcd_plan` |

***

## Next steps

* [Nodes](/platform/cluster-nodes) - every control on the Nodes tabs, including standalone VMs.
* [Cluster Autoscaling](/guides/cluster-autoscaling) - let pod demand size your node groups.
* [Power Schedules](/platform/cluster-power-schedules) - stop and start on a timetable.


# OVH Clusters
Source: https://docs.ankra.ai/guides/ovh-clusters

Create a Kubernetes cluster on Public Cloud instances in your own OVHcloud project, with Ankra installing and operating Kubernetes, ingress, TLS and DNS.

Choose OVHcloud when you want Kubernetes on Public Cloud instances in a project you own, including OVHcloud's 3-AZ regions where a cluster can be spread across three availability zones. Ankra creates the private network, managed network gateway, bastion and instances in your project, installs Kubernetes and the OpenStack cloud integration, and then operates the cluster for you - this is an **Ankra Managed** cluster. OVHcloud bills you directly for the instances.

## Before you start

* **OVHcloud API credentials** - application key, application secret, consumer key and Public Cloud project ID - stored as an [OVH credential](/platform/credentials/ovh).
* An **SSH key credential** - your own public key, or one Ankra generates. See [SSH Key Credentials](/platform/credentials/ssh-key).
* Room in your project's quotas for the instances, a network and the SSH keys, and the target region enabled on the project. Check them in the [OVHcloud Control Panel](https://www.ovh.com/manager/); OVHcloud support raises quotas.

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **OVHcloud** under **Ankra Managed**.
>
> **2. Credential & Region**
>
> Pick the OVH credential and the SSH key (or add either inline), and the region, for example Gravelines, Strasbourg, Beauharnois, Warsaw, London or Frankfurt.
>
> **3. Network & Compute**
>
> Keep or change the subnet CIDR, then pick the bastion flavor, the control plane count and flavor, and the worker flavor and count, with optional autoscaling bounds and a cloud-init document for the workers. The wizard shows each flavor's vCPUs, RAM, disk and hourly price. Add more node groups once the cluster is running.
>
> **4. Kubernetes**
>
> Keep **kubeadm** (the default, with Cilium) or pick **k3s**, and optionally the version. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) for the CNI and etcd options.
>
> **5. GitOps**
>
> Optionally connect a Git repository; Ankra commits the cluster's stacks to it. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind an OVHcloud load balancer.
> * **Include Public DNS** - a delegated subdomain on `ankra.cc` with external-dns wired, so an ingress hostname under it gets its DNS record and TLS certificate automatically.
>
> **6. Details**
>
> Name the cluster, set its environment, and click **Create cluster**. A progress view follows the network, bastion, control plane and worker instances, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials ovh create --name my-ovh-cred --project-id <project-id>   # prompts for the keys
> ankra credentials ovh ssh-key create --name my-ssh-key --generate
>
> ankra cluster ovh regions --credential-id <ovh-credential-id>
>
> ankra cluster ovh create \
>   --name my-cluster \
>   --credential-id <ovh-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --region GRA7 \
>   --gateway-flavor-id c3-4 \
>   --control-plane-count 1 \
>   --control-plane-flavor-id b3-16 \
>   --worker-count 2 \
>   --worker-flavor-id b3-16
> ```
>
> Leave a flavor flag out and the platform's default applies, as in the API tab: `c3-4` for the gateway and `b3-16` for the control plane and workers. `--distribution k3s`, `--etcd-topology external`, `--include-networking=false` and the `--gitops-*` flags cover the other choices.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/ovh \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<ovh-credential-id>",
>     "ssh_key_credential_id": "<ssh-key-credential-id>",
>     "region": "GRA7",
>     "control_plane_count": 1,
>     "control_plane_flavor_id": "b3-16",
>     "node_groups": [
>       {"name": "default", "instance_type": "b3-16", "count": 2}
>     ],
>     "include_networking": true,
>     "include_dns": true
>   }'
> ```
>
> Omitted, the bastion flavor (`gateway_flavor_id`) defaults to `c3-4` and the control plane and worker flavors to `b3-16`. Every field, the region list and the flavors are in the [OVH Reference](/reference/ovh).

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created in your project

* **A private network** - a vRack VLAN with a DHCP subnet. Nodes have private addresses only.
* **A managed network gateway** (`<cluster>-network-gw`) attached to the subnet. It is the nodes' default route and NAT: all node egress leaves through it.
* **A bastion** (`<cluster>-bastion`) - the only instance with a public IP. It is an SSH jump host, not a router: Ankra reaches the nodes through it to provision, upgrade and reconcile, and you can use it for `ssh -J`. Clusters created before the bastion rename carry the instance name `<cluster>-gateway` for the same component.
* **Control plane and worker instances**, and your SSH key on every instance.
* **The OpenStack cloud controller manager and Cinder CSI driver**, for `LoadBalancer` Services and persistent volumes.

Because no workload traffic depends on the bastion, workloads keep running while it is unavailable, but Ankra cannot provision, scale, upgrade or reconcile the cluster until it is back, and the dashboard can show the cluster as degraded meanwhile. The [OVH Reference](/reference/ovh#architecture) has the diagram.

## OVHcloud specifics

* **Flavor changes go one way.** A node group moves to a larger flavor only; each node is powered off, resized and powered on, with brief downtime for its workloads. For smaller nodes, create a new group and delete the old one.
* **Labels and taints at add time.** `ankra cluster ovh node-group add` also takes `--labels` and `--taints`, so a group can be created with them in one step.
* **First-boot scripts.** A node group can carry a cloud-init document, applied at first boot on every instance the group ever creates, including replacements - see [Node Group Cloud-init User Data](/guides/node-group-user-data).
* **Restart** is a soft reboot through the OVHcloud API, falling back to a hard reboot when the guest OS does not respond. An instance that is `SHUTOFF` is started instead. `ankra cluster ovh nodes list` shows each node's live `provider_status` and `provider_power_state`, which helps spot a crashed or powered-off instance first.
* **Access.** `ankra cluster ovh access-info <cluster>` prints the bastion and control plane IPs with ready-to-paste `ssh -J` and Kubernetes API port-forward commands.
* **Stop.** A stop releases the node instances, the bastion and the managed network gateway. The private network is kept and reused on the next start, and the Cinder volumes are kept and billed while the cluster is stopped.
* **Terminate** deletes the instances, networks and SSH keys; the dialog and `ankra cluster deprovision` list the Cinder volumes the teardown deletes.

### Availability Zones

Some OVH regions are *3-AZ*: one region spanning three availability zones with independent power, cooling, and networking. `EU-WEST-PAR` holds `eu-west-par-a`, `eu-west-par-b` and `eu-west-par-c`, and `EU-SOUTH-MIL` holds the equivalent three. Every other region is a single failure domain, so check before you plan around zones.

Two rules come from OVH and shape everything below. An instance's zone is chosen at creation, and a request that names no zone gets whichever zone OVH picks - in practice the same one for every node of a cluster. And an instance's zone is fixed for its lifetime, so re-placing a node means replacing it.

#### Find the zones a region has

Zone names are region-scoped, so check the spelling before you use one. Only a region whose type is `region-3-az` accepts zone placement.

```bash theme={null}
ankra cluster ovh regions --credential-id <ovh-credential-id> --with-zones
```

```
Regions available to credential <ovh-credential-id>:
  EU-WEST-PAR      region-3-az    zones: eu-west-par-a, eu-west-par-b, eu-west-par-c
  GRA              region
```

#### Spread a new cluster across zones

Pass the zone pool at create. Ankra distributes instances across it deterministically: control planes and etcd spread per role, workers spread per node group, so a three-node database group gets one node in each zone rather than being balanced against unrelated workers.

```bash CLI theme={null}
ankra cluster ovh create \
  --name my-cluster \
  --credential-id <ovh-credential-id> \
  --ssh-key-credential-id <ssh-key-credential-id> \
  --region EU-WEST-PAR \
  --availability-zones eu-west-par-a,eu-west-par-b,eu-west-par-c \
  --control-plane-count 3 \
  --control-plane-flavor-id b3-16 \
  --worker-count 3 \
  --worker-flavor-id b3-16
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/ovh \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<ovh-credential-id>",
    "ssh_key_credential_id": "<ssh-key-credential-id>",
    "region": "EU-WEST-PAR",
    "availability_zones": ["eu-west-par-a", "eu-west-par-b", "eu-west-par-c"],
    "control_plane_count": 3,
    "control_plane_flavor_id": "b3-16",
    "node_groups": [
      {"name": "default", "instance_type": "b3-16", "count": 3}
    ]
  }'
```

> [!WARNING]
>
> Spreading across more than one zone requires **at least 3 control planes**. Fewer cannot keep etcd quorum through the loss of a zone, which is the only reason to spread a control plane, so the create is refused rather than quietly producing a cluster that fails on the first zone outage.

Omitting the zones leaves placement to OVH and changes nothing about how clusters behaved before. Clusters in single-zone regions are unaffected by everything in this section.

#### Pin a node group to one zone

A node group can be pinned to a single zone instead of spreading. Pin the group that runs zonal storage, because an OVH volume cannot attach from another zone.

```bash theme={null}
ankra cluster node-group add <cluster> \
  --name database-par-a \
  --instance-type r3-128 \
  --count 1 \
  --availability-zone eu-west-par-a
```

Day-2 growth follows the cluster's stored zone pool: node group add, node group scale, worker scale, and control plane growth all balance new instances around where the existing ones already are. A group whose nodes all share one zone is treated as pinned and grows in that zone; a group that is already spread keeps spreading.

Spreading is per group, so a group with fewer nodes than the pool has zones cannot cover every zone. A new group added without a pin takes the zone with the fewest instances cluster-wide for each of its nodes, and a one-node group therefore lands wherever the cluster is thinnest, which is not necessarily the zone its name suggests: two groups called `general-par-a` and `general-par-b`, added without `--availability-zone` to a cluster whose `eu-west-par-c` held only one control plane, both went to `eu-west-par-c`. A group whose name promises a zone needs the pin.

`ankra cluster node-group list` ends each line with `az=` and the zones the group's nodes were placed into (`availability_zones` on the node-group listing API), so a group that has collapsed into one zone is visible in a single call.

#### Node topology labels

Every OVH node carries `topology.kubernetes.io/zone` (the zone OVH reports for the instance) and `topology.kubernetes.io/region` (the cluster's region), so zone-aware scheduling works without extra configuration. The zone comes from what OVH reports for the live instance rather than what was requested, so it is correct even on clusters created before zone placement existed. On those older clusters Ankra records the zone the next time it reads the instance, but the labels are written by a server sync; trigger one rather than waiting:

```bash theme={null}
ankra cluster reconcile <cluster>
kubectl get nodes -L topology.kubernetes.io/zone
```

#### Fixing a cluster that is already in one zone

* **Workers - in place.** Add a node group pinned to the target zone, drain the old group, then delete it. No cluster rebuild.
* **Control planes - not in place.** The zone is immutable and Ankra never re-places an existing control plane, so a zone-spread control plane on an existing cluster means recreating the cluster.

A cluster created before zone placement existed has no stored zone pool, so a node group added to it without a zone still lands wherever OVH picks. Pin each group explicitly: three zones means three pinned node groups.

#### Zone tolerance needs more than node spread

**OVH High Speed block storage is zonal.** It is triple-replicated *within* a single zone and cannot attach from another. A single database pod with a single PersistentVolume is therefore **not** zone-fault-tolerant however the nodes are spread: the volume is the single-zone dependency, and if its zone goes down the pod cannot start anywhere else.

A zone-fault-tolerant stateful workload needs all of:

* **Replication at the application layer** - CloudNativePG or Patroni with one replica per zone, each with its own volume. Node spread gives the replicas somewhere to live; it does not create them.
* **A `WaitForFirstConsumer` StorageClass** so the volume is not bound before its pod is scheduled. Ankra ships `csi-cinder-sc-topology` for exactly this reason, and marks it the default on new OVH clusters. On a cluster created earlier, k3s's `local-path` class is still present and also marked default, so name the class explicitly on anything that matters rather than relying on which default wins:

  ```yaml theme={null}
  spec:
    storageClassName: csi-cinder-sc-topology
  ```
* **A node group pinned to one zone per replica**, so a rescheduled pod cannot land where its volume is not. `allowedTopologies` on the StorageClass does not do this on its own - it narrows which zones the provisioner may choose from, it does not tie a volume to one of them.
* **`topologySpreadConstraints`** keyed on `topology.kubernetes.io/zone` for the stateless tiers.

Node spread is necessary but never sufficient.

> [!WARNING]
>
> **Zone placement is pending on OVH.** The Cinder CSI provisioner runs with its Topology feature gate off on every Ankra OVH cluster, because OVH Block Storage rejects the compute zone names the gate forwards - with the gate on, every volume creation in a 3-AZ region fails with `Availability zone 'eu-west-par-a' is invalid`. While it is off the provisioner sends no zone at all: Cinder creates the volume in its own default zone, and the PersistentVolume carries no zone affinity. That applies to every class, `csi-cinder-sc-topology` included, so delayed binding still holds the volume back until a pod is scheduled, but the volume is not placed in that pod's zone.
>
> Until the gate can be re-enabled per region, pin each stateful replica to a node group in one zone, so its pod can only ever be scheduled where its volume already is.

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `ovh`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Cluster stuck in provisioning | Check the OVH API credentials and the project's quotas (instances, networks and VLANs, SSH keys) in the [OVHcloud Control Panel](https://www.ovh.com/manager/) |
| Network setup fails during the reconcile | The region is not enabled on the project's private network. List the regions the credential can deploy in with `ankra cluster ovh regions` |
| Invalid API credentials | Re-validate them at the [OVH API Console](https://api.ovh.com/console/) |
| Flavor unavailable | Try another region or flavor |
| Cannot scale workers | Ensure the cluster is online and no operation is running |
| A node group's nodes all landed in one zone | Pin the group with `--availability-zone`; see [Pin a node group to one zone](#pin-a-node-group-to-one-zone) |
| Volume creation fails with `Availability zone '...' is invalid` | See the warning under [Zone tolerance needs more than node spread](#zone-tolerance-needs-more-than-node-spread) |


# OVHcloud Managed Kubernetes (MKS)
Source: https://docs.ankra.ai/guides/ovh-mks-clusters

Provision, import, and operate OVHcloud Managed Kubernetes (MKS) clusters with Ankra - free and standard control planes, node pools, upgrades, GitOps, and AI-assisted operations.

[OVHcloud Managed Kubernetes (MKS)](https://www.ovhcloud.com/en/public-cloud/kubernetes/) runs on OVHcloud Public Cloud. OVHcloud runs the control plane; Ankra provisions the cluster, then manages everything on top - node pools, Kubernetes upgrades, addons, stacks, GitOps, and AI-assisted operations.

This page covers OVHcloud MKS specifically. For the shared concepts across all managed providers - live options, discovery/import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes).

## Why OVHcloud MKS with Ankra

* **Free or standard control plane** - pick the OVHcloud control-plane plan that fits the workload.
* **Private networking and anti-affinity** - attach a private network and spread nodes with anti-affinity where supported.
* **Live pricing and options** - regions, Kubernetes versions, and node flavors are fetched live with your OVHcloud credential.

## Prerequisites

**OVHcloud application keys** with a Public Cloud project (`project_id`), stored in Ankra. See [OVH API Credentials](/platform/credentials/ovh).

GitOps is optional: connect a repository at creation and Ankra commits the cluster's stack definitions to Git.

## Creating an OVHcloud MKS cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick OVHcloud's **Cloud Managed** action.
>
> **2. Credential & Region**
>
> Select the OVHcloud credential and a region (for example `GRA9`). Regions load live from OVHcloud.
>
> **3. Node Pools**
>
> Define one or more worker pools: name, node flavor (with live pricing), count, labels, and autoscaling bounds.
>
> **4. Kubernetes & Plan**
>
> Pick a Kubernetes version or keep the default, choose the control-plane plan (`free` or `standard`), and set the update policy.
>
> **5. GitOps (optional) & Create**
>
> Optionally connect a Git repository, then create. Ankra runs OVHcloud preflight checks, provisions the cluster, retrieves the kubeconfig, and installs the Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider ovh_mks \
>   --name my-ovh-cluster \
>   --credential-id <ovh-credential-id> \
>   --location GRA9 \
>   --node-pool-name workers \
>   --node-pool-size b2-7 \
>   --node-pool-count 2
> ```
>
> Plan, private network, anti-affinity and update policy are set from the portal or the API; `--autoscaling` with `--autoscaling-min` and `--autoscaling-max` sets the initial pool's bounds. The CLI accepts `ovh_mks` (and the `ovh-mks` alias).

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/org/clusters/managed/ovh_mks \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-ovh-cluster",
>     "credential_id": "<ovh-credential-id>",
>     "location": "GRA9",
>     "kubernetes_version": "1.32",
>     "node_pools": [
>       {"name": "workers", "size": "b2-7", "count": 2}
>     ],
>     "ovh_mks": {"plan": "free", "anti_affinity": false, "monthly_billed": false}
>   }'
> ```

### OVHcloud MKS options

| Field | Description |
| - | - |
| `ovh_mks.plan` | Control-plane plan (`free` or `standard`) |
| `ovh_mks.private_network_id` | Attach the cluster to a private network |
| `ovh_mks.anti_affinity` | Spread nodes with anti-affinity |
| `ovh_mks.monthly_billed` | Bill nodes monthly instead of hourly |
| `ovh_mks.update_policy` | Node update policy |

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

Node pools, upgrades, and deletion work from the CLI, portal, or API. The CLI examples use `--provider ovh_mks`:

```bash theme={null}
# scale a pool to a fixed count
ankra cluster managed node-pool scale <cluster_id> workers --provider ovh_mks --count 5

# upgrade the cluster
ankra cluster managed upgrade <cluster_id> --provider ovh_mks --version 1.32

# delete the cluster
ankra cluster managed delete <cluster_id> --provider ovh_mks
```

Autoscaling bounds are set from the portal, with `ankra cluster managed node-pool update --autoscaling --autoscaling-min <n> --autoscaling-max <n>`, or with the `PATCH .../node-pools/{name}` endpoint. See [Managed Kubernetes - day-2 operations](/guides/managed-kubernetes#day-2-operations) for the shared mechanics.

## Importing an existing MKS cluster

Already running OVHcloud MKS? Discover clusters in your Public Cloud project and adopt them into Ankra without touching them. Discovery and import run from the portal, the CLI (`ankra cluster managed discover|import --provider ovh_mks`) or the API - see [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters).

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [OVH API Credentials](/platform/credentials/ovh)
* [Cluster settings](/platform/cluster-settings)


# Use the ankra CLI in CI
Source: https://docs.ankra.ai/guides/pipeline-agents

Call the ankra CLI from ordinary CI jobs - comment an AI review of a cluster change on a pull request, explain a failed deploy in Slack, and post a scheduled health check.

Your CI already has the schedule, the secrets and the logs. What it lacks is an answer to "what will this change do to the live cluster?" or "why did that deploy fail?". The [Ankra CLI](/integrations/ankra-cli) gives a CI job two commands for that: `ankra chat` asks Ankra's AI a question with your clusters as context and prints the answer, and `ankra cluster apply --wait` applies a cluster definition and waits for the result. This page shows one working job for each of three uses.

## Prerequisites

* A CI system that can run a shell step. The examples use GitHub Actions; the commands are the same anywhere.
* A [service token](/guides/service-tokens) stored as the CI secret `ANKRA_API_TOKEN`, with the narrowest role the job needs - see [Keep CI jobs read-only](#keep-ci-jobs-read-only).
* The CLI installed in the job:

  ```bash theme={null}
  bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
  ```

`ankra chat` prints the answer on standard output and the conversation ID on standard error, so redirecting standard output captures only the answer. To parse the answer, the tools the AI ran and any change it proposed, add `-o json` - see [Parse the answer as JSON](#parse-the-answer-as-json).

***

## Comment a review of a cluster change on the pull request

When a pull request changes a cluster definition, pass the diff to `ankra chat` and post the answer as a comment. Ankra's AI compares the change with the live cluster.

```yaml theme={null}
# .github/workflows/ankra-review.yml
name: Ankra review
on:
  pull_request:
    paths:
      - "cluster.yaml"
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Ankra CLI
        run: bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
      - name: Review the change against the live cluster
        env:
          ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          change=$(git diff "$BASE_SHA" HEAD -- cluster.yaml | head -c 20000)
          ankra chat --cluster my-cluster --mode ask \
            "This pull request changes the definition of this cluster. Compare it with the live cluster, \
             summarise what will change, and flag any capacity or quota risk. The diff: $change" \
            > review.md
      - name: Comment on the pull request
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: fs.readFileSync('review.md', 'utf8'),
            })
```

Replace `cluster.yaml` with the path of your cluster definition and `my-cluster` with the cluster's name.

***

## Explain a failed deploy in Slack

After a merge, apply the cluster definition and wait for Ankra to accept it. If the apply fails, ask why and post the answer to Slack, so the channel gets a cause instead of a red cross.

```bash theme={null}
set -euo pipefail

if ankra cluster apply -f cluster.yaml --wait --timeout 15m; then
  echo "Configuration applied"
else
  summary=$(ankra chat --cluster my-cluster --mode ask \
    "The last apply to this cluster failed. Give the root cause and the exact fix.")
  curl -sS -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "$(jq -n --arg text ":rotating_light: Deploy failed on my-cluster: $summary" '{text: $text}')"
  exit 1
fi
```

`ankra cluster apply --wait` exits with code `5` when `--timeout` expires, so you can treat a slow apply differently from a hard failure. `--wait` covers the configuration write only: add-on deploys are dispatched afterwards, so check them with `ankra cluster operations list` before calling a rollout healthy. The CLI's other [exit codes](/reference/cli) let a job treat `3` (not found) as success for idempotent steps and re-authenticate on `6`.

***

## Post a scheduled health check

Run every 30 minutes, stay silent while everything is healthy, and post to Slack only when something is degraded.

```yaml theme={null}
# .github/workflows/ankra-health.yml
name: Ankra health check
on:
  schedule:
    - cron: "*/30 * * * *"
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - run: bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
      - name: Check every cluster
        env:
          ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        run: |
          report=$(ankra chat --mode ask \
            "Check every cluster. Reply with the single word OK if all are healthy, \
             otherwise a short summary of what is degraded and why.")
          if [ "$(echo "$report" | tr -d '[:space:]')" != "OK" ]; then
            curl -sS -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' \
              -d "$(jq -n --arg t ":warning: $report" '{text: $t}')"
          fi
```

Without `--cluster`, `ankra chat` answers across the whole organisation.

***

## Parse the answer as JSON

With `-o json` (or `-o yaml`), `ankra chat "<question>"` prints one document on standard output when the turn ends, instead of streaming the answer. Status lines and notices go to standard error, so standard output is only the document. The health check above, with a parsed result:

```bash theme={null}
set -uo pipefail

ankra chat --mode ask -o json \
  "Check every cluster. Reply with the single word OK if all are healthy, otherwise a short summary of what is degraded and why." \
  > result.json
status=$?

if [ ! -s result.json ]; then
  # The platform refused to start the turn (for example a rejected token): no document, the exit code says why.
  echo "ankra chat did not start (exit $status)" >&2
  exit "$status"
fi

answer=$(jq -r '.answer' result.json)
error=$(jq -r '.error // empty' result.json)
failed_tools=$(jq -r '[.tool_calls[] | select(.success == false) | .tool_name] | join(", ")' result.json)

if [ -n "$error" ]; then
  echo "The turn failed: $error" >&2
  exit 1
fi
if [ "$(echo "$answer" | tr -d '[:space:]')" != "OK" ]; then
  curl -sS -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' \
    -d "$(jq -n --arg t ":warning: $answer" '{text: $t}')"
fi
[ -z "$failed_tools" ] || echo "Tools that failed during the check: $failed_tools" >&2
```

| Field | Meaning |
| - | - |
| `answer` | The AI's answer as text. |
| `error` | Present when the turn failed, was cancelled or expired. The command then exits non-zero after printing the document. |
| `conversation_id`, `continuable` | Pass the ID to `--conversation` to ask a follow-up, when `continuable` is `true`. |
| `session_id` | The chat session the platform opened. |
| `mode` | The safety mode the turn ran in: `ask`, `agent` or `plan`. |
| `cluster_id`, `cluster_name` | The cluster the turn was scoped to. `cluster_id` is `null` for an organisation-wide question. |
| `tool_calls` | The tools the AI ran, in order: `tool_name`, `tool_call_id`, `success`, `status`, `execution_time_ms`, and `error`, `error_class` and `error_code` when one failed. `success` is `null` for a call that did not finish, and for a proposed change, whose `status` is `pending_confirmation`. |
| `pending_actions` | Changes the AI proposed that have **not** run: `action_id`, `tool_name`, `description`, `parameters`, `risk_level`, `reversible`, `created_at`, `expires_in_seconds`. |

A turn that starts and then fails still prints the document, with `error` set, and exits non-zero. When the platform refuses to start the turn, nothing is printed on standard output and the command exits with that error's [exit code](/reference/cli) (`6` for a rejected token, `3` for an unknown cluster). `-o` works for a one-shot question only, not for interactive chat.

***

## GitLab CI and other runners

The commands are the same in any CI. In GitLab CI, run the review job on `rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"` and diff against `$CI_MERGE_REQUEST_DIFF_BASE_SHA`, and run the health check from a scheduled pipeline with `rules: - if: $CI_PIPELINE_SOURCE == "schedule"`.

***

## Keep CI jobs read-only

* The review and health check jobs only read. Give them a service token with the `viewer` role, which includes ask-mode AI. Token `--scopes` only choose MCP access (`mcp:read`, `mcp:write`), so the role is what limits a CLI token.
* Only the deploy job writes. Give it a separate service token with a role that can deploy Stacks, such as `member`.
* Run `ankra chat` with `--mode ask`: ask mode investigates and may make safe creations, but does not change what is already running. Never pass `--mode agent` in CI; make changes through `ankra cluster apply` and your GitOps repository.

***

## Related

* [Ankra CLI](/integrations/ankra-cli) - installing and configuring the CLI
* [`ankra chat` reference](/reference/cli/chat) and [`ankra cluster apply` reference](/reference/cli/cluster) - every flag
* [Service Tokens](/guides/service-tokens) - organisation-owned tokens for CI


# pipeline.yaml reference
Source: https://docs.ankra.ai/guides/pipeline-reference

Every key of .ankra/pipeline.yaml with its type and default, the expression language and its contexts, the trigger table with the reason a run records, and the diagnostics the validator reports.

`.ankra/pipeline.yaml` is the one file an [Ankra pipeline](/guides/ankra-pipelines) is planned from. It sits beside [`.ankra/ankra.yaml`](/reference/application-descriptor) in the repository, and its parser, validator and planner live in exactly one place on the platform, so the dry run you get from `ankra pipeline validate` is the run.

On GitHub, a run plans its *logic* from this file as committed at the run's own head sha; on GitLab and Bitbucket Cloud it plans from the definition stored through `ankra pipeline definition put`. A dispatch may also carry a definition of its own (`ankra pipeline run --spec-file`, `spec_yaml` on the API): it is stored verbatim on the run, and the planner and the dispatcher both render from it. A run's *authority* - its [protected sections](/guides/ankra-pipelines#logic-is-open-authority-is-closed) - always comes from the default branch's approved definition, whichever source the logic came from, an override included.

## The document

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "orders-api"
stages:
  - name: "test"
    kind: "run"
    image: "golang:1.26"
    run: "go test ./..."
```

The parser is lenient about anything that does not change what the pipeline does, and strict about anything that would:

* Unknown keys are ignored, and reported. A key this reference does not define - at the top level or in any block - decodes into nothing, so the pipeline runs on whatever the default is; `validate` answers `warn` rather than `ok` and names the key, the line and the field it was probably meant to be (`unknown key "timeuot" in the stage block; did you mean "timeout"?`). The key space of `env`, `with`, `outputs`, `permissions`, `matrix` axes and your own service and environment names is yours, and is never reported. Ignoring the key is what lets an Ankra older than your file keep reading it, so this stays a warning and never blocks a run.
* A single scalar stands in for a one-element list (`branches: main`), a quoted number reads as a number (`retention_days: "30"`), and a flag accepts `true`/`false`, `yes`/`no`, `on`/`off` and `1`/`0`. YAML anchors are resolved, so an anchored `services` or `defaults` block behaves like an inline one.
* An empty document, a document that is not YAML, an `apiVersion` other than `ankra.io/v1`, a `kind` other than `Pipeline`, or a `stages` block that is not a list is fatal: the pipeline cannot be planned.
* `metadata.name` and at least one stage are required.

A pipeline mistakenly committed under `.ankra/manifests/` is refused by the manifest gate, because the file carries a `kind` and an `apiVersion` and would otherwise be applied to a cluster.

## Top-level keys

| Key | Type | Default | Meaning |
| - | - | - | - |
| `apiVersion` | string | required | `ankra.io/v1` |
| `kind` | string | required | `Pipeline` |
| `metadata.name` | string | required | The pipeline's name |
| `on` | block | none | The triggers - see [Triggers](#triggers). A pipeline that declares none is still runnable by API dispatch. |
| `full_run` | block | none | `events` and `branches` naming the runs on which no path filter applies, so every stage runs. See [Setting path filters aside](#setting-path-filters-aside). |
| `concurrency.group` | string | none | Runs sharing a group serialise: a new run waits queued behind the group's holder. Expressions are allowed, for example `"${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"`. |
| `concurrency.cancel_in_progress` | flag or expression | `false` | With a group, an in-flight run of the same group is superseded and cancelled when a new one arrives. Leave it off and the new run waits instead - on a per-branch group that means the branch queues behind itself, which the validator points out as advice; see [Newest commit wins](/guides/ankra-pipelines#newest-commit-wins). Set without a group it does nothing, and the validator warns. A run in flight that stored `false` is never superseded by a newer one, whatever the newer run's own flag says. A run that is still waiting can still be replaced by a newer run's `cancel_queued`. May be [one expression settled per run](#a-concurrency-policy-per-event). |
| `concurrency.cancel_queued` | flag or expression | `false` | With a group, a new run cancels every older run of the group that has not started yet, so the group keeps the one running run and the newest waiting one. It never cancels the running run. The new run's own value decides, whichever event queued the older runs. A re-run never replaces anything, because it repeats an older commit. May be [one expression settled per run](#a-concurrency-policy-per-event). |
| `workspace.size` | quantity | none | The per-run volume every stage shares, for example `"10Gi"` |
| `workspace.access` | `rwo` or `rwx` | `rwo` | `rwo` is a volume one node can attach at a time. The agent pins each step, and its cache and artifact helpers, to the node the volume is attached to (or, before its first attach, the node the scheduler selected for it), so sequential steps do not wait for the volume to detach and re-attach elsewhere. The pin is dropped, and the step log says why, when that node is gone, cordoned or not Ready. `rwx` needs a StorageClass that serves it named on the claim; nothing names one today, so an `rwx` workspace is refused at dispatch rather than left waiting for a claim that never binds. |
| `defaults.image` | string | none | The image of every stage that names none |
| `defaults.timeout` | duration | 30 minutes | The timeout of every stage that names none, for example `"15m"` |
| `defaults.resources` | block | 500m CPU, 1Gi memory | `cpu`, `memory`, `gpu` for every stage that names none |
| `defaults.cache` | list | none | [Caches](#caches) every stage declares unless it declares its own |
| `defaults.working_directory` | string | the workspace root | Working directory of every stage that names none |
| `defaults.network` | tier | the kind's default | Network tier of every stage that names none, in place of that kind's own default - so `defaults.network: "none"` denies egress to a `build` or a `scan` stage that names no tier of its own, and does it quietly, because the validator's warning reads a stage's own declaration rather than this one. A value above `egress-https` is a protected section. |
| `defaults.env` | map | none | Environment variables for every stage |
| `defaults.secrets` | list | none | Declared secrets every stage may read |
| `permissions` | map | none | Scope to `none`, `read` or `write`. The authority granted is the intersection of this block, the organisation's policy and the target environment; it can only narrow. Protected. |
| `secrets` | list | none | `name`, `from` (`app_env_secret`, `org_variable`, `registry` or `credential`) and optional `key`. A stage may only name a secret this list declares. Protected. |
| `credentials` | list | none | `name`, `from` (`cloud`, `git`, `registry` or `object_storage`) and `as`, the name it is materialised under. Declared once for the whole run and materialised for every step of it - there is no per-stage `credentials` block, and unlike `secrets`, a stage does not narrow which of them it receives. A `credentials:` key written on a stage is an unknown key: it is ignored, `validate` warns, and nothing is delivered. Protected, and refused for a fork run. |
| `services` | map | none | Sidecars by name: `image` (required), `env`, `ports`, and `ready.tcp` (a port) or `ready.http` (a path, probed on the first declared port). Without a probe the stage starts as soon as the container does. A sidecar's image is held to the organisation's image policy and its `env` to the same reserved names a step's own is - either violation refuses the whole step rather than running it. Protected. |
| `stages` | list | required | The main DAG |
| `on_failure` | list | none | Stages that run after the main `stages` have all concluded, and only when one of them failed. See [Failure and cleanup stages](#failure-and-cleanup-stages) |
| `finally` | list | none | Stages that run after every main and `on_failure` stage has concluded, whatever the outcome, and after a run that had started is cancelled. See [Failure and cleanup stages](#failure-and-cleanup-stages) |
| `path_sets` | map | none | Named lists of path patterns. Any path filter list includes one with a `{set: <name>}` entry. See [Path sets](#path-sets) |
| `environments` | map | none | The pipeline's half of each deployment environment binding: `data` (`none`, `restore_point` or `seed`), `verify` (stage names), `rollout` (`recreate`, `rolling`, `blue_green` or `canary`) and `gate` (`automatic`, `manual` or `custom`). Protected. |

Stage names must be unique across `stages`, `on_failure` and `finally`, because the three share one run and one output namespace.

### Failure and cleanup stages

A run has three phases, in this order: the main `stages`, then `on_failure`, then `finally`. Every `on_failure` and `finally` stage waits on every stage of the phases before it without declaring it.

* **`on_failure` runs only when the main stages failed.** Once every main stage has concluded, the stage runs if one of them failed, timed out, or was stopped by an infrastructure fault or by its agent. A failure that `continue_on_error` or `allow_failure` keeps from failing the run does not count. After a green run the stage is skipped with the reason "Skipped because the run did not fail, so this on\_failure stage was not needed."
* **`finally` runs whatever the outcome.** It starts once every main and `on_failure` stage has concluded: after a green run, after a failed one, and after `on_failure` stages that themselves failed.
* **`needs:` inside a phase works as it does in `stages`.** An `on_failure` stage that `needs:` another `on_failure` stage runs only when that one succeeded, and the same holds between two `finally` stages. A `needs:` on a main stage only orders the stage and gives it that stage's `needs.<stage>.*` values; it never stops an `on_failure` or `finally` stage from running when the main stage failed.
* **They count toward the run's outcome.** An `on_failure` stage that succeeds does not turn a failed run green. A `finally` stage that fails fails a run whose main stages passed; give it `allow_failure: true` when a failed cleanup should not do that.
* **A failed-only re-run** repeats an `on_failure` stage together with the main stage it responds to, and runs it again only if that stage fails again. A `finally` stage that failed is repeated on its own.
* **`finally` also runs when a run is cancelled.** See [Cancelling a run](#cancelling-a-run) below.

#### Cancelling a run

A run can be cancelled as a whole in five ways: a person cancels it from the portal, the CLI, the API or the check run's **Cancel** button; a newer run takes its concurrency group (`cancel_in_progress: true`); its pull request is merged or closed; the merge train stops testing its car; or `cancel_queued` replaces it before it starts.

When the run had already started, it cancels the way GitHub Actions treats `if: always()` steps and GitLab treats `after_script`:

1. Every main and `on_failure` stage that has not finished stops at once and concludes `cancelled`. Their pods are stopped. `on_failure` stages do not start, because a cancel is not a failure.
2. The `finally` stages run once the stopped stages' pods have stopped (at most three minutes after the cancel, if a cluster does not answer). Each keeps its own `timeout`.
3. The run concludes `cancelled`, whatever the `finally` stages did. Who cancelled it and why are recorded when you cancel, not at the end.

While the `finally` stages run, the run reads `running` with `cancelling: true` in the API, `ankra pipeline get` and the check run, and the check run stays in progress. It never reports success. Its title says the run was cancelled and is running its finally stages. Cancelling it again answers that it is already cancelling.

Some limits apply:

* **A run that never started runs no `finally`.** A queued run, including one `cancel_queued` replaces, has done nothing to clean up, so it concludes `cancelled` at once.
* **Cleanup has a budget of 15 minutes from the cancel.** `finally` stages still running after that are stopped and the run concludes `cancelled`.
* **Force cancel skips cleanup.** `ankra pipeline cancel <run> --force`, or `POST .../pipeline-runs/{run_id}/cancel?force=true`, concludes the run at once. On a run that is already running its `finally` stages, it stops them.
* **The concurrency group.** With `cancel_in_progress: false`, a cancelled run keeps its group while its `finally` stages run, so two runs of the group never overlap, cleanup included. The next run waits at most for the cleanup budget. With `cancel_in_progress: true`, a newer run takes the group at once and the cancelled run's `finally` stages finish outside it. Scope that cleanup to its own run, for example by naming what it creates and deletes after the `ANKRA_RUN_ID` variable every step has.

Stopping a single stage where it ran is not a cancel of the run. An infrastructure fault or an agent stopping a stage counts as a failure: `on_failure` runs, then `finally`.

### A concurrency policy per event

`cancel_in_progress` and `cancel_queued` take `true`, `false`, or one `${{ }}` expression that wraps the whole value. The planner settles the expression once for each run, so one file can give each event its own policy. A common case is a pull request whose new commit supersedes its old run, while a push to the default branch is never cancelled and only its newest waiting commit is kept:

```yaml theme={null}
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: "${{ event.kind != 'push' }}"
  cancel_queued: "${{ event.kind == 'push' }}"
```

* **What the expression can read.** It is settled before the run exists, so it reads only what has an answer then: `event` (`kind`, `ref`, `pull_request.number`, ...), the run's identity in `ankra` (`ref`, `sha`, `sha_short`, `repository.*`, `organisation`, `application`, `environments`) and the `inputs` that `on.manual` declares. `vars`, `secrets`, `matrix`, `ankra.run`, `ankra.merge_sha`, `ankra.environment`, `ankra.urls`, `event.changed_files`, `event.before_sha`, `event.pull_request.is_fork` and `event.pull_request.head_repo` are refused rather than read as empty, because an empty value read through a negation is `true`: `"${{ vars.PROTECTED != 'true' }}"` would make every run cancellable. So is anything that would carry a refused field along: a computed index into `ankra` or `event` (`event[name]`), an input named by a computed key (`inputs[name]`), and `ankra`, `event` or `event.pull_request` read as a whole value (compared, serialised or converted). Read the fields you need by name; `has(event.pull_request)` is fine, and so is a literal index such as `ankra.environments[0]`. Write the event as `event.kind`, not GitHub's `github.event_name`. The answer must be a boolean.
* **An expression that cannot be settled is `false`.** That covers a reference that does not exist yet (`steps`, `needs`, `success()`), GitHub's vocabulary, an evaluation error and a non-boolean answer. `false` cancels nothing, so a mistake never cancels a run. But it does change the policy, so `ankra pipeline validate` reports it as `pipeline_concurrency:` at severity `warn`, naming the flag, the expression, the kinds of run it fails for and why. The check settles the block once for every kind of run the definition can start (a push, a pull request, a tag, a schedule and a manual dispatch when the triggers declare them, and always an API call, an agent run and a re-run, which can start any pipeline), with the run's own repository, ref and commit and a stand-in value for each required input, so a mistake in a pipeline that only runs by hand is reported too, and a run that cannot exist is not. Validate a definition before you merge a change to one of these expressions. A group expression that cannot be settled is reported the same way, and such a run is planned with no group.
* **Anything else carrying `${{` is refused.** `"yes ${{ x }}"` or two expressions side by side cannot be read as a boolean, and reading them as `false` would switch your policy off without a word.
* **Two parties decide a supersede.** The new run's settled `cancel_in_progress` decides whether it tries to supersede or waits. The run in flight stored its own value when it took the group, and only a run that stored `true` can be cancelled. In the example, a push run stores `false`, so no later run of its group can cancel it, whether that run is a pull request, a re-run or a dispatch.
* **A re-run of a push or pull request is planned as the event it repeats.** A re-run of a push run settles the flags as a push, but it never applies `cancel_queued`: it repeats an older commit, and replacing the newer one waiting in the group would leave the branch's newest commit without a run. A re-run of any other run is planned with `event.kind` `rerun`.
* **`cancel_queued` is the new run's decision alone.** It replaces every older run of the group that has not started, whichever event queued it. If a run must never be replaced or wait behind a branch's runs (a manual dispatch, an API or agent run, or a re-run of one of those), give it a group of its own: `${{ event.kind == 'push' || event.kind == 'pull_request' ? ankra.ref : 'dispatch-' + ankra.sha }}`. Keying on what the branch's runs are, rather than on `event.kind == 'manual'`, also covers the run kinds you did not think of.

## Triggers

| Key | Fields | Fires on |
| - | - | - |
| `on.push` | `branches`, `paths` | A push to a matching branch whose changed files match `paths`. Empty `branches` matches every branch; empty `paths` matches every change. |
| `on.pull_request` | `branches`, `paths`, `fork_policy` | A pull request opened, synchronised or reopened against a matching **base** branch, or retargeted to one: a change of base branch plans a new run for the same head against the new base, and its check replaces the old one. `fork_policy` is `none` (refuse), `read_only` (the default: no secrets, no credentials, no identity beyond reading the run) or `trusted`; it is a protected section. A run that ends up restricted is also budget-clamped - at most 8 matrix legs per stage, a 60-minute step timeout, 2 CPU and 4Gi per step, no sidecar services, no shared caches and 256 MiB of artifacts and logs per run - and the clamps are applied to the plan, so what a reviewer reads is what executes. See [Forks](/guides/ankra-pipelines#what-a-step-runs-as). |
| `on.tag` | `patterns` | A pushed tag matching one of the glob patterns |
| `on.schedule` | list of `cron`, `branch`, `stages` | A five-field cron expression, numeric fields only (`MON` and `JAN` are refused, because the scheduler evaluates the fields numerically). `branch` defaults to the repository's default branch; `stages` restricts the run to a subset, which is how a nightly runs only the expensive suites. Schedules fire from a stored watermark, through the same trigger every push and pull request uses. |
| `on.manual` | `inputs` | A dispatch from the CLI or the API with the declared inputs |
| `on.webhook` | none | Declares an inbound dispatch against a per-pipeline token. Presence is the declaration; the tokens are not available yet. |

**Which schedule entry a firing uses.** A schedule you create with `ankra pipeline schedules create` (or the API) stores its own `cron` and `ref`; it does not point at an entry of `on.schedule`. When it fires, the run is planned from the first `on.schedule` entry, in the order the file declares them, whose `cron` has the same five fields as the schedule's (spacing does not matter) and whose `branch` is the schedule's ref, or is left out. That entry's `stages` decide the run, and they decide it everywhere the run is planned: when it is queued, when it is admitted and when each step is dispatched. A re-run of the run plans the same entry, so re-running a red nightly repeats the nightly, not the whole pipeline. A firing that matches no entry is refused with "No schedule this pipeline declares matches the cron this run was triggered for." and the schedule records that as its last outcome; it never falls back to running the whole pipeline. `stages` is not closed over `needs` for you: a stage whose dependency is left out of the subset is skipped as `dependency_skipped`, so name every stage the subset needs (`checkout` included). `ankra pipeline validate` warns about such a subset, and about an entry no firing can reach because an earlier one with the same cron already covers its branch.

A manual input has a `name` (letters, digits and underscores, so it can be addressed as `${{ inputs.<name> }}`), a `type` (`string`, the default, `boolean`, `number` or `choice`), an optional `default`, an `enum` (required for `choice`, and the default must be one of its values), `required` and `description`. A dispatch whose inputs do not match is refused with the planner's diagnostics and records nothing.

A path filter is decided on the event's changed files, and never excludes a run when the diff could not be read or was truncated - a file the planner could not see is not a file that did not change; the run records that it passed on incomplete information. A push's changed files are read from the provider the same way on GitHub, GitLab and Bitbucket Cloud: from the head of the branch's last successful push run (the newest one that concluded `success` within 30 days) to the pushed commit, or from the push's previous head when the branch has no such run, up to 300 paths. Ankra uses GitHub's compare API, GitLab's repository compare and Bitbucket Cloud's diffstat, and first checks with the provider that the starting commit is still in the pushed commit's history. So a push that follows a cancelled or failed one still sees the files those pushes changed, and a force push is caught on every provider, GitLab included. When there is no range to read, because the push created the branch or because history was rewritten past that commit, no path filter excludes anything. A pull request's files are read from the provider when the run is triggered (GitHub's pull request files, a GitLab merge request's diffs, Bitbucket's diffstat), up to 300 paths. The list is stored on the run, and a re-run reuses it. When a filter had to pass without a complete list, the run's `paths_unverified` says why: `provider_error` (the provider was asked and failed), `truncated` (more than 300 paths changed), `unsupported_provider` (the provider or the event offers no list), `branch_created` (the push created its branch, so there is no earlier commit to compare with) or `forced_push` (the push rewrote the branch's history, so its commits do not name every file that differs).

Every path list here, and every path list on a stage, can include a named list from `path_sets:` with a `{set: <name>}` entry. See [Path sets](#path-sets).

The `on:` triggers decide whether a run starts at all, for the whole pipeline. To run one stage on a narrower set of changes for one event only - a component's checks on a pull request that touches it, but on every push - give the stage an [event-scoped `when`](#event-scoped-filters) block rather than a second trigger or a duplicate stage.

### Setting path filters aside

A path filter lets a run skip what a change did not touch. When you want to see every stage anyway, or want some stages never to be skipped, set the filters aside. Nothing here changes a stage's `if:`, which still decides.

A **full run** runs every stage whatever the path filters say: `on.<event>.paths`, `when.paths` (and an [event block's](#event-scoped-filters) `paths`) and an [affected-only](#fields-common-to-every-stage) stage's `paths:` all pass. A run is a full run when one of these asks for it:

| Who asks | How | Recorded as |
| - | - | - |
| A person or token starting a run | `ankra pipeline run --full`, or `"full_run": true` in the body of `POST …/pipeline-runs` | `dispatch`, with who asked |
| A person re-running a run | `ankra pipeline rerun <run> --full`, or `?full_run=true` on `POST …/pipeline-runs/<run>/rerun` | `rerun`, with who asked. A re-run of a full run is a full run again without the flag |
| The `ankra:full-run` label on a GitHub pull request | Add the label. A full run of the pull request's head starts at once, every later push to the pull request runs in full while the label stays on it, and so does its [merge train](/guides/ankra-pipelines#the-merge-train-test-every-pull-request-as-it-will-merge) car. Remove the label and the next run applies the filters again | `label`, with who added it |
| Your organisation | `ci_full_run_on_default_branch` in the [organisation CI settings](/guides/ankra-pipelines#organisation-ci-settings) runs every push to a repository's default branch in full | `organisation_policy` |
| The pipeline | A top-level `full_run` block naming the `events` and `branches` it covers. An empty `events` list covers every event and an empty `branches` list every branch; for a pull request the branch is the one it targets | `pipeline` |

```yaml theme={null}
# Pull requests skip what they do not touch. Every push to main runs everything.
full_run:
  events: [push]
  branches: [main]
```

The run records why it set its filters aside: `full_run_source`, `full_run_requested_by` and `full_run_message`, the sentence the run page and `ankra pipeline get` show, for example "Path filters were set aside: the pull request carries the ankra:full-run label." The plan carries a `plan_paths_set_aside:` diagnostic. A request for a full run never joins a run of the same commit that applied its filters; it queues a run of its own.

**Always-run stages.** `ci_always_run_stages` in the [organisation CI settings](/guides/ankra-pipelines#organisation-ci-settings) names stages that run whatever their path filters say, together with every stage they need. It applies to every pipeline in the organisation that declares a stage of that name, and a name a pipeline does not declare changes nothing there. When the trigger's own `on.push.paths` or `on.pull_request.paths` matches none of the changed files, the run still starts for the always-run stages and what they need, and every other stage is skipped as `path_filter`. A stage that ran only because of the setting carries a `plan_paths_set_aside:` diagnostic. An always-run stage does not make the run a full run.

`paths`, `when` and `if` are logic, not [protected sections](/guides/ankra-pipelines#logic-is-open-authority-is-closed): a pull request can change them, its own filters included. That is deliberate, because an author can rewrite a stage's script anyway. A stage a pull request must not be able to filter away belongs in `ci_always_run_stages`, which lives in the organisation's settings, outside every repository, and only an organisation administrator can change. `full_run` is logic too, and only ever makes a run do more.

### Skipping a push with \[skip ci]

A pushed commit whose message carries `[skip ci]`, `[ci skip]`, `[no ci]`, `[skip ankra]` or `[ankra skip]` (in any case), or whose last paragraph has a `skip-checks: true` trailer, records a skipped run instead of queueing one: outcome `skipped`, error class `skip_marker`, and a message naming the marker. The skipped run still posts its check. `[skip ankra]` and `[ankra skip]` skip Ankra Pipelines alone; GitHub Actions' own `[skip actions]` does not skip Ankra.

Only the head commit of a branch push counts. A tag push, a pull request run and a merge train car never honour a marker: a tag releases, and a pull request's check is what branch protection reads, so a line in a commit message must not turn it green. Where a branch push may be skipped is `ci_skip_markers` in the organisation CI settings:

| `ci_skip_markers` | A marker skips a push to |
| - | - |
| `except_default_branch` (the default) | Any branch but the repository's default branch |
| `everywhere` | Any branch, the default branch included |
| `never` | Nothing. Markers are ignored |

The default keeps every push to the default branch running, because that run is what releases and what catches whatever a pull request's path filters left out.

## Stages

Every stage has a `name` (lower-case letters, digits, dashes and underscores, starting with a letter or digit - it becomes an expression key, a Job name component and a check-run title) and a `kind`. The kinds are a closed vocabulary; an unknown kind is fatal rather than a stage the planner skips.

| Kind | What it does | Today |
| - | - | - |
| `checkout` | Materialises the repository at the run's ref into the workspace, reading `with.fetch_depth` (default `1`, `0` for full history), `with.submodules` (`false`, `true` or `recursive`) and `with.lfs` | Executes end to end: a pinned public git image, a shallow fetch of the exact commit with a fallback to its ref, `lfs: true` refused by name rather than silently checking out pointer files. A pull request from a fork clones the fork's own head anonymously, reading the head repository the trigger recorded on the run; refused, rather than guessed, only on the rare delivery whose fork head repository could not be established at all. |
| `run` | Executes `run` (a script, under `/bin/sh -eu`) in an image the organisation's policy allows; `uses` is refused at validation until the step library ships (below) | Executes end to end |
| `build` | Builds a container image by digest in a rootless BuildKit pod in `ankra-ci-build` | Executes end to end: resolves its own builder, source and push target at dispatch (a bare repository, or a component with no resolvable registry, gets a named refusal instead of a guess) and pushes by digest to the organisation's CI staging repository; a fork run's build has no push target, so it builds and discards. When the CI cluster cannot build - its agent runs no pipeline steps, or its node runtime confines the rootless builder ([`build_runtime_confined`](/guides/ankra-pipelines#when-something-fails)) - and the organisation set [`ci_build_fallback: platform_builders`](/guides/ankra-pipelines#organisation-ci-settings) and holds the platform builds grant (`platform_builds_enabled`; Ankra makes it per organisation on request), the step runs on [Ankra platform builders](/guides/ankra-pipelines#ankra-platform-builders) instead, with the same downstream `scan`/`gate`/`publish`. Without the grant the step is refused as `build_fallback_none`, whatever the setting says. The build pod names no seccomp or AppArmor profile and no setting renders it `Unconfined`; on a confining node the fallback is the supported route, not a workaround. |
| `scan` | Runs the scanners over the source and the built image | Executes end to end: one step per declared scanner - Trivy, Semgrep, Checkov - each a pinned public image, writing the reports `gate` and the application's Security tab both read. The filesystem legs honour the stage's `working_directory`, so a monorepo component scans its own tree |
| `gate` | Evaluates persisted findings against organisation policy | Executes end to end: judges the run's own persisted findings against [`ci_image_gate`](/guides/ankra-pipelines#organisation-ci-settings), which the stage's own `with:` may only tighten and each required `scan` stage's own `fail_on` tightens further per scanner (below); a declared scanner that recorded nothing fails the gate by name. It records the digest it judged on its own step outputs |
| `publish` | Re-tags an approved image digest in the registry | Executes end to end: re-tags the exact digest `gate` approved as `sha-<7>` in the application's real repository, then gives the same digest every tag under `publish.tags` (below); refuses by name when its run has no successful `gate` step, when the build's digest is not the one the gate recorded judging (or the gate recorded none), or - in a monorepo - when its own stage name matches neither the bare nor the component-suffixed convention, so it cannot tell which component's build it is publishing |
| `preview` | Deploys the run's artefact into a per-pull-request environment, from inside the pipeline DAG | No executor yet: warned at validation, skipped by the planner - distinct from an Application's own pull-request preview, which already deploys an `ankra_pipeline` application's `build` digest without this stage kind existing (see [Ankra Pipelines](/guides/ankra-pipelines#how-a-run-happens)) |
| `verify` | Runs one verification: `probe`, `smoke`, `load_test`, `assert_promql` or `restore_verify` | No runner image on this build, so the step could only fail to start: warned at validation, skipped by the planner rather than dispatched |
| `deploy` | Rolls a release out to the host targets of the stage's `environment`: machines outside Kubernetes that run `ankra-host-agent` (see [`ankra targets`](/reference/cli/targets)). `deploy.artifact` names the `publish` stage whose digest is deployed, which must be inside this stage's `needs`; `deploy.release` is the release name; `deploy.targets.match_labels` narrows the targets | Executes, settled by the platform: every active host target of the environment that matches the labels pulls the release, and the step concludes from what the hosts report, with the outputs `deployment_id`, `digest`, `environment`, `targets_succeeded` and `targets_failed` (see [`ankra deployments`](/reference/cli/deployments)). The artifact must be a signed release bundle (a `build` stage with `bundle`) that this run published. Concluded skipped when the stage has no `deploy` block or names an environment the organisation does not have; failed when the run's protected sections are not approved, the artifact is not such a bundle, or no target matches. A pull request run or a fork run never deploys: the planner skips the stage as `deploy_untrusted_event`. It does not deploy to a Kubernetes cluster; an application's push to deploy does that |
| `agent` | An AI mission with a `goal`, `tool_profile`, `mode` (`ask` or `agent`), `budget` (`tool_calls`, `turns`, `minutes`) and `context` | No executor yet: warned at validation, skipped by the planner |
| `approval` | Blocks the run on a human decision: `roles` (required), `min_approvals`, `timeout`, `message`. Never satisfiable by an AI or a service token | No executor yet: warned at validation, skipped by the planner - so it blocks nothing today, and everything downstream of it runs |
| `webhook` | Posts a signed payload to `url` with `method`, optionally `wait_for_callback` within `timeout` | No executor yet: warned at validation, skipped by the planner |
| `automation` | Runs an AI automation graph and reads its outputs | No executor yet: warned at validation, skipped by the planner |
| `ankra` | Runs a platform verb through the run's scoped identity | No executor yet: warned at validation, skipped by the planner |
| `external` | Waits on a provider's own CI: `provider`, `workflow`, `inputs` | No executor yet: warned at validation, skipped by the planner |

A stage whose kind has no executor on this build is reported twice, in the same words. The validator raises a **warning** under `pipeline_executor:` naming the stage, its kind and the wave that ships the executor - a warning rather than a fatal, deliberately, because refusing the document would stop every other stage in it from running too. The planner then skips exactly that stage with reason `kind_unavailable`, checked before every event-dependent filter because it is a static fact about the stage. The run therefore concludes on its own; before this it sat `pending` forever and `ankra pipeline cancel` was the only way to release its concurrency group.

### Event-scoped filters

A stage's `when` can name the event a filter belongs to. For the run's event, the stage's block for that event - `push`, `pull_request`, `tag`, `schedule` or `manual` - supplies the branches and paths, and the flat `when.branches` and `when.paths` do not apply to it at all; an empty block means that event is unfiltered. Events with no block keep the flat fields. `when.events` is unchanged and still has to include the event. A re-run is planned as the event the run it repeats was planned as, so its event blocks and `when.events` decide the same way they did the first time. A re-run of a pull request run reads the `pull_request` block, and so does a re-run of a [merge train](/guides/ankra-pipelines#the-merge-train-test-every-pull-request-as-it-will-merge) run, which is planned as a pull request. A re-run of a push reads the `push` block and plans the push-only stages that push planned, `publish` included. A re-run of a schedule run plans that schedule firing again, with the same `stages` subset. A re-run also reuses the original run's stored change list, so a stage filtered only by `when.pull_request.paths` is left out of a re-run of that pull request exactly when it was left out the first time. A re-run of any other run (a tag, a manual or API dispatch, an agent run) is planned as its own `rerun` event, and an agent run as an `agent` event. Neither has a block, so both read the flat fields against the stored change list, and a stage runs in such a re-run only when its `when.events` lists `rerun` or is empty.

```yaml theme={null}
stages:
  - name: frontend
    kind: run
    image: node:22
    run: pnpm test
    when:
      pull_request:
        paths: ["frontend/**", ".ankra/**"]   # a pull request runs it only when frontend changes
      push: {}                                 # every push runs it
  - name: backend
    kind: run
    image: golang:1.26
    run: go test ./...
    when:
      paths: ["backend/**"]                    # every event, unless it has a block
      pull_request:
        paths: ["backend/**", ".ankra/**"]
```

A block for an event the pipeline's `on:` does not trigger on, or that the stage's own `when.events` leaves out, can never apply and is a warning under `pipeline_trigger:`. Converted pipelines use these blocks: a GitHub Actions repository's workflows keep their own `on.pull_request.paths` and `on.push.paths` on their stages, and a GitLab rule whose `if:` tests `$CI_PIPELINE_SOURCE == "merge_request_event"` or `== "push"` becomes `when.pull_request` or `when.push`. The recipe for a monorepo is [PR-only checks, full builds on push](/guides/ankra-pipelines#monorepo-pr-only-checks-full-builds-on-push).

### Path sets

A monorepo filters many stages on the same few directories. `path_sets:` names a list of patterns once, and every path list includes it with a `{set: <name>}` entry: `on.push.paths`, `on.pull_request.paths`, a stage's `paths`, `when.paths`, `when.push.paths` and `when.pull_request.paths`. A set can include other sets the same way.

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: shop
path_sets:
  pipeline: [".ankra/**"]
  backend:
    - "backend/**"
    - "!backend/**/*.md"
    - set: pipeline
  frontend: ["frontend/**", "packages/ui/**", {set: pipeline}]
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
defaults:
  network: egress-https
stages:
  - name: checkout
    kind: checkout
  - name: test-backend
    kind: run
    image: golang:1.26
    run: go test ./...
    needs: [checkout]
    paths:
      - set: backend
      - "go.work"
  - name: test-frontend
    kind: run
    image: node:24
    run: pnpm test
    needs: [checkout]
    when:
      pull_request:
        paths: [{set: frontend}]
      push: {}
```

* A set name uses lower-case letters, digits, `-` and `_`, and starts with a letter or digit, like a stage name.
* An entry is a pattern, with the same glob rules as any path list (`*`, `**`, `?`, a leading `!` to exclude), or `{set: <name>}`. A path list can also be a single `{set: <name>}` in place of a list.
* A reference is replaced by the set's patterns, in order, where it stands. The list then means exactly what it would mean with the patterns written there, so the last pattern that matches a file still decides, and a `!` pattern in a set excludes from the list it lands in.
* Ankra expands the sets when it reads the file. Plans, the stored definition and its hash are those of the expanded lists, so a file written with sets and the same file written out by hand are the same pipeline. Paths are not a protected section, so changing a set never needs an administrator's approval.
* `{set: <name>}` is accepted only in the path lists above. In `needs`, `branches`, a cache's or an artifact's `paths` or any other list it is refused.

Refused under `pipeline_path_sets:`: a reference to a set `path_sets:` does not declare (the message suggests the closest name), sets that include each other in a cycle, an invalid set name, a set declared twice, an entry that is neither a pattern nor `{set: <name>}`, and an empty pattern. A set nothing references, directly or through another set, and an empty set are warnings. A set entry spelled so that it can match no file is a `pipeline_paths:` warning that names the set and the entry, once, not again for every list the set is used in.

`ankra pipeline validate` lists every set with its expanded patterns, the sets it includes and the lists that use it. The API answer carries the same as `path_sets`.

### Fields common to every stage

| Field | Type | Default | Meaning |
| - | - | - | - |
| `image` | string | `defaults.image` | The container the stage runs in. Required for `run`, the one kind that runs in the image its definition names: a `run` stage that resolves no image, its own or `defaults.image`, is a fatal violation with the key `pipeline_image:`, so the definition is refused at validation and no run is planned from it, naming the stage. Ignored for `build` (the builder is Ankra's), `checkout` (the git client is Ankra's own, pinned by digest) and `scan` (the scanners' images are Ankra's) - any of them may declare one for readability, but the platform's own image runs regardless. A `verify` stage has no runner on this build: it is warned at validation and skipped by the planner whatever its `image` says (see the `verify` row under [Stages](#stages)), and `pipeline_image:` does not apply to it. What a stage may name is held to the organisation's [image policy](/guides/ankra-pipelines#organisation-ci-settings), matched at a path boundary: a policy prefix ending in `/`, `:` or `@` admits only that boundary. |
| `uses` | string | none | A reusable step, spelled `ankra/<name>`, `custom_tool/<name>` or `repo:<owner>/<name>@<ref>#<path>`. **Refused today**: any `uses:`, however it is spelled, is fatal under `pipeline_uses_unavailable:` with the sentence "Reusable steps are not available yet; write the step as `run:`", until the step library ships. A stage declares `run` or `uses`, not both. |
| `with` | map | none | Inputs to `uses`, and where a `gate` stage's own image-gate configuration lives. Protected. |
| `run` | string | none | The script; required on a `run` stage without `uses` |
| `needs` | list | none | Stages this one waits for. Every name must exist and the graph must be acyclic. |
| `skippable_needs` | list | none | The entries of `needs` this stage may run without. When a listed stage is left out because its own path filter (`when.paths`, or the [event block's](#event-scoped-filters) `paths` for this run's event) matches no changed file, this stage waits on what that stage would have waited on instead of being skipped with it. When the listed stage runs, it is an ordinary need: this stage runs after it, and only if it succeeded. Any other reason the listed stage is skipped - a branch or event filter, a false `if`, the fork policy - still skips this stage, unless this stage's own `if:` calls a status function (see `if`). Every entry must also be in `needs`; an entry naming a stage with no path filter has no effect and is a warning. |
| `paths` | list | none | Makes the stage **affected-only**: it runs only when a changed file matches one of these globs (the `when.paths` dialect: `*`, `**`, `?`, a leading `!` to exclude), or a [path set](#path-sets) the list includes. When none does, the stage is skipped as `path_filter` and **counts as satisfied** for every stage that needs it: each of them waits on what the skipped stage waited on instead of being skipped with it, so a monorepo can leave out the tests of the components a change did not touch and still build, gate and publish. That is the difference from `when.paths`, which skips the stages behind it unless each lists it in `skippable_needs`. A change list that could not be read in full never leaves the stage out. Only `paths` may be the reason it is out: when its `if` is false for the run, or can only be decided at dispatch, the stages behind it are skipped as for any other need. Refused (`pipeline_paths:`): a stage that reads its outputs, a `build` another stage needs, a `checkout`, `gate` or `approval`, a scan a gate names in `require_stages`, and `paths` together with a `when` path filter on one stage. See [Affected-only stages](/guides/ankra-pipelines#affected-only-stages-skip-what-a-change-did-not-touch). |
| `affected` | map | none | Makes the stage **affected-only** from the code's dependency graph instead of, or as well as, globs. `go` lists Go package patterns (`./...`, `./internal/api` relative to the stage's `working_directory`, or import paths; only a trailing `/...` is a wildcard), `pnpm` lists pnpm workspace packages by name (`@acme/web`) or by `./directory`. The stage runs when a changed file is in the dependency closure of what it names, tests included, or matches its `paths` (an OR: list the files the code reads at run time there). Otherwise it is skipped as not affected (class `not_affected`) and counts as satisfied for every stage that needs it, as for `paths`. The run's checkout step reads the graph of the commit it checked out and answers per stage; a stage with no answer runs. Every `paths` refusal applies, and patterns may not carry `${{ }}`. See [Affected from the dependency graph](/guides/ankra-pipelines#affected-from-the-dependency-graph-affected). |
| `if` | expression | none | Runs the stage only when the expression is true; see [Expressions](#expressions). As in GitHub Actions, an `if:` that calls a status function - `always()`, `success()`, `failure()`, `cancelled()`, `skipped()` - replaces the implicit "every need succeeded": such a stage is not skipped because a need was left out of the run. It waits on the nearest stages behind that need that do run, and its condition decides at dispatch, where `needs.<stage>.result` reads `skipped` and `skipped()` is true. |
| `when.branches`, `when.paths`, `when.events` | lists | none | Filters on the event without an expression, decided before any expression context exists. `branches` and `paths` apply to every event that has no [event block](#event-scoped-filters) of its own; `events` always applies |
| `when.push`, `when.pull_request` | `branches`, `paths` | absent | The branch and path filter for that one event, in place of the flat fields; an empty block (`{}`) means the event is unfiltered. See [Event-scoped filters](#event-scoped-filters) |
| `when.tag` | `patterns` | absent | The tag names this stage runs for on a tag push |
| `when.schedule`, `when.manual` | none | absent | Accepted only empty: the event is unfiltered. `when.manual` covers an API dispatch too |
| `matrix` | map | none | Axes (`name: [values]`) plus `include` and `exclude` lists, with GitHub Actions semantics; at most 64 legs after exclusions, and 8 on a restricted fork run, where the surviving legs are truncated in cross-product order with a `plan_fork_budget:` diagnostic. An axis may not be named `include` or `exclude`. |
| `services` | list | none | Names from the `services` block this stage reaches |
| `env` | map | none | Environment variables; names beginning `ANKRA_`, `PATH` and the loader variables, and the builder's own `BUILDKIT*`, `BUILDCTL`, `ROOTLESSKIT` and `DOCKER_CONFIG` are refused |
| `secrets` | list | none | Names from the `secrets` block this stage may read |
| `cache` | list | `defaults.cache` | `key` (expressions allowed, typically `hashFiles`), `paths` under the workspace, optional `restore_keys` (an ordered list of key prefixes), `size` and `fallback` (`volume` or `none`). Each path is restored before the step and saved after it succeeds, scoped to the repository and to the trust of the run. See [Caches](#caches) for how keys are computed, what restores, what saves and how long it is kept. A restricted fork run and a tag run get no shared cache. `size` is held to the organisation policy's `max_cache_size`. The whole block is protected - a cache decides whose earlier output lands in this run's workspace. |
| `artifacts` | list | none | `name`, `paths` and optional `retention_days` (zero takes the organisation default). Every artifact is a presigned upload into the organisation's oldest ready [backup vault](/concepts/backup-vaults) - or, for an organisation that has none, into the Ankra-managed default vault, under a key prefix of its own. The step's execution says which: `pipeline_artifacts: "granted"` or `"granted (Ankra-managed default vault)"`. Only with no ready vault on either side is the step dispatched with no upload grants, recording `pipeline_artifacts: "unavailable: …"`. [Bringing your own vault](/guides/ankra-pipelines#before-your-first-run) decides where the objects live, not whether they are collected. |
| `test_results` | list | none | `format` (`junit`, `go-test`, `pytest` or `playwright`) and `path`, a file or a directory of reports under the workspace. Ankra uploads each report after the step and records every test's outcome, duration and attempts; see [Test results](/guides/ankra-pipelines#test-results). A path with a wildcard is a warning and is not uploaded. Never changes the step's own outcome. |
| `outputs` | map | none | The names the stage writes to `$ANKRA_OUTPUT`, read back onto the step |
| `timeout` | duration | `defaults.timeout`, else 30 minutes | Wall-clock budget; at most 6 hours, longer values are clamped and recorded - 60 minutes on a restricted fork run. Protected, so a head cannot remove its own or the trusted definition's |
| `resources.cpu`, `resources.memory`, `resources.gpu` | quantities | 500m, 1Gi, none | The step's ceilings. `cpu` is the most the step may use: it reserves half of it on its node (never under 100m, or the whole of a smaller ceiling) and uses the rest while the node has it free. `memory` is reserved in full. At most 8 cores, 32 GiB and 4 GPUs - 2 cores and 4Gi on a restricted fork run, where a quantity the planner cannot read is clamped to the ceiling rather than passed through. All three are protected, and `gpu` also needs `runs_on.node_selector`. |
| `runs_on.cluster`, `node_selector`, `tolerations`, `runtime_class`, `arch` | placement | none | Every field is protected |
| `network` | `none`, `egress-https`, `services` | `defaults.network`, else [the kind's default](#the-tier-a-stage-gets-by-default) | `none` denies all egress. `egress-https` allows 53/UDP and 53/TCP to the cluster's own DNS (the `kube-system` namespace, plus `169.254.0.0/16` for NodeLocal DNSCache) and 443/TCP to public addresses only - RFC1918, `169.254.0.0/16`, `100.64.0.0/10`, `fd00::/8`, `fe80::/10` and `fd00:ec2::254` are excluded, so private space and every cloud metadata endpoint are out of reach unless the organisation names the range in [`ci_egress_allowed_cidrs`](/guides/ankra-pipelines#organisation-ci-settings). `services` is deny-all plus the run's own pods and that same DNS rule, and needs at least one service. Anything above `egress-https` is protected. A stage that names no tier takes its kind's default, which is `egress-https` rather than `none` for `checkout`, `build` and `scan`. |
| `shm_size` | quantity | `64Mi` | Size of `/dev/shm` |
| `working_directory` | string | `defaults.working_directory` | Under the workspace mount. A `scan` stage's filesystem scanners honour it too, so a monorepo component scans its own subtree; the reports still land at the workspace root |
| `allow_failure` | flag | `false` | The stage may fail without failing the run |
| `continue_on_error` | flag | `false` | Stages depending on this one still run when it fails. Setting both flags earns a warning: `allow_failure` alone is what keeps the run green. |
| `retry` | block | none | `max_attempts` (counts the first attempt; at most 5), `backoff` (`fixed` or `exponential`), `on` (`failure`, `timeout`, `infra_error`). Validated and carried today, not applied. |
| `gate.approval_roles`, `gate.require_stages` | lists | none | The `gate` block; protected |
| `environment` | string | none | An environment this stage targets; a name the pipeline does not declare earns a warning |

#### The tier a stage gets by default

A stage's egress tier is decided in one place, in one order: the tier the stage names, then `defaults.network`, then the default for the stage's kind.

| Kind | Tier when nothing names one |
| - | - |
| `checkout`, `build`, `scan` | `egress-https` |
| `run` and every other kind | `none` |

Those three cannot do their only job inside the cluster. `checkout` clones the run's source from a remote. `build` resolves the base images its Dockerfile names and pushes what it produces, both against a registry - a build with no egress fails on its first `FROM`. `scan` fetches a vulnerability database, a policy set and a rule registry, one per built-in scanner, and pulls the image its Trivy leg reads. Every other kind, `run` above all, works out of the shared workspace and asks nothing further of the network, so it keeps the deny-all default.

An explicit `network: "none"` on one of the three is still honoured - a pipeline that asks for no egress gets no egress - and the validator raises a `pipeline_network:` **warning** naming what that stage will no longer be able to do, rather than widening the tier back.

### Caches

A stage's `cache` block keeps directories of the workspace from one run to the next: a package store, a module cache, a build cache. Each declared path is kept on its own, under the cache's key.

```yaml theme={null}
cache:
  - key: "pnpm-${{ hashFiles('pnpm-lock.yaml') }}"
    paths: [".ankra-node-cache/pnpm-store"]
    restore_keys: ["pnpm-"]
    fallback: "none"
```

**The key is computed after checkout.** A `${{ hashFiles('...') }}` block becomes the SHA-256 of the files it matches, read in the stage's `working_directory`, so a key over a lock file changes exactly when the lock file does. A pattern is relative and `/`-separated: every directory is a literal name, at most one `**` may stand immediately before the file name, and the file name may use `*`. `hashFiles('pnpm-lock.yaml')`, `hashFiles('go.mod', 'go.sum')` and `hashFiles('**/go.sum')` all work; `hashFiles('**/src/go.sum')`, with a directory after the `**`, and `hashFiles('../go.sum')` do not. One call takes up to eight patterns, and files under `.git` are never hashed. A key the platform cannot read this way is used as written, as one fixed key, and the step's `pipeline_caches` note says so. A `hashFiles` that matches no file adds nothing to the key.

**Restore, before the step.** The exact key wins. Without it, each `restore_keys` prefix is tried in the order written, and the newest stored entry whose key starts with it is restored. A run on the repository's default branch restores only what default-branch runs saved. Any other run - a feature branch, a pull request, a manual run of another ref - looks in its own scope first and then at the default branch's, so a pull request starts warm from main, while nothing a branch saved ever reaches a default-branch run. A restricted fork run and a tag run, or a rerun of one, get no shared cache at all: every declared path starts empty, and the step's `pipeline_caches` note says `caches are not shared with fork runs` or `caches are not shared with tag runs`.

**Save, after the step succeeds.** A step that failed, was cancelled or timed out saves nothing. A key with a `hashFiles` block is saved once: when the exact key was restored, the content is already stored. A key with no `hashFiles` is saved again after every successful step, and the newest save of it wins. A run saves only into its own scope.

**How long it is kept.** An entry nothing restored for `ci_cache_retention_days` (default 14) is removed. Each repository keeps at most 10 GiB of saved caches across both scopes, and the least recently used go first past that; one saved path may be up to 4 GiB, and a larger one is not kept. There is no purge: change the key (`pnpm-v2-...`) to start over, and the old entries age out.

**`fallback`, on an older agent.** Caches are archives on a cluster whose Ankra agent supports them. On an agent that does not, a cache with `fallback: volume` - the default - is one 5Gi volume per path, shared by every run of the same trust scope on that cluster, with the key used as written rather than hashed; a cache with `fallback: none` gets an empty directory for the step instead, and the step's `pipeline_caches` note says so. A shared volume can be attached to one node at a time, so `none` is the safer choice for a cache that is only an optimisation: two overlapping runs on two nodes do not wait on each other's volume. `size` sizes that volume and is not used by archives.

**What Ankra generates.** The `.ankra/pipeline.yaml` a new application's setup pull request commits declares its test stage's package caches this way, with `fallback: "none"`, in directories under `.ankra-` that the scan step skips, and points the toolchain at them through the stage's `env`. A pipeline you already committed is never rewritten; copy the block into it to get the same.

| Toolchain | Key | Paths |
| - | - | - |
| pnpm | `pnpm-${{ hashFiles('pnpm-lock.yaml') }}` | `.ankra-node-cache/pnpm-store`, `.ankra-node-cache/corepack` |
| Yarn | `yarn-${{ hashFiles('yarn.lock') }}` | `.ankra-node-cache/yarn`, `.ankra-node-cache/yarn-global`, `.ankra-node-cache/corepack` |
| npm | `npm-${{ hashFiles('package-lock.json') }}` | `.ankra-node-cache/npm` |
| Go | `go-${{ hashFiles('go.mod', 'go.sum') }}` | `.ankra-go/mod`, `.ankra-go/cache` |
| uv | `uv-${{ hashFiles('uv.lock') }}` | `.ankra-python-cache/uv` |
| Poetry | `poetry-${{ hashFiles('poetry.lock') }}` | `.ankra-python-cache/pip`, `.ankra-python-cache/poetry/cache`, `.ankra-python-cache/poetry/artifacts` |
| Pipenv | `pipenv-${{ hashFiles('Pipfile.lock') }}` | `.ankra-python-cache/pip`, `.ankra-python-cache/pipenv` |
| pip | `pip-${{ hashFiles('requirements.txt') }}` | `.ankra-python-cache/pip` |
| Rust | `cargo-registry-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}` and `cargo-target-` the same | `.ankra-cargo/home/registry`, `.ankra-cargo/home/git`; `.ankra-cargo/target` |

Each key's `restore_keys` is its own prefix (`pnpm-`, `go-`, ...). In a monorepo each component's directories carry the component's directory (`.ankra-node-cache-web/...` for `web/`), because its test stage runs beside its siblings'. A Rust component gets a test stage when it commits integration tests under `tests/` and pins no toolchain file.

### What a step reports about its caches

On a cluster whose agent stores caches as archives in the organisation's vault, each step records one result for all its caches and one entry per cache. `ankra pipeline get` shows the result in the **CACHE** column, and `ankra pipeline get <run> --step <key>` prints the per-cache table. The portal's run timeline shows the same as a chip on the step.

| `cache_result` | Meaning |
| - | - |
| `hit` | Every declared cache was restored, by its exact key or a `restore_keys` prefix |
| `partial` | Some caches were restored and others were not |
| `restore_failed` | No cache was restored and at least one restore failed, so the step ran cold because something broke |
| `miss` | Nothing was stored yet for any declared cache |
| `disabled` | No cache was shared with the step: the cluster has no StorageClass to back a cache volume, or every cache declares `fallback: none` on an agent that does not keep archives |
| `unknown` | Nothing was reported, or the report could not be read. Never read it as a miss |

Each cache has an outcome (`hit`, `restored`, `miss` or `failed`), the bytes downloaded, the time taken, whether the step saved a new archive, and a reason:

| Reason | Meaning |
| - | - |
| `none` | The outcome is the whole story |
| `key_unresolvable` | The key could not be computed: `hashFiles` matched no file, or the working directory could not be read |
| `download_failed` | The vault did not serve the archive |
| `unpack_failed` | The archive downloaded and could not be unpacked or moved into place |
| `unschedulable` | The pod doing the restore was never scheduled |
| `pod_failed` | That pod could not start, or ended without reporting the cache |
| `timeout` | The restore ran out of time |

A failed restore never fails the step: the step starts cold and says so in its log on a line starting `[ankra] cache`.

Reasons, sizes and times come from an agent that reports them. An older agent reports the outcome only, and the reason is empty.

**Where the restore runs.** A stage on the `egress-https` tier with no organisation egress allow-list, whose vault is on public addresses, restores inside the step's own pod before the step starts, so it is scheduled exactly once with the step. Every other stage restores in a separate pod beside the step's, placed on the same node, because a step's network policy covers its whole pod and a `none` or `services` stage must not gain a route to the vault.

### Kind-specific blocks

| Block | Fields |
| - | - |
| `build` | `dockerfile`, `context`, `platforms`, `build_args` (names only), `provenance`, `sbom`, `cache_to`. **`dockerfile` and `context` are both paths from the repository root**, resolved independently of one another - see below. `provenance`/`sbom` ask BuildKit to attest the digest it pushes to the CI staging repository - `publish`'s re-tag does not carry those attestations into the real repository yet (below). |
| `scan` | `scanners` (`semgrep`, `checkov`, `trivy`) and `fail_on`, a map from scanner to a severity. `fail_on` is **read by the gate**: each scan stage the `gate` stage requires has its `fail_on` folded into the gate's policy, per scanner and tighten-only - it can raise that scanner's floor above the organisation's [`ci_image_gate`](/guides/ankra-pipelines#organisation-ci-settings) and a `gate` stage's own `with:`, and can never lower either, so a pull request head may add scrutiny to its own pipeline but not remove the organisation's. A value that is not that scanner's own severity vocabulary - Checkov's `none`, a Trivy image-gate word such as `app` - carries no floor rather than the loosest one. `with.semgrep_config` names the space-separated Semgrep registry packs to run (for example `"p/default p/docker p/golang"`); undeclared, Semgrep runs its own `--config=auto`. Each tool leg declares its own reports as artifacts, so they travel the vault like any other: a report that never uploaded, or that downloaded and would not parse, revises the step from `success` to `infra_error` / `report_unreadable` rather than letting an unread scan count as a clean one. Reports travel to the organisation's own ready vault, or to the [Ankra-managed default vault](/guides/ankra-pipelines#before-your-first-run) when it has none, so an organisation that never registered a vault still scans and still gates; with no ready vault on either side the step is refused before it runs, as `artifact_store_unavailable` (below). |
| `gate` | No block of its own beyond `gate.approval_roles`/`gate.require_stages` (above) - a `kind: gate` stage's `with.image_gate` (`app`, `all` or `off`, case-insensitive, the same vocabulary as [`ci_image_gate`](/guides/ankra-pipelines#organisation-ci-settings)) and `with.severity` (`critical`, `high`, `medium` or `low`) may only make the organisation's policy *stricter*, never looser; `with.ignore_unfixed` (excludes a Trivy finding with no published fix) is floored the same way by the organisation's own [`ci_ignore_unfixed`](/guides/ankra-pipelines#organisation-ci-settings), which is `true` by default: an organisation that sets it `false` has every unfixed finding keep blocking, and a stage's `with:` may then only move toward `false` as well. A gate judges the findings the run *persisted*, and a required scanner that recorded none fails it by name rather than passing as clean - so a gate cannot pass at all in an organisation whose scan reports had nowhere to be stored. |
| `publish` | `tags`: extra tags the published digest is given in the application's repository beside `sha-<7>` - a moving `latest`, a version such as `"0.2.${{ ankra.run.number }}"`. Each is a manifest re-tag of the one digest, in place: no blob is pushed again, and a tag that already points at the digest is left alone. Expressions resolve at plan time; a literal must be a tag a registry accepts (up to 128 letters, digits, `_`, `.`, `-`, not starting with `.` or `-`), and an entry listed twice or empty is refused at validation. The stage's `when:` governs the extra tags with the stage: a publish skipped for the branch writes none. A registry that refuses one of them - a tag-immutability rule on the project, say - fails the step naming the tag, so a `latest` that did not move never reads as published. The step's outputs carry them as `image_tags`. `with.image` is accepted and validated but not read: the real target is the organisation's own registry, resolved for the run's application and component exactly as `build`'s push target was - never a value a stage can name. It refuses by name unless a `gate` upstream concluded successfully and recorded the same digest `build` pushed, so the whole scan-to-registry chain rests on findings the run managed to persist. `promote_from: pull_request` lets a push publish the digest a pull request run already built and tested for exactly the same tree, instead of building and testing it again; see [Promote a tested image instead of rebuilding](#promote-a-tested-image-instead-of-rebuilding). It is a protected section. |
| `deploy` | `artifact` (the `publish` stage whose digest is deployed, by name or as `${{ needs.<stage>.outputs.image_digest }}`; it must be inside the stage's `needs`), `release` (equal to `metadata.name` in the bundle's `ankra-release.yaml`), `targets.match_labels`. The environment is the stage's own `environment`. The artifact is a release bundle: a `build` stage with `bundle.path` (a workspace directory) and `bundle.manifest` (its `ankra-release.yaml`) packs one instead of building an image. Protected. |
| `preview` | `database.enabled`, `database.extensions`, `database.seed_from_restore_point`, `migrate`, `ingress_path` |
| `verify` | Exactly one of `probe` (`url`, `status`, `timeout`), `smoke` (`image`, `run`), `load_test` (`script`, `virtual_users`, `duration`, `thresholds`), `assert_promql` (`query`, `comparison`, `threshold`, `for`) or `restore_verify` (`restore_point`, `queries`) |
| `agent` | `goal` (required), `tool_profile`, `mode`, `budget.tool_calls`, `budget.turns`, `budget.minutes`, `context` |
| `approval` | `roles` (required), `min_approvals`, `timeout`, `message` |
| `webhook` | `url` (required), `method`, `wait_for_callback`, `timeout` |
| `external` | `provider` (required), `workflow`, `inputs` |

#### Promote a tested image instead of rebuilding

A merge to the default branch normally builds, scans, tests and gates the merged commit again before `publish` releases it, even when a pull request run already did all of that for the same files. `publish.promote_from: pull_request` skips the repeat:

```yaml theme={null}
  - name: "publish"
    kind: "publish"
    needs: ["gate", "e2e"]
    when:
      events: ["push"]
    publish:
      promote_from: "pull_request"
```

When a push arrives, Ankra reads the git tree of the pushed commit and looks for a pull request run of the same repository that recorded the same tree. The push is promoted only when all of these hold:

* A pull request run tested exactly that tree. A squash merge of a pull request that was up to date with its base has the tree the pull request tested; a merge of one that was behind does not, and builds in full - unless the [merge train](/guides/ankra-pipelines#the-merge-train-test-every-pull-request-as-it-will-merge) merged it, whose car run tested exactly the merged tree.
* Every stage the push's `publish` needs passed in that run, on its newest attempt, and resolved to the same stage definition. A build argument or a value drawn from the event (`ankra.ref`, `ankra.sha`) makes the image differ, so the push builds.
* A stage the run skipped counts only when the push would have skipped it too. A stage with [`affected:`](/guides/ankra-pipelines#affected-from-the-dependency-graph-affected) that the run skipped as not affected counts when every file the push changes is among the files that run's dependency graph was asked about: the tree is the same, so a change the graph already showed cannot reach the stage still cannot. A push that changes a file the run did not, such as one push that carries two merges, builds in full, and its own checkout reads the graph. A merge train car is asked about its pull request's files, which are the files its merge changes, so a train merge promotes past the skip. A stage a `paths:` filter left out needs no rule: the push applies the same filter to its own change, so either it leaves the stage out too, or its change reaches the stage and the push builds. Any other skip, such as a false `if:`, never counts.
* The run's head is in the repository itself. A fork's run is never promoted.
* Both runs executed under the same approved [authority](/guides/ankra-pipelines#logic-is-open-authority-is-closed), and the run's `gate` judged exactly the digest its `build` reported.
* The run was queued within the last 72 hours.
* Every stage of the push is `publish` or a stage `publish` needs, and every `publish` stage declares `promote_from`.

A promoted push runs `publish` alone. It re-tags the pull request run's gate-approved digest as the push's own `sha-<7>` in the application's repository, and push-to-deploy rolls it out exactly as after a full run. Every stage it skipped shows as skipped on the run, naming the pull request run that passed it, or that found it not affected. Anything short of the list above builds and tests the push in full, as without the key, and the run records why.

Deploys still move forward in push order. If an older merge that built in full publishes after a newer promoted one, it gets its own `sha-<7>` but deploys nothing, and a moving tag such as `latest` stays on the newer release.

`promote_from` is a protected section: an administrator approves it with the rest of the default branch's definition, and a pull request cannot turn it on for itself. The promoted image is the one the pull request run built, so its build provenance names the pull request's head commit, which carries the same tree.

#### Where a build's paths are resolved from

`context` and `dockerfile` are **two independent paths from the repository root**. `dockerfile` is *not* relative to `context` - the rule `docker build -f` and GitHub's `docker/build-push-action` hold, and the opposite of Docker Compose's `dockerfile:`. So a component in a monorepo names both in full:

```yaml theme={null}
- name: "build-backend"
  kind: "build"
  build:
    context: "backend"
    dockerfile: "backend/Dockerfile"
```

Declaring `context: "backend"` with `dockerfile: "Dockerfile"` points the build at the repository *root's* `Dockerfile`. If there is none, the step fails with exit status `78` and the message `The Dockerfile Dockerfile is not in the repository at this commit` - which names the path it looked for, and is the quickest way to see that the path was read from the root.

Omitting `dockerfile` entirely reads `Dockerfile` at the repository root - except in a pipeline Ankra generated for an application, where the field is already filled in with the path the application's analysis resolved.

Either path may only address files inside the checkout: an absolute path, or a relative one that climbs out with `..`, is refused. That refusal is raised when the step is rendered for dispatch, not when the definition is stored - so the definition saves cleanly, and the run instead concludes with the step refused for asking for host privilege, against the field `runs_on` rather than against the path. A build step refused that way while declaring no `runs_on` of its own is worth re-reading `context:` and `dockerfile:` for.

A build step does not read the checkout the run's other stages share: it runs in its own namespace and fetches the commit itself, which is why its paths are repository paths and not paths into the run's workspace.

### What every step carries

A step's container mounts the run's workspace at `/workspace` and runs with these variables set: `ANKRA_RUN_ID`, `ANKRA_STEP_ID`, `ANKRA_STEP_KEY`, `ANKRA_STEP_KIND`, `ANKRA_ORGANISATION_ID`, `ANKRA_CLUSTER_ID`, `ANKRA_REPOSITORY_ID`, `ANKRA_APPLICATION_ID`, `ANKRA_HEAD_SHA`, `ANKRA_REF`, `ANKRA_IS_FORK` and `ANKRA_WORKSPACE`. `ANKRA_OUTPUT` names a file on a memory-backed volume: append `key=value` lines to it (at most 64 KiB) and they are recorded as the step's outputs when the script exits, whether it succeeded or not. A declared secret or credential the step may read is delivered as a file under `/run/agent-secrets`, named after the binding: the agent reveals it once, at step start, by calling back with its own session token, so the value never rides in the payload the platform sent or in a log line. The directory is mounted only when the step has at least one file binding, so a step with none has no `/run/agent-secrets` to list rather than an empty one. A `secrets` binding sourced `app_env_secret`, `org_variable` or `registry` resolves; `from: credential` validates but is not deliverable yet. A `credentials` binding sourced `git` or `registry` resolves; `cloud` and `object_storage` are refused by name until the run has its own scoped identity.

### A registry login in a step

A binding sourced `registry` is delivered as a Docker `config.json` - `auths` keyed on the registry's host, carrying the username and password Ankra resolved - rather than as a bare token. `from: registry` naming no `key` is the organisation's own Ankra registry, logged in as the organisation's CI robot, which pushes and pulls across the whole organisation project; a `key` names another connected registry instead. `ankra application publish-readiness` prints the host and project the organisation's registry resolves to.

The file is named after the binding like any other, so it lands at `/run/agent-secrets/<name>` and not at a path a container tool searches by default. `DOCKER_CONFIG` is reserved - along with `PATH`, `HOME`, `TMPDIR`, `BUILDKIT_HOST` and the other variables that decide what a step actually executes - so a pipeline cannot point a tool at the directory with `env`, and declaring one of them refuses the step rather than being overwritten silently. Every tool that reads a Docker config has to be given the path explicitly: `helm --registry-config`, `oras --registry-config`, `crane --docker-config`, `skopeo --authfile`.

That is the whole of publishing a Helm chart to the organisation's registry from a pipeline, which `build` and `publish` do not cover - those stages carry an image digest, not a chart:

```yaml theme={null}
secrets:
  - name: registry_login
    from: registry

stages:
  - name: publish-chart
    image: alpine/helm:3.16.3
    network: egress-https
    secrets: ["registry_login"]
    run: |
      helm package charts/myapp --destination /tmp
      helm push /tmp/myapp-*.tgz \
        "oci://registry.ankra.cloud/org-${ANKRA_ORGANISATION_ID}" \
        --registry-config /run/agent-secrets/registry_login
```

The image is named on the stage because a pipeline's `defaults.image` is its build toolchain and ships no `helm`, and the tier is named because a `run` stage defaults to `network: none` - without it the push fails on a connection timeout rather than on the login. A registry on a private address needs its range in [`ci_egress_allowed_cidrs`](/guides/ankra-pipelines#organisation-ci-settings) as well.

`secrets` is a protected section, so the binding a run receives is the one on the **default branch's approved definition**. A pull request that adds the declaration plans its logic from its own head sha but its authority from the default branch, so that first run reaches the stage with no login and the push fails to authenticate. Merge the declaration, then push the chart.

### A git credential in a step

A `credentials` binding sourced `git` is delivered as one line of JSON - not as a bare token, and not as a `git-credentials` line:

```json theme={null}
{"provider":"github","instance_url":"","username":"x-access-token","token":"<token>","expires_at":"<RFC 3339 time>"}
```

The keys are exactly these five, lower case and unnested, and the file holds that one compact line with no trailing newline. `provider` is the repository's provider: `github`, `gitlab` or `bitbucket_cloud`. `token` is a short-lived token for the run's own repository: a GitHub App installation token when an installation covers it, otherwise the stored credential the binding's `name` points at. `username` is the one the provider expects beside it (`x-access-token` on GitHub, `x-token-auth` on Bitbucket Cloud). `instance_url` is empty for a provider's public host and names a self-hosted instance otherwise. `expires_at` is a UTC RFC 3339 time for a minted token and empty for a stored credential, so a script should not depend on it. The file lands at `/run/agent-secrets/<as>`, or at `/run/agent-secrets/<name>` when the binding has no `as`, and the step's own user can read it. It is written once, at step start, and is not refreshed.

Git reads none of that by itself. Pointing `git-credential-store` at the file (`credential.helper 'store --file /run/agent-secrets/<as>'`) does not work: the store helper reads `https://user:token@host` lines, finds none, and git falls back to prompting, which a step cannot answer. The fetch exits 128 with `could not read Username for 'https://github.com': terminal prompts disabled`. Give git a helper that reads the JSON instead, and pass it on the command line: it then applies to that one command, and nothing is written under a `HOME` on the step's read-only root filesystem.

```yaml theme={null}
credentials:
  - name: github-app-myorg
    from: git
    as: repo_git

stages:
  - name: checkout
    kind: checkout
  - name: compare-with-main
    kind: run
    image: alpine/git:2.54.0
    network: egress-https
    needs: ["checkout"]
    run: |
      cat > /tmp/git-credential-ankra <<'EOF'
      [ "$1" = get ] || exit 0
      host=""
      while IFS='=' read -r key value; do
        [ -z "$key" ] && break
        [ "$key" = host ] && host="$value"
      done
      [ "$host" = github.com ] || exit 0
      file=/run/agent-secrets/repo_git
      token=$(grep -o '"token": *"[^"]*"' "$file" | cut -d'"' -f4)
      username=$(grep -o '"username": *"[^"]*"' "$file" | cut -d'"' -f4)
      [ -n "$token" ] || exit 0
      printf 'username=%s\npassword=%s\n' "${username:-x-access-token}" "$token"
      EOF
      git -c safe.directory=/workspace \
        -c credential.helper= -c credential.helper='!sh /tmp/git-credential-ankra' \
        -C /workspace fetch --no-tags origin main
```

`safe.directory` comes first because git refuses the workspace without it. Every step runs as an unprivileged user (uid 65532) while the workspace's mount directory belongs to root, so git stops with `detected dubious ownership in repository at '/workspace'` and exits 128 before it reaches the network or the helper. That applies to every git command in the stage, including read-only ones: a `git rev-parse origin/main` or `git log` without it fails the same way, which reads like a missing ref. The `checkout` stage trusts the directory for itself, and that setting is not carried to later stages either.

The empty `credential.helper=` clears any helper the image configures, and the host check keeps the token from being offered to any other host git asks about - a submodule URL, say. Replace `github.com` with your provider's host for a self-hosted instance. The image only needs `sh`, `cat`, `git`, `grep` and `cut`, and has to be inside the organisation's image policy. The tier is named because a `run` stage defaults to `network: none`, where the fetch fails on the connection rather than on the login. Git exits 128 for an untrusted workspace, a blocked connection and a missing login alike, so check them in that order.

The `checkout` stage's own credential helper is not available to later stages, on purpose. It is configured under a `HOME` on that step's own `/tmp`, which no other step mounts, so a later step cannot inherit it or rewrite it for a checkout that runs after it. What later steps do share is the workspace, whose `origin` remote is the plain clone URL with no credential in it. A step that fetches from `origin` again needs its own `credentials` binding, `safe.directory`, and a helper like the one above.

`credentials` is protected like `secrets`: a pull request run receives the block on the default branch's approved definition, not the one on its own head.

## Expressions

Any string field may embed expressions between `${{` and `}}`; the text inside is [CEL](https://cel.dev). Evaluation is deterministic and performs no I/O: everything an expression can reach arrives in its context, and `hashFiles` is served by the agent, which has the workspace.

| Context | Paths |
| - | - |
| `ankra` | `organisation`, `repository.owner`, `repository.name`, `repository.provider` (the stored provider: `github`, `gitlab` or `bitbucket_cloud`), `application` (empty for a bare repository), `ref` (the full git reference the run identifies itself by: `refs/heads/main` for a push, `refs/tags/v1.2.0` for a tag, and `refs/pull/<n>/head` for a pull request, so a concurrency group keyed on it serialises each pull request on its own; the base branch a pull request targets is `event.ref`), `sha`, `sha_short` (7 characters), `run.id`, `run.number`, `environment.name`, `environment.url`, `environments` (list of strings: the application environments a push of the run's branch deploys to - see [Where a push deploys](#where-a-push-deploys)), `urls.run`, `urls.portal` |
| `event` | `kind` (`push`, `pull_request`, `tag`, `schedule`, `manual`, `api`), `provider` (`github`, `gitlab`, `bitbucket` - Bitbucket Cloud is `bitbucket` here, where `ankra.repository.provider` spells it `bitbucket_cloud`), `pull_request.number`, `pull_request.is_fork`, `pull_request.head_repo`, `ref`, `before_sha`, `changed_files` |
| `inputs.<name>` | The validated dispatch inputs |
| `matrix.<name>` | The current matrix leg |
| `vars.<name>` | Organisation, cluster and environment variables |
| `env.<NAME>` | Environment variables in scope for the step |
| `steps.<key>.outputs.<name>`, `steps.<key>.outcome` | Concluded steps of this run |
| `needs.<stage>.outputs.<name>`, `needs.<stage>.result` | The stages this one depends on |
| `secrets.<NAME>` | `true` when the secret is declared - never its value, so no expression can leak one into a log line or a check-run summary |

Functions: `hashFiles(pattern, …)`, `contains(haystack, needle)` (substring or list membership), `startsWith`, `endsWith`, `fromJSON`, `toJSON` (compact, keys sorted), `format(template, args…)` with GitHub-style `{0}` placeholders, `join(list)` and `join(list, separator)`, and the status functions `always()`, `success()`, `failure()`, `cancelled()` and `skipped()`. The CEL standard library - `size`, `matches`, the bounded `all`/`exists`/`map`/`filter` macros, arithmetic and comparisons - is available on top.

Rules worth knowing:

* A stage condition is compiled at plan time against a schema without `steps.*`, so a reference to a step that has not run is deferred rather than resolved to nothing. The dispatcher evaluates the same condition with the run's concluded steps in scope, and interpolates the same run's `${{ }}` references into `run`, `env.*`, `with.*`, `image`, `working_directory` and the stage's `outputs:`. Dispatch is the last evaluation point there is, so unlike plan time nothing unresolved is carried through verbatim: a field that still will not resolve concludes the step `infra_error` naming it, rather than handing a container a literal `${{ }}`.
* **A step key nobody declared resolves to empty, not to an error.** The expression schema declares *roots*, not key sets, and a step key is a matrix-expansion product the validator cannot know - so `${{ steps.buidl.outputs.tag }}` interpolates to an empty string. Check the key against the stage names you wrote; nothing else will.
* `has()` is refused on `inputs`, `matrix`, `vars`, `env`, `steps`, `needs` and `secrets`: an absent key on those roots resolves to the zero value, so a converted `env.DEPLOY == 'true'` keeps its meaning when the variable is unset. Compare the value instead. `has()` still works on `ankra` and `event`, whose paths are fixed.
* Converted GitHub expressions keep working - single-quoted strings, `==`, `!=`, `&&`, `||`, `!`, the functions above, and the `steps`, `matrix`, `inputs`, `env` and `needs` references map one to one. A reference to the `github`, `runner`, `job` or `strategy` context is a diagnostic naming the Ankra equivalent (`github.sha` is `ankra.sha`, `github.event_name` is `event.kind`). Two deliberate departures: `toJSON` emits compact JSON, and comparisons follow the typed rules of CEL, so `'1' == 1` is a type error rather than true.
* A template is at most 8,192 bytes with at most 64 expressions; an expression is at most 2,048 bytes and 24 levels deep; the evaluation cost is capped. Each bound is refused with a fixed sentence at validation time.

### Where a push deploys

`ankra.environments` is the sorted list of application environment names that a push of the run's branch deploys to, decided by each environment's [branch rule](/guides/application-environments). It is empty for every run that is not a push or a re-run of one, for a run of a repository that has no application, and when no environment with push to deploy on follows the branch. The list is resolved once, when the run is triggered, and stored on the run, so every evaluation in one run agrees. A re-run of a push resolves its own list when it is triggered, from the rules and push to deploy switches at that moment. The runs API returns it as `target_environments`.

```yaml theme={null}
stages:
  - name: smoke-production
    kind: run
    if: "'production' in ankra.environments"
    run: ./scripts/smoke.sh https://app.example.com
  - name: seed-demo-data
    kind: run
    if: "'development' in ankra.environments"
    run: ./scripts/seed.sh
```

Use `ankra.environments` for steps that depend on where the image is going. Steps that change with the branch itself still belong in `when.branches`.

## Triggers and reasons

Every event that reaches the trigger is decided in order, and the answer is recorded as one of these tokens. Where a run row is written, `ankra pipeline list` shows it; where none is, the reason is in the platform's logs and metrics.

| Reason | Meaning | Run recorded |
| - | - | - |
| `enqueued` | One run was queued | Yes |
| `already_queued` | A run for this event is still queued; the redelivery joined it | No new run |
| `already_recorded` | A run for the same commit, trigger, reference and pull request exists inside the recent-run window - running, or concluded skipped; the redelivery joined it | No new run |
| `skipped` | The trigger matched but its branch, tag or path filter excluded the event, or a pushed commit carries a [skip marker](#skipping-a-push-with-skip-ci) the organisation honours on that branch | Yes, concluded with outcome `skipped` and the planner's sentence, or error class `skip_marker` and a sentence naming the marker |
| `refused` | A dispatch the planner refused - an undeclared `on.manual`, an input outside its declared type | No; the diagnostics go back to the caller |
| `repository_not_onboarded` | The repository is not connected to a pipeline | No |
| `no_ci_cluster` | The organisation has no CI cluster and no AI staging cluster | No, for a provider event; a dispatch still gets its run row |
| `no_definition` | The repository has no stored definition | No |
| `trigger_not_declared` | The definition's `on:` block does not declare this event kind | No |
| `fork_policy_pending` | Reserved in the metric's stable label set; no longer returned in the ordinary case. A pull request whose head lives in a fork, or whose provenance could not be established, is enqueued and runs restricted today - see [Forks](/guides/ankra-pipelines#what-a-step-runs-as) | No |

Dispatches (`manual`, `api`, `agent`, `rerun`) are exempt from the recent-run deduplication: a person who presses run twice asked for two runs.

A dispatch is also the one entry point whose commit no provider delivery has already proven, so `POST …/pipeline-runs` resolves the `ref` it was given - or the repository's default branch - against the repository's own host and accepts a supplied `head_sha` only when it is that reference's current tip or, on GitHub, a provable ancestor of it. Anything else refuses the dispatch before a run row exists, and so does a host that could not be asked at all. A `rerun` is exempt: its commit is one Ankra itself recorded on the original run, which is what lets a fork pull request's run be repeated when the commit lives on no ref of this repository.

Inside a run, a stage that is not planned carries a skip reason: `kind_unavailable` (the stage's kind has no executor on this build - decided first, because it is a fact about the stage rather than about the event), `event_filter`, `branch_filter`, `path_filter`, `schedule_subset`, `condition_false`, `condition_unreadable` (a condition nobody can read is not a condition that passed), `fork_policy`, `dependency_skipped`, `deploy_untrusted_event` (a `deploy` stage in a pull request run, or in a run of a head the repository does not own) or `promoted` (a push run publishes the image a pull request or merge train run already built and tested for the same tree, so this stage, which that run passed, is not run again; see [promotion](#promote-a-tested-image-instead-of-rebuilding)). A run refused as a whole carries one fixed sentence, for example "Every stage this pipeline declares is filtered out for this event, so the run would do nothing." or "A stage fans out over more matrix legs than the number one run may plan."

A step that *was* planned can still be concluded without running. At dispatch, a deferred `if:` that evaluates false concludes the step `skipped` with the condition in the message, and a `${{ }}` reference dispatch cannot resolve concludes it `infra_error` naming the field. A step still `pending` once its run has outlived the sum of every step's `timeout` is concluded `infra_error` with error class `step_stranded`, never retried. A `kind: scan` step is refused at dispatch with error class `artifact_store_unavailable` - "This step's reports need a ready backup vault in the organisation, and there is none." - when its reports would have nowhere to go: no ready vault in the organisation *and* no Ankra-managed default vault designated. An organisation with no vault of its own ordinarily falls back to the platform's, so this is now the rare case rather than the first-run one. A `scan` step can also be concluded and then *revised*: one that succeeded but whose declared report Ankra could not read becomes `infra_error` with error class `report_unreadable`, because an unread scan is not a clean one - see [When something fails](/guides/ankra-pipelines#when-something-fails).

## Time saved

Every run records the CI time it did not spend because of a path filter, the dependency graph or a promoted publish, with an estimate for each piece of work it skipped. Only runs planned after this was released have a record. Older runs show nothing.

### What counts

| Saving | `reason` |
| - | - |
| A stage left out by a path filter (`when.paths`, the event block's `paths`, or the stage's affected-only `paths:`) | `path_filter` |
| A stage skipped because a stage it needs was left out by a path filter. `cause_stage` names that stage | `dependency_skipped` |
| A step a promoted publish (`publish.promote_from`) did not run again | `promoted` |
| A step skipped as not affected by its stage's [`affected:`](/guides/ankra-pipelines#affected-from-the-dependency-graph-affected) dependency graph | `not_affected` |
| A whole run that `on.<event>.paths` excluded | `run_paths_excluded` |

A stage skipped by a branch filter or a condition is not counted, because it would not have run whatever the change touched. An `on_failure` stage is never counted.

### How a saving is estimated

Each estimate is made when the run is planned or skipped, or for a `not_affected` step when the step is skipped, from the history of the same repository.

| Saving | Estimate | `basis` |
| - | - | - |
| A skipped stage | The median time of the stage's newest 20 successful runs, read from the repository's newest 300 concluded runs. A matrix stage adds up its legs | `stage_history` |
| A step skipped as not affected | The same median: from the stage's history when the stage has one step, or from the leg's own newest 20 successful runs for a matrix leg | `stage_history` or `step_history` |
| A promoted step | The time the same step took in the run it was promoted from. When that run no longer has the step, or the step did not succeed there, the median of its own newest 20 successful runs: `step_history` for a matrix leg, `stage_history` for a stage with one step | `promoted_source_run`, else `step_history` or `stage_history` |
| A whole run | The median total step time of the newest 20 successful runs of the same trigger | `run_history` |
| Work with no usable history | Unknown. `saved_seconds` is null and the saving is not added to any total | `no_history` |

The time is runner time, the seconds the skipped steps would have run added up. It is not wall-clock time, so two skipped stages that would have run side by side count twice. CPU-minutes are the requested CPU times that duration. A sample whose steps did not all carry a CPU request is left out of the CPU median, and CPU-minutes are null when no sample carried one. A promoted step estimated from its source run has CPU-minutes when the step carried a request there.

### Where to read it

* `ankra pipeline get <run-id>` prints a `Time saved` line under the run's steps, with one line per saving. It prints nothing for a run with no savings. With `-o json` or `-o yaml` the run's record is added as the `time_saved` field. A run with no record, including one planned before this was released, carries a `time_saved` object with `saved_seconds` 0 and an empty `savings` list. `time_saved` is null only when the platform does not serve the route yet or the read failed, and a failed read is reported on stderr.
* `ankra pipeline time-saved` prints the total for the organisation over the last 30 days. `--window 7d` reads the last 7 days, and `--application` or `--repository` reads one application or repository.
* The API has three routes. `GET …/pipeline-runs/{run_id}/time-saved` reads one run. `GET …/pipeline-time-saved?window=30d` reads one repository or application. `GET /api/v1/org/pipelines/time-saved?window=30d` reads the organisation. `window` is `7d` or `30d` and defaults to `30d`.

## Validation

```bash theme={null}
ankra pipeline validate --application my-service
ankra pipeline validate path/to/pipeline.yaml --application my-service
```

The command reads `.ankra/pipeline.yaml` (or the file you name), validates it, and plans it for a synthetic push to the default branch and a synthetic pull request - and a synthetic `v1.0.0` tag when the pipeline declares `on.tag` - printing for each the steps that would run, the stages that would be skipped with their reason, and every diagnostic, then a table of every stage against every event: `run`, or `skip` with the reason. A path filter cannot decide without a diff, so it passes with a diagnostic; `--changed-file <path>` (repeatable) plans the push and the pull request as if those files changed, so path filters - flat or [event-scoped](#event-scoped-filters) - decide for real (`changed_files` in the API body):

```bash theme={null}
ankra pipeline validate --application my-service --changed-file frontend/app.ts --changed-file .ankra/pipeline.yaml
```

Its exit code is non-zero when the severity is `fatal`. Without a file and without a stored definition there is nothing to validate. The same validator answers `POST …/pipeline/validate` on the API and the `cicd_validate_pipeline_yaml` tool in chat, which needs no repository at all.

Every planned step of that dry run carries the [network tier it resolved to](#the-tier-a-stage-gets-by-default) - `network` on each node of the DAG - so a definition that names no tier anywhere still says what each of its stages will be allowed to reach. The field is on the API's answer today; the CLI's own step line prints the step key, the stage and the kind only.

A result has a severity - `ok`, `advice` (the pipeline does what it says, and there is a better way to say it), `warn` (the pipeline runs, but not the way its author probably meant; reported on the pull request, never blocking) or `fatal` (the pipeline cannot be planned) - and a list of violations, each prefixed with a fixed key. Only `fatal` stops a run, and only `fatal` makes the command exit non-zero:

| Key | Covers |
| - | - |
| `pipeline_parse:` | A document that is not readable YAML, or whose shape the decoder could not take |
| `pipeline_unknown_key:` | A key this reference does not define, at the top level or in any block (warning). The sentence names the line, the key, the block it sits in and - when the key is close enough to be a slip rather than an invention - the field it was probably meant to be. The key is ignored, so the value written against it has no effect |
| `pipeline_kind:` | A wrong `apiVersion` or `kind` |
| `pipeline_metadata:` | A missing `metadata.name` |
| `pipeline_stages:` | The stage list and stage identity: missing or duplicate names, an unusable name, both `allow_failure` and `continue_on_error` (warning) |
| `pipeline_stage_kind:` | A kind outside the vocabulary, or a kind missing what it requires (`run` without `run` or `uses`, `approval` without roles, `agent` without a goal, `webhook` without a URL, `external` without a provider, `verify` without a sub-block) |
| `pipeline_executor:` | A stage whose kind has no executor on this build (warning). The sentence names the stage, the kind and the wave that ships its executor; the planner skips that stage with reason `kind_unavailable` |
| `pipeline_uses:` | A `uses` reference not spelled as one of the three forms |
| `pipeline_uses_unavailable:` | Any `uses` at all, correctly spelled or not, until the step library ships (fatal) |
| `pipeline_needs:`, `pipeline_cycle:` | A `needs` entry naming no stage; a stage needing itself; a cycle |
| `pipeline_trigger:` | The `on:` block: an unknown `fork_policy`; `cancel_in_progress` without a group (warning) |
| `pipeline_concurrency_queues_behind:` | A `concurrency.group` that varies per branch or pull request with no `cancel_in_progress` (advice), so a newer commit waits for the older run - see [Newest commit wins](/guides/ankra-pipelines#newest-commit-wins) |
| `pipeline_concurrency:` | A `concurrency.group`, `cancel_in_progress` or `cancel_queued` expression the planner cannot settle for one of the kinds of run the definition can start (warning): a run of that event is planned with no group, or with that flag `false`. Reported once per cause, naming every event it fails for. See [A concurrency policy per event](#a-concurrency-policy-per-event) |
| `pipeline_schedule:` | A cron that is not five numeric fields; a schedule naming a stage that does not exist. Warnings: a schedule's `stages` leaving out a stage one of them needs; an entry that an earlier entry with the same cron always wins over (the earlier one names the same branch, or no branch) |
| `pipeline_inputs:` | Input names, types, a `choice` without an enum, a default outside the enum |
| `pipeline_secrets:`, `pipeline_credentials:`, `pipeline_permissions:` | An unknown source, a duplicate name, an unknown permission level, a stage naming an undeclared secret |
| `pipeline_services:` | A service without an image; a stage naming an undeclared service |
| `pipeline_expression:` | An unterminated `${{` in `if`, `run`, `uses`, `image`, `timeout`, `with` or `env` (a stray `}}` is not reported: scripts legitimately carry them) |
| `pipeline_matrix:` | An axis with no values; an exclusion on an axis that does not exist (warning) |
| `pipeline_network:` | A tier outside `none`, `egress-https`, `services`; an explicit `network: "none"` on a `checkout`, `build` or `scan` stage (warning), naming what that stage can no longer reach |
| `pipeline_retry:` | More than 5 attempts, a negative count, an unknown backoff or condition |
| `pipeline_artifacts:` | An artifact without a name or paths; a negative retention (warning); an unknown test result format or a missing path |
| `pipeline_environment:` | A stage targeting an environment the pipeline does not declare (warning) |
| `pipeline_paths:` | An `affected` block that names no package, a pattern it cannot read (an expression, a path above the repository root, a wildcard other than a trailing `/...`), or relative patterns under a `working_directory` that carries an expression (fatal); an `affected` stage in a pipeline with no checkout stage (warning: the graph is never read, so the stage always runs). An [affected-only](#fields-common-to-every-stage) stage (`paths` or `affected`) on a shape where "satisfied" would be untrue: a stage reading its outputs (`needs.<stage>.outputs`, `steps.<stage>.outputs`, a deploy whose `artifact` names it), a `build` another stage needs, a `checkout`, `gate` or `approval`, a scan a gate requires, an empty pattern, or `paths` beside a `when` path filter (fatal). Warnings: an affected-only scan no gate requires, an affected-only `deploy`, `publish` or `preview` that another stage needs, a `skippable_needs` entry the needed stage's own `paths` already covers, and any path pattern, in a path list or a [path set](#path-sets), spelled so that it can match no file (a leading `./` or `/`, a trailing `/`, a backslash or surrounding whitespace). A path set's entry is reported once, at `path_sets.<name>[i]` |
| `pipeline_path_sets:` | The [`path_sets:`](#path-sets) block and its `{set: <name>}` references: a reference to an undeclared set, sets that include each other in a cycle, a reference in a list that is not a path filter, an invalid or duplicate set name, an entry that is neither a pattern nor a reference, an empty pattern (fatal). Warnings: a set nothing references, an empty set |
| `pipeline_full_run:` | A [`full_run`](#setting-path-filters-aside) block naming an event no run is planned as, or naming no event and no branch, which sets every path filter aside on every run (both warnings) |
| `pipeline_build_component:` | A `build.component` that is not a valid component name; one on a stage that is not `kind: build` (warning). Validated against an application: a build stage that belongs to no component, a `build.component` the application does not record, and two build stages that publish to the same repository - fatal when both always run, a warning when one of them runs only under a condition. See [Which component a build belongs to](/guides/ankra-pipelines#which-component-a-build-belongs-to) and the application's [declared components](/reference/application-descriptor#components) |

The planner adds diagnostics with `plan_` keys (`plan_trigger:`, `plan_paths:`, `plan_paths_set_aside:`, `plan_matrix:`, `plan_condition:`, `plan_fork:`, `plan_fork_budget:`, `plan_concurrency:`, `plan_interpolation:`, `plan_timeout:`, `plan_needs:`, `plan_spec:`), and the step renderer records what it decided on incomplete information: `image_policy_open` when the organisation set no image policy, `resources_defaulted`, `service_without_readiness`, `service_undeclared`, `build_without_registry_auth`, `registry_push_withheld`, `build_namespace_workspace` and `multi_platform_build`. A step the renderer refuses outright - an image outside the policy, more compute than one step may have, a missing timeout, a `services` tier without services, host privilege - is a fixed sentence naming the field, and the same refusal at dispatch time is what a step that never started shows.

## A complete example

This is the pipeline Ankra's own documentation repository is written against - a bare repository with nothing to build, which is the case that proves pipelines are repository-scoped with an optional application link.

```yaml theme={null}
# ankraio/ankra-docs as an Ankra pipeline.
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "ankra-docs"
on:
  push:
    branches:
      - "master"
  pull_request:
    branches:
      - "master"
    fork_policy: "read_only"
  schedule:
    - cron: "0 6 * * *"
      branch: "master"
      stages:
        - "checkout"
        - "install"
        - "broken-links"
        - "live-openapi-reachable"
concurrency:
  group: "ankra-docs-${{ ankra.ref }}"
  cancel_in_progress: true
workspace:
  size: "10Gi"
  access: "rwo"
defaults:
  image: "node:22-bookworm-slim"
  timeout: "15m"
  network: "egress-https"
permissions:
  contents: "read"
  pipelines: "read"
stages:
  - name: "checkout"
    kind: "checkout"

  - name: "install"
    kind: "run"
    run: |-
      set -eu
      corepack enable
      pnpm install --frozen-lockfile
    needs:
      - "checkout"
    cache:
      - key: "pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}"
        paths:
          - ".pnpm-store"
    timeout: "10m"

  # The structure checks read the repository and nothing else; only the
  # pyyaml install needs egress.
  - name: "structure"
    kind: "run"
    image: "python:3.12-slim"
    run: |-
      set -eu
      pip install --quiet pyyaml
      python3 scripts/check_nav.py
      python3 scripts/check_frontmatter.py
      python3 scripts/check_snippets.py
    needs:
      - "checkout"
    timeout: "10m"

  # Split out because it is the only check that leaves the repository: it
  # fails on production being down rather than on the docs being wrong, and
  # as its own stage that distinction is visible on the run.
  - name: "live-openapi-reachable"
    kind: "verify"
    needs:
      - "checkout"
    verify:
      probe:
        url: "https://platform.ankra.app/openapi.json"
        status: 200
        timeout: "1m"

  - name: "broken-links"
    kind: "run"
    run: |-
      set -eu
      pnpm exec mint broken-links
    needs:
      - "install"
    timeout: "15m"

  # allow_failure keeps the run green while the prose warnings stay visible
  # on the stage.
  - name: "prose"
    kind: "run"
    image: "jdkato/vale:v3.9.1"
    run: |-
      set -eu
      vale --output=line --minAlertLevel=warning .
    needs:
      - "checkout"
    allow_failure: true
    timeout: "10m"

on_failure:
  - name: "triage"
    kind: "agent"
    agent:
      goal: "Explain which docs check failed and propose the smallest edit that fixes it."
      tool_profile: "ci-read-only"
      mode: "ask"
      budget:
        tool_calls: 15
        turns: 6
        minutes: 10
      context:
        - "diff"
        - "logs"

finally:
  # A Slack incoming-webhook URL is a bearer credential, so it is read from
  # the organisation's variables rather than committed here.
  - name: "notify"
    kind: "webhook"
    webhook:
      url: "${{ vars.SLACK_CI_ALERTS_WEBHOOK }}"
      method: "POST"
      timeout: "30s"
```

Reading it against [what executes today](/guides/ankra-pipelines#what-is-in-place-today): `checkout` and the four `run` stages execute in the cluster; the `verify` probe, the `agent` triage and the `webhook` notification have no executor on this build, so each reports a `pipeline_executor:` warning and is skipped with reason `kind_unavailable` - the run still concludes on the stages that do execute. The schedule fires. The definition therefore validates as `warn`, not `ok`, and that is the honest answer: the file describes three stages the platform will not run yet, and says so in the same words the run's own skip reason uses.

## Related

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> How a run happens, the security model, failure handling and limits.

> [card] [Migrate from GitHub Actions](/guides/migrate-from-github-actions)
>
> Convert an existing definition and review the notes.

> [card] [ankra.yaml reference](/reference/application-descriptor)
>
> The application descriptor beside the pipeline: metadata, deploy options and declared components.


# PR Preview Environments
Source: https://docs.ankra.ai/guides/pr-preview-environments

Every pull request on a connected application gets a live, throwaway preview on your staging cluster - with one status comment that updates in place

Reviewers should be able to open a link on a pull request and see the change running, instead of reading a diff and imagining it. Ankra deploys every pull request on a connected application to your organisation's staging cluster, keeps one status comment on the pull request up to date, and tears the preview down when the pull request closes.

A preview deploys an image that was already built for the pull request. Which image that is depends on how the application is built - see [Where the preview image comes from](#where-the-preview-image-comes-from) before you rely on previews.

***

## What you get

Once the pull request's image exists, a comment like this appears and keeps itself up to date:

> ### 🚀 Ankra Preview
>
> | Application | Status | Preview | Commit | Updated (UTC) |
> | :- | :- | :- | :- | :- |
> | **website** | ✅ Ready | **Visit Preview ↗** | `524ba32` | Aug 8, 2026, 10:26 PM |
>
> <sub>⏳ Expires Aug 9, 22:26 UTC · 🔁 Redeploys on every push</sub>

The preview runs in its own isolated namespace on the staging cluster, PodSecurity-hardened and quota-bounded, exactly like a manually launched [preview demo](/concepts/applications#preview-demos). When the Ankra GitHub App has the optional Deployments permission, the pull request also gets a GitHub deployment entry, so the preview shows up in the pull request's environments box.

***

## Prerequisites

**1. Connect the repository as an application**

The repository must be a [connected application](/concepts/applications) (GitHub only for now).

**2. Make sure pull requests produce an image**

An application built with Ankra Pipelines already does: every pull request run builds the head commit. An application built with the generated GitHub Actions workflow does not, because that workflow pushes nothing for a pull request. See [Where the preview image comes from](#where-the-preview-image-comes-from).

**3. Turn PR previews on for the installation**

An admin switches **PR previews** on under **AI** → **Settings** → **Connections** → **Source control & AI review**, on the GitHub installation's **All repositories** row or on a rule for that repository. It is off on a new installation, and nothing is deployed until it is on. See [AI code review](/platform/ai-code-review#the-repository-table).

**4. Configure a staging cluster**

An admin sets the organisation's staging cluster under **AI** → **Settings** → **Workspaces**. Without it, pull requests deploy nothing however the switch is set.

**5. Optional: bring a demo base domain for HTTPS**

By default previews are served under the staging cluster's own Ankra DNS zone (`*.ankra.cc`, or the [Ankra domain your organisation selected](/concepts/applications#the-preview-url)) over plain HTTP. For HTTPS (or your own hostnames), configure a **demo base domain** with an ingress class and TLS secret in the same settings screen.

***

## Where the preview image comes from

Ankra looks for the preview image in one of two ways, depending on what builds the application. The application's setup pull request decides that: a new application builds with Ankra Pipelines by default. [Ship Your App](/guides/deliver-your-app#where-the-image-is-built) compares the builders.

### Applications built with Ankra Pipelines

The preview deploys the image the pipeline's `build` step pushed for the pull request's head commit, by digest. Nothing else is needed: the pull request run that the push already starts is what produces it. Ankra never deploys a tag that could still point at an older commit.

While that run is still going, the preview waits and the comment says **Building**. When the run concludes, Ankra deploys straight away. If the run fails before it produces an image, the preview reports **Failed** with the reason, for example `Pipeline run #53 failed to build 524ba32: ...`. The next push, or a later successful run for the same commit, deploys it.

The pipeline needs its CI cluster and an approved definition before it runs at all - see [Before your first run](/guides/ankra-pipelines#before-your-first-run).

### Applications built by GitHub Actions

The preview deploys an image from the application's registry repository tagged with, in this order of preference:

1. `sha-<7>` - the first seven characters of the pull request's head commit,
2. `pr-<number>` - the pull request number,
3. the branch name, with every character other than letters, digits, `.`, `_` and `-` replaced by `-`.

> [!WARNING]
>
> The generated `build-and-publish.yml` workflow builds and scans the image on a pull request but never pushes it, so it produces none of these tags for a pull request. An application on the generated workflow therefore reports **Build unavailable** on every pull request. Previews work in this lane only when a workflow of your own pushes one of the tags above for pull requests, or after the application moves to [Ankra Pipelines](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call).

Ankra prefers the head's own `sha-<7>` tag because a `pr-<number>` or branch tag can still hold an earlier push's image.

***

## The status comment

One marker-tagged comment per pull request, updated in place - never a stream of new comments.

| Status | Meaning |
| - | - |
| 🔄 **Building** | No image exists for this head yet. Ankra checks again for a few minutes and updates the comment when it arrives; a later completed build for the same head also re-triggers it. The footer says what the preview is waiting for: the pipeline run's `build` step for a pipeline-built application, or a `pr-<number>` or `sha-<7>` tag for every other application. |
| ⏳ **Deploying** | The image was found and the preview is starting on the staging cluster. |
| ✅ **Ready** | Deployed. The **Visit Preview** link opens the running pull request build; the **Commit** column shows the deployed head SHA. |
| ⚠️ **Build unavailable** | Ankra stopped waiting and found no image for this head. See [Troubleshooting](#troubleshooting). |
| ❌ **Failed** | The deploy failed, or the pipeline run failed to build the head. The reason appears in a caution callout under the table. |
| ⚪ **Stopped** | The pull request was closed or merged and the preview namespace was deleted. |

Lifecycle:

* **On open**: the preview deploys as soon as the pull request's image exists.
* **On every push**: the preview redeploys with the new head; the comment's Commit and Updated cells refresh.
* **On close or merge**: the namespace is torn down immediately and the comment flips to ⚪ Stopped.
* **On expiry**: previews are time-limited (the organisation's demo lifetime, 24 hours by default) and reaped automatically; pushing again deploys a fresh one.

***

## Configuration and data

Automatic previews inherit the application's **demo environment defaults** - env vars, secret slots, and the optional throwaway Postgres - configured as the environment template under the application's **Previews** section (*Preview settings*). See [environment variables and a throwaway database](/concepts/applications#environment-variables-and-a-throwaway-database). If your app needs configuration to boot, set the defaults once and every pull request preview gets them.

***

## Troubleshooting

| Symptom | What to check |
| - | - |
| No comment appears on a new pull request | Is **PR previews** on for that repository, is the repository a connected application, and is the staging cluster set? If all three hold, push a new commit (or close and reopen the pull request) - either re-triggers the preview. |
| Stuck on 🔄 Building, pipeline-built application | Find the pull request's run with `ankra pipeline list --application <application> --head-sha <full-sha>`, or in the application's **Pipelines** section. No run at all usually means the organisation's CI cluster has no CI workers or no cluster is set - see [Before your first run](/guides/ankra-pipelines#before-your-first-run). |
| ⚠️ Build unavailable, application on the generated workflow | Expected: that workflow pushes no image for a pull request. Push a `sha-<7>` or `pr-<number>` tag from your own CI, or [move the application to Ankra Pipelines](/guides/migrate-from-github-actions#migrate-an-existing-application-with-one-call). |
| ⚠️ Build unavailable, your own workflow | The workflow did not push any of the tags [listed above](#applications-built-by-github-actions) to the application's registry repository for this head. Check the workflow run and the tags it pushed. |
| No preview for a pull request from a fork | Forks get no preview image in either lane. A fork's pipeline build is restricted and pushes nothing, and GitHub does not give a fork's workflow the secrets it would need to push. |
| ❌ Failed with a pipeline run named | The pull request's pipeline run failed before its `build` step produced an image. Open the run named in the callout, fix it, and push again. |
| ✅ Ready but the URL errors or 503s | The preview runs *your pull request's container* - a crash on boot is application-side, not platform-side. Inspect the preview namespace's pod logs on the staging cluster (the preview's detail page under **Previews**, or `kubectl`). A config file change that breaks the container's server is the classic cause. |
| The preview URL does not resolve | The staging cluster's DNS zone must be active (or a demo base domain configured). If it resolves publicly but not on your machine, a stale negative DNS cache is usually to blame - retry against another resolver. |
| HTTP instead of HTTPS | Platform-zone previews (`*.ankra.cc`, or your selected Ankra domain) are HTTP by design. Configure a demo base domain with a TLS secret for HTTPS. |

***

## Related

* [Ship Your App](/guides/deliver-your-app) - the routes from a repository to a running, redeploying application, and which builder feeds previews
* [Branch demos](/guides/branch-demos) - the manual launch dialog, its environment variables, throwaway database, and teardown timer
* [Preview demos](/concepts/applications#preview-demos) - launch a demo manually from the portal, CLI, or the `deploy_pr_demo` MCP tool
* [The preview URL](/concepts/applications#the-preview-url) - how the public hostname is resolved
* [Ankra Pipelines](/guides/ankra-pipelines) - the in-cluster CI whose pull request runs build preview images


# Private access for proxied domains
Source: https://docs.ankra.ai/guides/private-proxied-domains

Require Ankra organisation membership and optional roles for ankra.cc and custom domains proxied by Ankra Cloud.

Ankra Cloud can protect services on generated `ankra.cc` hostnames **and custom domains** with the same organisation identity used in Ankra Platform. Set a domain's Cloud DNS zone to **organisation** access and the relay sends visitors through Platform sign-in, then checks their current organisation membership and allowed role before forwarding a request. Existing public zones stay public until you change their policy.

This applies to hostnames served through the Ankra Cloud proxy. A DNS record that sends traffic directly to an origin does not pass through this gate. A private zone cannot use a direct HTTP route that bypasses the proxy.

> [!NOTE]
>
> The `ankra org access-gateway` commands are merged into the CLI source but await the next tagged CLI release. Check `ankra org access-gateway --help` before following the commands below.

## Choose who can enter

First, link the Ankra Cloud account that owns the zone to its Ankra Platform organisation. Sign in to the [Ankra CLI](/integrations/ankra-cli), select that organisation, and list its Cloud DNS zones:

```bash theme={null}
ankra org current
ankra org access-gateway zones
ankra org access-gateway get <zone-id>
```

Set the zone to organisation-only access. With no role filter, every active member of the linked organisation can enter:

```bash theme={null}
ankra org access-gateway set <zone-id> --mode organisation
```

To limit access to particular organisation-wide roles, repeat `--role`:

```bash theme={null}
ankra org access-gateway set <zone-id> --mode organisation --role admin --role operator
```

The built-in role names are `owner`, `admin`, `operator`, `member`, and `viewer`; you can also use a custom role's ID. A member must hold at least one allowed role. The policy applies to the zone's proxied hostnames and is inherited by its subzones. To make the zone public again, run `ankra org access-gateway set <zone-id> --mode public`.

Reading zones and policies requires `members.read`; changing a policy requires `members.manage`. The organisation is taken from the authenticated CLI session, and the Cloud account and zone are checked server-side. You cannot select a different organisation by putting its ID in the policy.

## Use your own identity provider

Members sign in through Ankra Platform. An organisation can configure its own OpenID Connect provider under **Organisation → Settings → Single sign-on** and map provider groups to Ankra roles. The gateway then uses that Platform sign-in and checks current membership and roles; it does not maintain a separate Cloud user list. Follow [Single Sign-On](/guides/single-sign-on) for provider setup, plan requirements, and how to require SSO for the organisation.

A browser visiting a private service is sent to sign-in when needed. Non-browser requests do not start the interactive flow; sign in through the service's browser page first. If membership or the required role is removed, subsequent checks deny access.

## Check readiness

```bash theme={null}
ankra org access-gateway status \
  --platform-cluster <platform-cluster> \
  --relay-cluster <cloud-control-cluster> \
  -o json
```

The status command checks the Platform API and relay deployments, their credential references, and the relay's broker URL through Ankra. It does not reveal credentials, prove that both sides have the same token, or perform a browser sign-in. Read the zone policy with `get` and test the private hostname in a browser before relying on it.


# Protect Persistent Data Before Changing a Stack
Source: https://docs.ankra.ai/guides/protect-persistent-data

Removing or renaming a Stack manifest deletes its objects, PersistentVolumeClaims included, and a Delete reclaim policy destroys the disk too. Check and fix this before you change the Stack.

You want to tidy up a Stack - rename a manifest, split one into two, or drop one you no longer need - and the manifest owns a namespace or a PersistentVolumeClaim. Done carelessly, that change deletes the volume and the data on it. This guide shows how to check what is at risk and make the change safely.

## Why a Stack Change Can Delete Data

Ankra identifies a manifest by its `name`. When a Stack is applied - with `ankra cluster apply`, a GitOps sync, or an edit in the portal - and a manifest name is no longer there, Ankra deletes every object in that manifest's stored YAML. A rename is the same thing: the old name is deleted and the new name is created as a new manifest, with nothing ordering the two.

* A manifest that holds a `Namespace` takes the namespace with it, and every PersistentVolumeClaim inside it.
* A manifest that holds PersistentVolumeClaims deletes those claims.
* What happens to the disk depends on the PersistentVolume's reclaim policy. With `Delete`, the default for most CSI drivers, the disk is destroyed with the claim. With `Retain`, the PersistentVolume and its data stay behind in the `Released` state.

The field-level rules are in the [ImportCluster reference](/reference/importcluster#spec-stacks-manifests).

## Prerequisites

* Access to the cluster in Ankra, and permission to edit the Stack.
* The Ankra CLI, logged in, if you use the commands below. Everything can also be done in the portal.

## Steps

**1. Find the volumes the change touches**

List the claims in the namespaces the manifest owns or deploys into. In the portal, open the cluster and go to **Kubernetes → Storage → Persistent Volume Claims**. From the CLI:

```bash theme={null}
ankra cluster get resources PersistentVolumeClaim -n my-namespace
```

Note the volume each claim is bound to. A claim created by a StatefulSet's `volumeClaimTemplates` is not in any manifest, but it is still deleted when the namespace around it is.

**2. Check each volume's reclaim policy**

Go to **Kubernetes → Storage → Persistent Volumes** and read the **Reclaim Policy** column for those volumes, or list them:

```bash theme={null}
ankra cluster get resources PersistentVolume
```

Any volume with `Delete` loses its data if its claim is deleted.

**3. Switch the volumes you need to Retain**

A volume's reclaim policy can be changed in place, with no downtime. From the CLI:

```bash theme={null}
ankra cluster patch pv <pv-name> --type merge \
  --patch '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
```

Or open the volume, go to its **Manifest** tab, click **Edit**, set `persistentVolumeReclaimPolicy: Retain`, and **Apply**.

For volumes created later, a StorageClass's `reclaimPolicy` cannot be changed after it is created. Add a second StorageClass with `reclaimPolicy: Retain` and use it for stateful workloads.

**4. Take a copy if the data matters**

`Retain` keeps the disk, but it does not give you a copy. [Take a restore point](/guides/backups#take-a-restore-point-now) of the Stack first, or use your database's or storage provider's own backup.

**5. Make the Stack change**

Rename or remove the manifest. Where you can, avoid renaming a manifest that owns a namespace or a claim at all: keep its name fixed and change its contents instead. If you rename a parent, update every `parents` entry that names it in the same change.

## Verify

After the Stack has synced, check **Kubernetes → Storage → Persistent Volumes** again. Volumes you switched to `Retain` whose claims were deleted show the status `Released`, with their data intact.

To use a `Released` volume again, clear its `spec.claimRef` and create a claim that names it with `spec.volumeName`. A released volume keeps costing money until you reuse or delete it; [Cloud Cost](/platform/cloud-cost) lists released persistent volumes among its savings findings.

## Changing the Cluster's GitOps Repository

Pointing a cluster at a different GitOps repository or branch carries the same risk on a larger scale. Ankra writes the cluster's current state to the new source first, but from then on that source is authoritative: anything that later leaves it is removed, including workloads that own claims. `ankra cluster apply` refuses a repoint unless you pass `--allow-repoint`, and on a cluster that holds PersistentVolumeClaims it also needs `--allow-repoint-destroying-data`. Only pass the second flag after you have done the steps above. See `spec.git_repository` in the [ImportCluster reference](/reference/importcluster).

## Troubleshooting

* **The claim is gone and the volume was `Delete`.** The disk has been removed by the storage provider. Restore from a backup or restore point; Ankra cannot bring it back.
* **The recreated claim is empty.** A new claim with the old name is bound to a new, empty volume by the StorageClass, not to the retained one. To get the data back, clear the retained volume's `spec.claimRef` and create the claim with `spec.volumeName` set to that volume.

## Next Steps

Before your next Stack change, switch the volumes of every stateful workload to `Retain` now, so a later rename cannot take data with it. For help with a volume you have already lost, [contact support](/platform/support).


# Proxmox VE Clusters
Source: https://docs.ankra.ai/guides/proxmox-clusters

Create a Kubernetes cluster on virtual machines in your own Proxmox VE datacenter, with Ankra installing and operating Kubernetes, ingress, TLS and DNS.

Choose Proxmox VE when the cluster has to run on hardware you already own, on-premises or on dedicated servers. You bring the Proxmox nodes, storage and bridges; Ankra fills in safe defaults where they are missing, creates the VMs, installs Kubernetes, and then operates the cluster for you - this is an **Ankra Managed** cluster. There is no cloud bill: [Cloud Cost](/platform/cloud-cost#private-capacity-rate-cards) prices the cluster from a rate card on its Proxmox credential, which starts with Ankra's default rates.

## Before you start

* A **Proxmox VE API credential**: the API URL and an API token with VM management privileges. If Ankra needs to initialise storage, networking or the template, the token also needs `Datastore.Allocate`, `Datastore.AllocateTemplate`, `Sys.Modify` and `SDN.Allocate`. Persistent volumes also need `Datastore.Audit`. [Proxmox VE Credentials](/platform/credentials/proxmox#what-ankra-accesses) lists every privilege with a ready-made `pveum` role.
* An **SSH key credential** for VM access - your own public key, or one Ankra generates. A Proxmox cluster takes a single key. See [SSH Key Credentials](/platform/credentials/ssh-key).
* **A cloud-init VM template.** During credential setup Ankra downloads the Ubuntu 24.04 cloud image and registers it as the `ankra-ubuntu-24-04` template on every node that lacks it. You can bring your own and pin it with `template` - see [Creating a cloud-init template](#creating-a-cloud-init-template).
* **Room next to your own VMs.** On an installation that already runs VMs, VMID 9999 must be free and the selected hosts need free memory for every cluster VM. See [Connecting a Proxmox VE that already runs VMs](/platform/credentials/proxmox#connecting-a-proxmox-ve-that-already-runs-vms).
* **A network bridge.** Use an existing active Linux bridge, or let Ankra convert the single active management Ethernet or bond interface (static or `manual` method) to `vmbr0`. Ankra also creates a private NAT network `ankra` (10.20.0.0/16) through Proxmox SDN - see [Networking](#networking).
* **The `dnsmasq` package** on each node for the private network's DHCP (`apt install dnsmasq && systemctl disable --now dnsmasq`), and `source /etc/network/interfaces.d/*` in `/etc/network/interfaces` (present by default on standard installs).
* **Free local disk or existing VM storage.** If no active storage supports VM images, Ankra enables `images` and `rootdir` on the `local` directory storage, or creates it at `/var/lib/vz`. The `import` content type is enabled on `local` for cloud-image downloads. A Proxmox VE installed on top of Debian has only `local`, no `local-lvm`, so pass `--storage local` to the CLI.
* **API reachability.** The Proxmox API must use HTTPS and be reachable from Ankra, directly or through an [SSH jumphost](#hybrid-connectivity-ssh-jumphost).

### Hybrid connectivity (SSH jumphost)

Many Proxmox environments are not reachable from the internet. If Ankra cannot reach the Proxmox API and the VM network directly, attach an **SSH jumphost** (host, port, username and private key) to the Proxmox VE credential; Ankra then tunnels both the API calls and the SSH connections to your nodes through it. If the API uses a self-signed certificate, enable **TLS insecure** (`tls_insecure`) on the credential. Both are set on the credential - see [Proxmox VE Credentials](/platform/credentials/proxmox).

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **Proxmox VE** under **Ankra Managed**.
>
> **2. Credential**
>
> Pick the Proxmox VE credential and an SSH key, or add either inline.
>
> **3. Placement**
>
> Pick **Single host** and the Proxmox node that hosts all cluster VMs, or **Host spread** and two or more hosts - see [Host-Spread Placement](#host-spread-placement). In both modes pick the **Storage** for VM disks and the **Network Bridge** the VMs attach to. Pick the `ankra` private network unless you run your own DHCP-served bridge.
>
> **4. Compute**
>
> Pick the bastion size (for example `px-small`), the control plane count (1 or 3) and size (for example `px-medium`), worker node groups, and for kubeadm the etcd topology. The wizard shows each size's vCPUs, memory and disk.
>
> **5. Kubernetes**
>
> Keep **kubeadm** (the default, with Cilium) or pick **k3s** and its CNI, and optionally the version. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time).
>
> **6. Review**
>
> Name the cluster and set its environment. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik and cert-manager as Ankra-managed stacks. On k3s they run through the built-in service load balancer; unchecked, k3s keeps its bundled Traefik and no certificate manager (a kubeadm cluster gets no ingress controller or certificate manager at all).
> * **Include Public DNS** - a delegated subdomain on `ankra.cc` with external-dns wired, so an ingress hostname under it gets its DNS record and TLS certificate automatically.
>
> Click **Create cluster**. A progress view follows the SSH keys, bastion, VMs, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials proxmox create --name my-proxmox --api-url https://pve.example:8006 --token-id 'root@pam!ankra'   # prompts for the token secret
> ankra credentials proxmox ssh-key create --name my-ssh-key --generate
>
> # What the credential can use
> ankra cluster proxmox hosts --credential-id <proxmox-credential-id>
> ankra cluster proxmox storages --credential-id <proxmox-credential-id> --node pve01
> ankra cluster proxmox bridges --credential-id <proxmox-credential-id> --node pve01
> ankra cluster proxmox templates --credential-id <proxmox-credential-id> --node pve01
> ankra cluster proxmox sizes
>
> ankra cluster proxmox create \
>   --name my-cluster \
>   --credential-id <proxmox-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --node pve01 \
>   --storage local-lvm \
>   --bridge ankra \
>   --control-plane-count 1 \
>   --control-plane-instance-type px-medium \
>   --worker-count 2 \
>   --worker-instance-type px-medium
> ```
>
> `--placement-nodes pve01,pve02,pve03` spreads the VMs across hosts. `--template`, `--distribution k3s`, `--etcd-topology external` with `--etcd-node-count` and `--etcd-instance-type`, and `--include-networking=false` cover the other choices. The credential flags `--tls-insecure` and `--jumphost-*` set the options from [Hybrid connectivity](#hybrid-connectivity-ssh-jumphost).

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/proxmox \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<proxmox-credential-id>",
>     "ssh_key_credential_id": "<ssh-key-credential-id>",
>     "node": "pve01",
>     "storage": "local-lvm",
>     "bridge": "ankra",
>     "control_plane_count": 1,
>     "control_plane_instance_type": "px-medium",
>     "node_groups": [
>       {"name": "default", "instance_type": "px-medium", "count": 2}
>     ],
>     "include_networking": true,
>     "include_dns": true
>   }'
> ```
>
> Every field, default and instance size preset is in the [Proxmox VE Reference](/reference/proxmox).

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created on your hosts

* **A bastion VM** - the only SSH access point Ankra uses to reach the nodes. It carries no workload or egress traffic. With a jumphost on the credential, Ankra reaches both the Proxmox API and the bastion through it.
* **Control plane and worker VMs** (QEMU), cloned from the cloud-init template and attached to the network you picked, plus dedicated etcd VMs for a kubeadm cluster with external etcd. Each is tagged `ankra` and `ankra-cluster-<id>`.
* **The `vmbr0` bridge and the `ankra` SDN network**, when they did not exist, set up during credential setup.

There is no cloud controller manager: `LoadBalancer` Services are not provisioned. Expose workloads with `NodePort` Services, an ingress controller, or a load balancer you deploy yourself. The [Proxmox VE Reference](/reference/proxmox#architecture) has the full layout.

## Proxmox VE specifics

### Networking

When you save a Proxmox VE credential, Ankra initialises two networks when they do not already exist:

| Network | Purpose | Address |
| - | - | - |
| `vmbr0` (Linux bridge) | Management - carries the host's public or provider-assigned IP | Inherited from the physical interface |
| `ankra` (SDN vnet) | Private compute - isolated from the management interface | 10.20.0.1/16 (SNAT to the public interface) |

**`vmbr0` (management bridge).** If no active bridge exists, Ankra converts the single active Ethernet or bond management interface to `vmbr0`. A statically addressed interface's address and gateway move to the bridge; a `manual`-method interface (common on dedicated-server providers such as Scaleway) converts to an address-less bridge. The physical interface becomes the bridge's uplink. DHCP-managed management interfaces cannot be converted through the Proxmox API - create the bridge manually in that case. Ankra refuses the conversion when the management interface is ambiguous, has custom options, or another network change is pending.

**`ankra` (private SDN network).** Ankra creates a Proxmox SDN *simple zone* named `ankra` with a vnet of the same name and the subnet 10.20.0.0/16 (gateway 10.20.0.1). The subnet has **SNAT** enabled, so Proxmox masquerades outbound VM traffic through the host's public interface, and **DHCP** served by dnsmasq (range 10.20.1.1 to 10.20.254.254) backed by the built-in PVE IPAM. Because addresses are registered in the IPAM the moment a VM's NIC attaches, Ankra reads VM addresses without requiring the QEMU guest agent in the image.

**Recommended setup.** Place cluster VMs on the `ankra` network - it appears alongside Linux bridges in the cluster creation wizard. This keeps Kubernetes traffic off the management bridge and gives VMs internet access through NAT without exposing them publicly. Because the VMs are private, attach the Proxmox host itself (or another host with a route into 10.20.0.0/16) as the [SSH jumphost](#hybrid-connectivity-ssh-jumphost) on the credential so Ankra can reach the bastion.

### Creating a cloud-init template

Ankra clones a cloud-init VM template for every cluster VM. **Every node gets Ankra's template automatically**: during credential setup Ankra downloads the Ubuntu 24.04 cloud image and registers it as the `ankra-ubuntu-24-04` template. Your own templates are left untouched, and Ankra clones one of them only when you name it with `template`.

Create your own template when you need a different distribution, a hardened image, or pre-installed packages. The steps below use Ubuntu 24.04. Adjust the image URL and VM ID for your environment.

```bash theme={null}
# On the Proxmox node (as root)

# 1. Download the Ubuntu 24.04 cloud image
wget https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img \
  -O /var/lib/vz/images/ubuntu-2404-cloud.img

# 2. Create a VM to use as the template (VM ID 9000, adjust as needed)
qm create 9000 \
  --name ubuntu-2404-cloudinit \
  --memory 2048 --cores 2 \
  --net0 virtio,bridge=ankra \
  --ostype l26

# 3. Import the cloud image as the primary disk
qm importdisk 9000 /var/lib/vz/images/ubuntu-2404-cloud.img local-lvm

# 4. Attach the disk, enable SCSI, and configure boot
qm set 9000 \
  --scsihw virtio-scsi-pci \
  --scsi0 local-lvm:vm-9000-disk-0,discard=on \
  --boot c --bootdisk scsi0

# 5. Add a cloud-init drive and serial console
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --serial0 socket --vga serial0

# 6. Enable the QEMU guest agent (required for Ankra to read VM IPs on
#    networks other than the Ankra-managed SDN network)
qm set 9000 --agent enabled=1

# 7. Convert the VM to a template
qm template 9000
```

> [!NOTE]
>
> The template VM ID (9000 in this example) must be unique on your node. Ankra uses `ankra-ubuntu-24-04` unless you pin your template with the `template` option (by name or VMID) at cluster creation time.

For **host-spread placement**, create the same-named template on every selected node before provisioning the cluster.

### Host-Spread Placement

When your Proxmox VE cluster has multiple nodes, you can spread the Kubernetes VMs across them so a single host failure does not take down the whole Kubernetes cluster. Host spread is opt-in: pass `placement_nodes` with two or more nodes via the API, or pick **Host spread** in the creation wizard.

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/proxmox \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<proxmox-credential-id>",
    "ssh_key_credential_id": "<ssh-key-credential-id>",
    "node": "pve01",
    "placement_nodes": ["pve01", "pve02", "pve03"],
    "storage": "local-lvm",
    "bridge": "ankra",
    "control_plane_count": 3,
    "control_plane_instance_type": "px-medium",
    "node_groups": [
      {"name": "default", "instance_type": "px-medium", "count": 3}
    ],
    "distribution": "k3s"
  }'
```

#### Prerequisites

Every selected host must be online and provide the **same-named resources**, because VMs are cloned locally on each host:

* Active storage with the selected name that allows VM images (e.g., `local-lvm` on every host).
* An active bridge with the selected name (e.g., `vmbr0` on every host), all attached to the same DHCP network.
* A cloud-init template with the **same name** on every host. Ankra resolves each host's own template VMID and clones locally - shared-storage cross-node cloning is not used.

Creation is rejected if any selected host is missing one of these. `node` stays required and must be one of the `placement_nodes`; the bastion always runs there.

#### How VMs are distributed

Ankra assigns control planes, dedicated etcd members, and each worker group deterministically: the host with the fewest members of the same role or group wins, ties break by fewest total Kubernetes VMs, then by your selected-node order. Every Kubernetes node is labeled with `topology.kubernetes.io/zone=<proxmox-node>` so you can use standard [topology spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) and pod anti-affinity against the physical failure domain.

Later scaling keeps the policy: adding node groups, scaling them up, and adding control planes all place new VMs on the least-represented eligible host. Restart, resize, upgrade, and delete operations stay pinned to each VM's recorded host.

#### Requirements and limitations

* **At least 3 control planes.** Host-spread clusters must be created with 3 or 5 control plane nodes so the Kubernetes control plane keeps quorum when one host fails.
* **Two hosts give reduced resilience.** With only two hosts, losing the host that carries the control-plane majority still takes the Kubernetes API down. Three or more hosts are recommended.
* **The bastion is not spread.** It runs on the primary `node`; if that host fails, Ankra's SSH path to the cluster is unavailable until the host returns, while workloads keep running.
* **No Proxmox HA-manager integration.** Ankra does not enroll VMs in Proxmox HA groups and never live-migrates or recreates VMs on another host after a failure. Resilience comes from Kubernetes replication across hosts, so run workloads with multiple replicas spread over zones.

#### Workload guidance

For a workload to survive a host outage, run at least two replicas and spread them across zones:

```yaml theme={null}
topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        app: my-app
```

### Other differences

* **Resizing a node group** powers each VM off, resizes it and powers it on again, with brief downtime for its workloads. Sizes only grow; for smaller nodes, create a new group and delete the old one. On a host-spread cluster, new VMs go to the least-represented eligible host.
* **Restart** works from the CLI (`ankra cluster proxmox nodes restart`); the bastion is resized from the dashboard or the API.
* **A stop** captures the cluster's etcd state through the credential's jump host before the VMs are deleted, and frees the host capacity. **Terminating** deletes every VM Ankra created (bastion, control planes, workers and etcd VMs) and leaves your Proxmox nodes, storage and bridges untouched. It also deletes the disks the cluster's CSI driver provisioned, so a cluster that has some is terminated only once you accept that - see [Persistent Volumes on Proxmox VE Clusters](/guides/proxmox-persistent-volumes#deleting-a-cluster-deletes-its-volumes).
* **No cost estimate in the create wizard**, because Proxmox VE has no list pricing. [Cloud Cost](/platform/cloud-cost#private-capacity-rate-cards) prices running clusters from the credential's rate card, which ships with default rates you can change.

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `proxmox`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Proxmox API unreachable from Ankra | Attach an [SSH jumphost](#hybrid-connectivity-ssh-jumphost) to the credential - Ankra tunnels API calls and node SSH through it |
| TLS certificate errors (self-signed) | Enable the **TLS insecure** toggle (`tls_insecure`) on the Proxmox VE credential |
| Nodes never get an IP address | On the `ankra` SDN network, verify the zone is healthy (`dnsmasq` installed, zone status *available* under **Datacenter → SDN**). On your own bridge, verify a DHCP server answers there |
| Provisioning fails waiting for a VM's IP address | On the `ankra` SDN network, addresses come from the PVE IPAM automatically. On other bridges the cloned template must ship the **QEMU guest agent** - rebuild the template with `qemu-guest-agent` and retry |
| Ankra's template `ankra-ubuntu-24-04` is not on the node | Re-save the Proxmox credential to build it, or name your own template with `template` |
| VMID 9999 is in use | A guest of yours has the VMID the persistent volume driver files cluster volumes under - move it to another VMID and retry |
| The cluster needs more memory than the selected hosts have free | Choose smaller instance types, fewer nodes, or more hosts - Ankra does not overcommit hosts that run your VMs |
| No VM templates found on the node | Re-save the Proxmox credential to run the automatic setup (it creates the `ankra-ubuntu-24-04` template), or create one yourself - see [Creating a cloud-init template](#creating-a-cloud-init-template) |
| Cluster stuck in provisioning | Check the API token privileges (see [Proxmox VE Credentials](/platform/credentials/proxmox)) and free capacity on the selected node and storage |
| VM creation fails with a permission error | The API token is missing privileges (e.g., `VM.Allocate`, `Datastore.AllocateSpace`) on the selected node, storage, or bridge |
| `PersistentVolumeClaim` stuck in `Pending`, or `proxmox-csi-plugin-node` pods restarting | See [Persistent Volumes on Proxmox VE Clusters](/guides/proxmox-persistent-volumes#troubleshooting) |
| LoadBalancer service stuck in `Pending` | Proxmox clusters have no cloud controller manager - use `NodePort`, ingress, or your own load balancer |
| No cost estimate in the wizard | Expected - Proxmox has no list pricing. Running clusters are priced in Cloud Cost from the credential's [rate card](/platform/cloud-cost#private-capacity-rate-cards) |


# Persistent Volumes on Proxmox VE Clusters
Source: https://docs.ankra.ai/guides/proxmox-persistent-volumes

How Ankra-built Proxmox VE clusters provision PersistentVolumes through the bundled Proxmox CSI driver, which StorageClass to use, how volumes follow Proxmox hosts, and how to fix a cluster whose CSI node plugin keeps restarting.

Every [Proxmox VE cluster](/guides/proxmox-clusters) Ankra builds ships with a CSI driver, so a `PersistentVolumeClaim` gets a real virtual disk on your Proxmox storage. That disk is attached to the VM that runs the pod. There is no extra install and no extra credential: the driver uses the same Proxmox API token the cluster was built with. That token needs `Datastore.Audit` on top of what provisioning uses - see [Proxmox VE Credentials](/platform/credentials/proxmox#what-ankra-accesses).

## What Ankra installs

The `proxmox-csi` Stack on each cluster holds:

| Part | Name | What it does |
| - | - | - |
| Namespace | `csi-proxmox` | Labelled for the privileged Pod Security profile, because the node plugin mounts host paths |
| Secret | `proxmox-csi-plugin-config` | The Proxmox API URL, token and TLS setting, SOPS-encrypted in the Stack |
| Add-on | `proxmox-csi-plugin` (chart from `oci://ghcr.io/sergelogvinov/charts`) | The controller, which creates, attaches and resizes disks through the Proxmox API, and a node plugin on every node, which mounts them |
| StorageClass | `proxmox-csi` | The default class, backed by the storage the cluster's VM disks live on |

When the cluster's disks span more than one Proxmox storage, each further storage gets its own class, named `proxmox-csi-<storage>`.

The driver reaches the Proxmox API from inside the cluster at the credential's API URL. If that address is not reachable from the cluster's VMs, for example on a routed SDN where guest traffic is SNATed, create the credential through the API with `internal_api_url` set to an address the VMs can reach. The driver then uses that address and Ankra keeps using `api_url`.

## Use a volume

An unqualified claim lands on the default class:

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
  namespace: my-app
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 10Gi
```

Ship it as a manifest in one of your own Stacks, like any other resource - not in the `proxmox-csi` Stack, which Ankra owns. See [Stacks](/concepts/stacks). On teardown Ankra removes every other Stack's volume users before the CSI driver, so their volumes detach cleanly; a pod placed inside `proxmox-csi` itself gets no such ordering and can hang in `Terminating` once the driver is gone. The claim stays `Pending` until a pod uses it, because the class binds with `WaitForFirstConsumer`: a Proxmox disk is created on one host, so Kubernetes first picks the node, then the driver creates the disk on that node's host.

Volumes are `ReadWriteOnce` disks attached to one VM at a time, as an extra SCSI disk on the VM (`scsi1`, `scsi2`, ...). On directory storage such as `local` each volume is a raw image file; on LVM-thin, ZFS or Ceph it is a volume of that storage.

## How volumes follow Proxmox hosts

Ankra labels every node with:

* `topology.kubernetes.io/region: proxmox`, the name the driver uses for the Proxmox installation
* `topology.kubernetes.io/zone: <proxmox host>`, the host the VM runs on

It also registers each node with the providerID `proxmox://proxmox/<vmid>`, which is how the driver finds the VM to attach a disk to.

On a single-host cluster this is invisible. On a [host-spread cluster](/guides/proxmox-clusters#host-spread-placement) a volume on local storage belongs to one host, so a pod that uses it can only run on a node on that host. Kubernetes enforces this through the zone label. Use shared storage (Ceph RBD, for example) when a stateful pod must be able to move between hosts.

## Deleting a cluster deletes its volumes

The disks the driver provisioned do not belong to any of the cluster's VMs - the driver parks them on a placeholder VM ID, 9999 - so deleting the VMs alone would leave them on your storage. A deprovision therefore deletes them too, after the VMs are gone, but only once you accept it: the CLI lists the volumes and asks, and a scripted deprovision passes `--accept-volume-data-loss`.

```bash theme={null}
ankra cluster deprovision my-cluster                                   # lists the volumes, then asks
ankra cluster deprovision my-cluster --yes --accept-volume-data-loss   # non-interactive
```

A cluster that has no such disks is deprovisioned without the question. One that has some is not deprovisioned at all without the acceptance: the CLI stops before it sends the request, and the platform refuses a request that lacks it with HTTP 409, `Written consent is required`, naming the volumes - the cluster, its VMs and its disks stay as they are. Neither `--yes` nor `--force` stands in for it, and when Ankra cannot read the cluster's volume list it asks rather than assume there are none.

Only disks the driver named after a PersistentVolume of this cluster are deleted; nothing else on the host is touched. In the Proxmox VE web UI they are listed among the storage's **VM Disks**, owned by VM `9999` and named after their PersistentVolume (`vm-9999-pvc-...`).

## Clusters created before the fix

Before 30 October 2026, Ankra set neither the topology labels nor the providerID on nodes of **kubeadm** Proxmox clusters, and pointed the driver at the bare API address instead of `/api2/json`. On those clusters the node plugin restarts endlessly, and every claim stays `Pending`:

```bash theme={null}
ankra cluster get pods -n csi-proxmox
# proxmox-csi-plugin-node-...   CrashLoopBackOff
ankra cluster logs <proxmox-csi-plugin-node-pod> -n csi-proxmox -c proxmox-csi-plugin-node --previous
# Failed to get region or zone for node: <node>, region: , zone: , see documentation about topology labels
```

To repair such a cluster:

1. Add `Datastore.Audit` to the role of the cluster's Proxmox token (`pveum role modify <role> --append 1 --privs Datastore.Audit` on the Proxmox host).
2. Let Ankra correct the API address in the `proxmox-csi-plugin-config` Secret. It does so on the next reconcile, and restarts the controller when the Secret changes.
3. Replace the worker nodes. A node's providerID cannot change once it has registered, so existing nodes cannot be repaired in place, and new nodes get the labels and the providerID:

```bash theme={null}
# a new worker group, then retire the old one
ankra cluster node-group add <cluster-id> --name workers-v2 --instance-type px-medium --count 2 --wait
ankra cluster node-group delete <cluster-id> default
```

Control-plane nodes carry the control-plane taint, which the node plugin does not tolerate, so no node plugin runs there and they can stay as they are. If you removed that taint to run workloads on them, recreate the cluster instead.

## Troubleshooting

| Issue | Solution |
| - | - |
| `proxmox-csi-plugin-node` pods in `CrashLoopBackOff` with `Failed to get region or zone for node` | The node predates the fix. Replace it, as described in [Clusters created before the fix](#clusters-created-before-the-fix) |
| A claim stays `Pending` with `did not have enough free storage` | The driver publishes no capacity. Its controller log names the reason: `500 no such file '/cluster/resources'` is the bare API address: the Secret has not been corrected yet, or the controller started before Ankra began restarting it on a config change (on clusters reconciled before 30 October 2026), in which case `ankra cluster restart deployment proxmox-csi-plugin-controller -n csi-proxmox` reloads it, `failed to get proxmox storage config: not found` is a token without `Datastore.Audit`, and a connection error means the cluster's VMs cannot reach the API URL |
| A claim stays `Pending` without an event | Nothing uses it yet. With `WaitForFirstConsumer` the disk is created only when a pod is scheduled |
| A pod is stuck in `ContainerCreating` with an attach error | The token lacks `VM.Config.Disk` on the VM, or the disk's storage is not available on the VM's host |


# Helm Registries
Source: https://docs.ankra.ai/guides/registries

Connect external Helm repositories and OCI registries to Ankra for deploying custom and third-party charts.

Helm registries let you connect external Helm chart repositories to Ankra. Once connected, all charts in the registry become available as add-ons that you can deploy to your clusters through stacks.

> [!NOTE]
>
> Registries you add are available to your organisation. Team members can browse and deploy charts from shared registries.

***

## Supported Registry Types

Ankra supports two types of Helm registries:

> [card] HTTP Registries
>
> Traditional Helm repositories served over HTTP/HTTPS.
>
> Examples: ChartMuseum, Harbor, Nexus

> [card] OCI Registries
>
> Container registries that support Helm charts as OCI artifacts.
>
> Examples: GHCR, Google Artifact Registry, Amazon ECR

***

## Adding a Registry

**1. Navigate to Charts**

Go to **Add-ons** in the main navigation, then click **Manage registries**.

**2. Click Add**

Click the **Add** button to open the registry dialog.

**3. Enter Registry Details**

* **Registry Name**: A friendly name for the registry (e.g., `my-charts`)
* **Registry URL**: The full URL to your registry
* **Credential** (optional): Select a credential if authentication is required

**4. Save**

Click **Add** to connect the registry. Ankra will fetch the chart index and display available charts.

***

## Registry URL Examples

### OCI Registries

| Provider | URL Format |
| - | - |
| GitHub Container Registry | `oci://ghcr.io/YOUR_ORG/charts` |
| Google Artifact Registry | `oci://REGION-docker.pkg.dev/PROJECT/REPO` |
| Amazon ECR | `oci://ACCOUNT.dkr.ecr.REGION.amazonaws.com/charts` |
| Azure Container Registry | `oci://YOUR_REGISTRY.azurecr.io/charts` |
| Docker Hub | `oci://registry-1.docker.io/YOUR_ORG` |
| Harbor 2.8 and later | `oci://harbor.example.com/PROJECT` |

### HTTP Registries

| Provider | URL Format |
| - | - |
| ChartMuseum | `https://charts.example.com` |
| Harbor before 2.8 (ChartMuseum) | `https://harbor.example.com/chartrepo/PROJECT` |
| Nexus | `https://nexus.example.com/repository/helm-hosted/` |
| JFrog Artifactory | `https://artifactory.example.com/artifactory/helm-local` |

> [!TIP]
>
> OCI registries use the `oci://` prefix. Ankra automatically detects the registry type based on the URL.

***

## Authentication

Many registries require authentication. Create a registry credential first, then select it when adding the registry.

### Creating a Registry Credential

**1. Go to Credentials**

Navigate to **Credentials** in the Ankra dashboard.

**2. Add New Credential**

Click **Add** and select **Registry** as the provider.

**3. Enter Credentials**

* **Name**: A name for this credential (e.g., `ghcr-auth`)
* **Username**: Your registry username
* **Password**: Your registry password or access token

**4. Save**

Click **Create** to save the credential.

### Provider-Specific Authentication

> [accordion] GitHub Container Registry (GHCR)
>
> 1. Create a Personal Access Token with `read:packages` scope
> 2. Username: Your GitHub username
> 3. Password: The Personal Access Token

> [accordion] Google Artifact Registry
>
> 1. Create a service account with Artifact Registry Reader role
> 2. Username: `_json_key`
> 3. Password: The JSON key file contents

> [accordion] Amazon ECR
>
> 1. Get an auth token: `aws ecr get-login-password`
>
> 2. Username: `AWS`
>
> 3. Password: The token from the command above
>
> > [!WARNING]
> >
> > ECR tokens expire after 12 hours. Refresh the credential before it expires.

> [accordion] Docker Hub
>
> 1. Create an Access Token in Docker Hub settings
> 2. Username: Your Docker Hub username
> 3. Password: The Access Token

***

## Managing Registries

### View Registry Charts

Click on a registry to browse all available charts. Each chart shows:

* Chart name and description
* Latest version
* Last updated timestamp
* Keywords and maintainers

### Delete a Registry

1. Go to **Add-ons** and click **Manage registries**
2. Click on the registry you want to remove
3. Click the **More** menu (⋮) and select **Delete**

> [!WARNING]
>
> Deleting a registry removes it from Ankra but doesn't affect deployed add-ons. Existing deployments will continue to work.

***

## How Registry Sync Works

Ankra automatically syncs your registries to keep chart listings up to date.

### Sync Schedule

* **Default interval**: Every 2 minutes
* **Configurable**: Set a custom sync interval per registry (60 seconds to 24 hours, or 0 to disable)
* **Disable sync**: Set interval to 0 to disable automatic sync

### Sync Process

**1. Check for Updates**

Ankra checks the registry's index.yaml (HTTP) or manifest (OCI) using ETag/Last-Modified headers to avoid unnecessary downloads.

**2. Detect New Versions**

New chart versions are identified by comparing the index against previously synced versions.

**3. Download Charts**

New versions are downloaded and stored securely. Ankra extracts README, values.yaml, and JSON schema files.

**4. Update Index**

The chart browser is updated with new versions available for deployment.

### Version Tracking

Ankra tracks every chart version with:

* **Version number** and semantic versioning
* **Digest** for integrity verification
* **Created date** from the chart metadata
* **Deprecation status** if marked in Chart.yaml

> [!TIP]
>
> Failed version syncs are automatically retried with exponential backoff. Check the registry details page to see sync status.

***

## Using Registry Charts

Once a registry is connected, its charts appear in the add-on browser:

1. **Create or edit a stack**
2. **Click Add Component** → **Add-on**
3. **Browse or search** for charts from your registries
4. **Select the chart** and configure values
5. **Deploy the stack** to your cluster

Charts from your registries work exactly like built-in add-ons-they support custom values, dependencies, and GitOps sync.

### Example: Envoy Gateway and the Gateway API

Envoy Gateway ships its chart as an OCI artifact on Docker Hub, so it installs through an organisation registry rather than the built-in catalogue:

1. Add an OCI registry with the URL `oci://registry-1.docker.io/envoyproxy`. It is public, so no credential is needed.
2. Add the `gateway-helm` chart to a stack as an add-on. Ankra recognises it as Envoy Gateway. Pin the chart version, as for any add-on.
3. Deploy the stack. The chart installs the Gateway API and Envoy Gateway CRDs with the release. Turn on **Server-Side Apply** in the [add-on settings](/concepts/addon-settings), which is the recommended option for charts that carry large CRDs.
4. Define your `GatewayClass`, `Gateway` and `HTTPRoute` resources as [manifests](/concepts/stacks#manifests) in the same stack, with the Envoy Gateway add-on as their parent so they are applied after the CRDs exist.

The same steps apply to any Gateway API implementation that publishes a Helm chart, such as NGINX Gateway Fabric.

***

## Global Helm Registries

Besides the registries you connect, every organisation sees a curated set of preloaded Helm registries. They power the add-on catalog and live in the public [ankraio/ankra-global-resources](https://github.com/ankraio/ankra-global-resources) repository:

* `helm_registries/` - the preloaded chart repositories that appear in the add-on catalog.
* `addons/` - the catalog's add-on definitions. See [Publishing Add-ons](/platform/addon-publishing).

To propose a registry for every Ankra user:

1. Fork [ankraio/ankra-global-resources](https://github.com/ankraio/ankra-global-resources).
2. Add your Helm registry definition to the `helm_registries/` folder.
3. Open a pull request that describes the charts and what they are for.
4. Once it is merged, the charts are available to every organisation.

***

## Troubleshooting

### Registry Not Loading

| Issue | Solution |
| - | - |
| Connection timeout | Check the registry URL is accessible from Ankra |
| Authentication failed | Verify credentials are correct and not expired |
| No charts found | Ensure the registry contains Helm charts, not just container images |
| OCI not supported | Some registries need OCI support enabled (e.g., Harbor) |

### Sync Issues

| Issue | Solution |
| - | - |
| Charts not updating | Check the sync interval hasn't been disabled (set to 0) |
| Some versions missing | Check registry details for failed versions and retry |
| Stale data | Registry may have an issue serving index.yaml-verify externally |

### Common Errors

**"invalid reference format"**

* The URL format is incorrect. OCI URLs must start with `oci://`

**"unauthorized: authentication required"**

* Add or update the registry credential

**"manifest unknown"**

* The chart doesn't exist at the specified path. Check the repository structure.


# Roles & Access
Source: https://docs.ankra.ai/guides/roles-and-access

Govern who can do what in your organisation with roles, scoped assignments, cluster groups, and an audit log.

Ankra controls access with **roles** that you assign at a **scope**. A role is a set of permissions; a scope decides where those permissions apply - the whole organisation, a single cluster, a **cluster group**, or a [**project**](/concepts/projects). A role can also bundle Kubernetes access that Ankra provisions on every cluster in scope, so platform permissions and `kubectl` access are granted together.

> [!NOTE]
>
> Roles and scoped assignments replace the earlier admin/member split. Existing members keep working: `admin` and `member` map onto the new model, and wider roles become available as you adopt them.

***

## How access is decided

```mermaid theme={null}
flowchart LR
    Assignment["Assignment (member + role + scope)"] --> Resolve[Ankra resolves scope]
    Resolve -->|organisation| AllClusters[Every cluster]
    Resolve -->|cluster| OneCluster[One cluster]
    Resolve -->|cluster group| GroupClusters[Clusters in the group]
    Resolve -->|project| ProjectClusters[Clusters and resources in the project]
    Assignment -->|"role bundles kube access"| Kube[Kubernetes RBAC on each cluster]
```

An **assignment** ties a member to a role at a scope. When the role includes Kubernetes access, Ankra reconciles the matching [Cluster Access](/guides/cluster-access) grants onto every cluster the scope resolves to, and keeps them in sync as group membership changes.

***

## Built-in roles

| Role | What it grants |
| - | - |
| `owner` | Full control, including organisation deletion and ownership transfer |
| `admin` | Full control except deleting the organisation (includes billing and the audit log) |
| `operator` | Day-2 operations: deploy, operate clusters, act on alerts, `kubectl` write and exec |
| `member` | Build and deploy stacks, variables, and applications |
| `viewer` | Read-only access plus ask-mode AI |

`read-only` from the earlier model maps to `viewer`.

The organisation role a member holds is a floor that reaches every project. A sixth membership choice, **Project only**, holds no organisation role at all: the member reaches only the projects they are given a role in. See [Project-only members](#project-only-members).

You can also define **custom roles** that bundle a specific permission set and, optionally, a Kubernetes access level provisioned across the assignment's scope.

### Kubernetes access in custom roles

The Kubernetes access level a custom role bundles (`view`, `edit`, `admin` or `cluster-admin`) becomes a [Cluster Access](/guides/cluster-access) grant on every cluster in the assignment's scope. That access is always clamped to the ceiling of the [organisation access policy](/guides/cluster-access#organisation-access-policy): a role that bundles `cluster-admin` in an organisation whose ceiling is `edit` gives `edit`. When the ceiling is lowered, role-bundled access drops to it within about a minute. Grants made directly on a cluster are not changed when the policy changes.

Two permissions control the edges of Kubernetes access:

* **`kube_access.policy`** changes the organisation access policy. Owners and admins hold it. It is human-only, so an API token carries it only if the token's scopes name it.
* **`kube_access.elevate`** is break-glass: its holder can give itself time-boxed, reasoned access to a cluster within the policy, and nothing else. It cannot grant anyone else, create a standing grant, list grants or change the policy. A custom role holding only `kube_access.elevate` and `kube_access.use`, with Kubernetes access set to `view`, is the recommended role for automation that needs break-glass access - see [Break-glass elevation](/guides/cluster-access#break-glass-elevation).

***

## Permission matrix

Every permission Ankra checks, and which built-in role holds it. A custom role can hold any combination of these. The table is generated from the platform's permission registry, so it lists exactly what the platform enforces.

Two patterns to notice when you review access:

* **Every built-in role can read.** All read permissions, including ask-mode AI (`ai.use`), are shared by every role. The exception is `audit.read`: only `admin` and `owner` hold it, and a custom role can grant it on its own.
* **Some powers sit only with `admin` and `owner`.** Among them are revealing stored credentials (`credentials.reveal`), approving promotions (`promotions.approve`), managing members and tokens, and choosing the AI provider (`ai.manage`).
* **Reading a Kubernetes Secret's values is its own permission.** `kubernetes.read` shows a Secret's key names and a digest of each value. The digest changes when the value changes, and it is keyed per cluster, so it cannot be used to check a guessed value. The values need `kubernetes.secrets_reveal` (in the console, **Reveal values**; in the CLI, `ankra cluster get secrets <name> -n <namespace> --reveal`), which `operator`, `admin` and `owner` hold and `member` and `viewer` do not, and every reveal is written to the [audit log](/guides/audit-log). Custom roles that already held `kubernetes.write` when the permission was introduced on 2026-10-01 were given it too, because a role that can apply workloads can already mount a Secret into one. Other custom roles, and API tokens restricted to a list of scopes, get it only when you add it. The same permission is needed to reveal the passwords and keys in a Helm release's values, and to read or change Secrets with `kubectl` through Ankra, whatever role the [access grant](/guides/cluster-access#secrets-need-their-own-permission) gives.

**Human-only** permissions reach an API or MCP token only when the token names them explicitly. A token that asks for "everything its owner can do" does not get them, so an automated caller cannot approve its own promotion or its own AI action, or change the cluster access policy that bounds it.

### Organisation, people and audit

| Permission | What it allows | `owner` | `admin` | `operator` | `member` | `viewer` |
| - | - | :-: | :-: | :-: | :-: | :-: |
| `organisation.read` | Read organisation settings and metadata | ✓ | ✓ | ✓ | ✓ | ✓ |
| `organisation.manage` | Update organisation settings (name, slug, MFA requirement, AI insight settings) | ✓ | ✓ | | | |
| `organisation.delete` | Delete the organisation | ✓ | | | | |
| `members.read` | List members, invites, and their roles | ✓ | ✓ | ✓ | ✓ | ✓ |
| `members.invite` | Invite new members and revoke pending invites | ✓ | ✓ | | | |
| `members.manage` | Change member roles and remove members | ✓ | ✓ | | | |
| `members.mfa_reset` | Reset another member's MFA factors | ✓ | ✓ | | | |
| `billing.read` | Read subscription, invoices, and usage analytics | ✓ | ✓ | ✓ | ✓ | ✓ |
| `billing.manage` | Change subscription, open the billing portal, sync billing | ✓ | ✓ | | | |
| `tokens.manage` | Revoke organisation members' API and kube tokens | ✓ | ✓ | | | |
| `audit.read` | Read the organisation audit log | ✓ | ✓ | | | |

### Clusters and Kubernetes

| Permission | What it allows | `owner` | `admin` | `operator` | `member` | `viewer` |
| - | - | :-: | :-: | :-: | :-: | :-: |
| `clusters.read` | Read clusters, their resources, and their state | ✓ | ✓ | ✓ | ✓ | ✓ |
| `clusters.create` | Import or provision new clusters | ✓ | ✓ | | | |
| `clusters.write` | Edit cluster configuration and metadata | ✓ | ✓ | ✓ | ✓ | |
| `clusters.operate` | Scale, upgrade, start/stop, reconcile, and sync clusters | ✓ | ✓ | ✓ | | |
| `clusters.delete` | Deprovision or delete clusters | ✓ | ✓ | | | |
| `agents.manage` | Mint agent bootstrap tokens and upgrade cluster agents | ✓ | ✓ | | | |
| `kubernetes.read` | Read Kubernetes resources, pods, and logs through the platform | ✓ | ✓ | ✓ | ✓ | ✓ |
| `kubernetes.write` | Apply, patch, and delete Kubernetes resources through the platform | ✓ | ✓ | ✓ | | |
| `kubernetes.exec` | Open pod terminals, exec, and port-forward sessions | ✓ | ✓ | ✓ | | |
| `kubernetes.secrets_reveal` | Reveal Kubernetes Secret values through the platform (every reveal is audited) | ✓ | ✓ | ✓ | | |
| `kube_access.use` | Mint kubeconfigs and kube tokens for granted clusters | ✓ | ✓ | ✓ | ✓ | |
| `kube_access.manage` | Grant and revoke cluster Kubernetes access for members | ✓ | ✓ | | | |
| `kube_access.elevate` | Give yourself a time-boxed, reasoned cluster access grant within the organisation access policy (break-glass) | ✓ | ✓ | | | |
| `kube_access.policy` | Change the organisation cluster access policy (an API token carries it only by naming it) (human-only) | ✓ | ✓ | | | |

### Stacks, configuration and secrets

| Permission | What it allows | `owner` | `admin` | `operator` | `member` | `viewer` |
| - | - | :-: | :-: | :-: | :-: | :-: |
| `stacks.read` | Read stacks, addons, manifests, and drafts | ✓ | ✓ | ✓ | ✓ | ✓ |
| `stacks.write` | Create and edit stacks, addons, manifests, and drafts | ✓ | ✓ | ✓ | ✓ | |
| `stacks.deploy` | Deploy, sync, and roll back stacks and addons | ✓ | ✓ | ✓ | ✓ | |
| `stacks.delete` | Delete stacks, addons, and manifests | ✓ | ✓ | ✓ | ✓ | |
| `variables.read` | Read organisation and cluster variables | ✓ | ✓ | ✓ | ✓ | ✓ |
| `variables.write` | Create, update, and delete variables | ✓ | ✓ | ✓ | ✓ | |
| `profiles.read` | Read stack profiles and their versions | ✓ | ✓ | ✓ | ✓ | ✓ |
| `profiles.write` | Create, edit, and publish stack profiles | ✓ | ✓ | | ✓ | |
| `profiles.share` | Share stack profiles with other organisations | ✓ | ✓ | | | |
| `helm.read` | Browse helm registries and charts | ✓ | ✓ | ✓ | ✓ | ✓ |
| `helm.manage` | Manage helm registries and their credentials | ✓ | ✓ | | | |
| `git.manage` | Connect and manage git providers and GitOps repositories | ✓ | ✓ | | | |
| `sops.use` | Encrypt and decrypt values with the organisation SOPS key | ✓ | ✓ | ✓ | ✓ | |
| `sops.manage` | Initialise and rotate the organisation SOPS key | ✓ | ✓ | | | |
| `credentials.read` | List credentials and read their metadata | ✓ | ✓ | ✓ | ✓ | ✓ |
| `credentials.write` | Create and update credentials | ✓ | ✓ | | | |
| `credentials.delete` | Delete credentials | ✓ | ✓ | | | |
| `credentials.reveal` | Reveal stored credential secret material | ✓ | ✓ | | | |

### Applications and delivery

| Permission | What it allows | `owner` | `admin` | `operator` | `member` | `viewer` |
| - | - | :-: | :-: | :-: | :-: | :-: |
| `applications.read` | Read applications and their workflow state | ✓ | ✓ | ✓ | ✓ | ✓ |
| `applications.write` | Create and edit applications | ✓ | ✓ | ✓ | ✓ | |
| `applications.deploy` | Deploy applications | ✓ | ✓ | ✓ | ✓ | |
| `applications.delete` | Delete applications | ✓ | ✓ | | ✓ | |
| `pipelines.read` | Read pipeline definitions, schedules, and step templates | ✓ | ✓ | ✓ | ✓ | ✓ |
| `pipelines.operate` | Run, re-run, cancel, and dispatch pipelines | ✓ | ✓ | ✓ | ✓ | |
| `pipelines.manage` | Manage pipeline definitions, schedules, step templates, and organisation CI policy | ✓ | ✓ | ✓ | | |
| `promotions.read` | Read promotions, their approvals, and their history | ✓ | ✓ | ✓ | ✓ | ✓ |
| `promotions.request` | Request a promotion between environments | ✓ | ✓ | ✓ | ✓ | |
| `promotions.approve` | Approve or reject a requested promotion (human-only) | ✓ | ✓ | | | |
| `environments.read` | Read environments, their instances, and their promotion edges | ✓ | ✓ | ✓ | ✓ | ✓ |
| `environments.operate` | Create, hydrate, extend, and destroy ephemeral environment instances | ✓ | ✓ | ✓ | ✓ | |
| `environments.manage` | Manage environment definitions, protection rules, and promotion edges | ✓ | ✓ | ✓ | | |
| `executions.read` | Read executions, operations, and their events | ✓ | ✓ | ✓ | ✓ | ✓ |
| `executions.operate` | Cancel and retry executions and operations | ✓ | ✓ | ✓ | | |
| `runs.read` | Read cross-cluster runs and stream their progress | ✓ | ✓ | ✓ | ✓ | ✓ |
| `runs.operate` | Start and cancel cross-cluster runs | ✓ | ✓ | ✓ | | |
| `automations.read` | Read automations, their triggers, and their run history | ✓ | ✓ | ✓ | ✓ | ✓ |
| `automations.manage` | Create, edit, enable, and delete automations | ✓ | ✓ | | | |

### Alerts, security and backups

| Permission | What it allows | `owner` | `admin` | `operator` | `member` | `viewer` |
| - | - | :-: | :-: | :-: | :-: | :-: |
| `alerts.read` | Read alerts, triggers, and integrations | ✓ | ✓ | ✓ | ✓ | ✓ |
| `alerts.write` | Acknowledge, resolve, snooze, and annotate alert triggers | ✓ | ✓ | ✓ | | |
| `alerts.manage` | Manage alert definitions, integrations, and notification routes | ✓ | ✓ | | | |
| `security.read` | Read fleet security findings, posture, and disposition policies | ✓ | ✓ | ✓ | ✓ | ✓ |
| `security.triage` | Acknowledge fleet security findings | ✓ | ✓ | ✓ | | |
| `security.manage` | Create, edit, and revoke accepted-risk security policies | ✓ | ✓ | | | |
| `backups.read` | Read backup vaults, stack backup policies, and restore points | ✓ | ✓ | ✓ | ✓ | ✓ |
| `backups.operate` | Create restore points and run restores and data clones | ✓ | ✓ | ✓ | ✓ | |
| `backups.manage` | Manage backup vaults and stack backup policies | ✓ | ✓ | | | |

### AI

| Permission | What it allows | `owner` | `admin` | `operator` | `member` | `viewer` |
| - | - | :-: | :-: | :-: | :-: | :-: |
| `ai.use` | Use ask-mode AI chat and read AI insights | ✓ | ✓ | ✓ | ✓ | ✓ |
| `ai.execute` | Run agent-mode AI and confirm AI-proposed actions | ✓ | ✓ | ✓ | ✓ | |
| `ai.manage` | Manage AI providers, MCP servers, skills, trusted actions, and spend caps | ✓ | ✓ | | | |
| `ai_actions.approve` | Approve or reject a parked AI action from an API or MCP token (a token carries it only by naming it) (human-only) | ✓ | ✓ | | | |

***

## Scopes

| Scope | Applies to |
| - | - |
| **Organisation** | Every cluster and resource in the organisation |
| **Cluster** | A single named cluster |
| **Cluster group** | Every cluster that a group resolves to |
| **Project** | Every cluster, application, environment, profile, repository and project-scoped shared resource the [project](/concepts/projects) holds, now and later |

A project assignment never confers the permissions that are about the organisation as a whole. `organisation.*`, `members.*`, `billing.*`, `tokens.*`, `audit.*`, `projects.*`, `kube_access.manage`, `kube_access.policy`, `sops.manage`, `secrets.manage`, `git.manage`, `security.manage`, `ai.manage`, `workspaces.manage` and `profiles.share` are dropped from it whatever the role, so an `admin` of one project is the resource half of admin inside that project: it deploys, operates and configures everything in the project, and cannot invite members, see invoices, mint organisation tokens or create projects.

> [!TIP]
>
> Assign the narrowest scope that fits. A support engineer who only triages one team's clusters gets a `viewer` (or `operator`) role on that team's **cluster group** or **project**, not the whole organisation.

### Project-only members

A role assigned in a project limits what a member can **do** there. It does not by itself limit what they can **see**, because every member also holds an organisation role - `viewer` at the least - that reaches every project read-only. To limit a person to one project, make them a **Project only** member:

* Choose **Project only** as the membership role when you invite them, or change it on their row on the **People** page. From the CLI, `ankra org invite <email> --role project --project <project> --project-role <role>` invites them straight into one project.
* Then assign them `admin`, `operator`, `member` or `viewer` in each project they should reach (`member` is the CLI's default). They see those projects and nothing else.
* They can never hold an organisation-level permission - members, billing, other members' tokens, the audit log and organisation settings are out of reach whatever role they are given in a project - and when they sign in they land in their current project if they still reach it, otherwise in the oldest project they reach.

A project-only member can be made an organisation member later by changing the membership role on People; nothing is lost in either direction. Tokens a project-only member mints reach only the projects they reach, and an MCP token they mint is pinned to the project they are working in. Ankra Cloud console access needs organisation-wide membership for now: a project-only member is refused there, and everything in the Ankra platform itself works for them.

***

## Cluster groups

A **cluster group** is a named set of clusters used as an assignment scope. Groups can be:

* **Static** - you pin specific clusters as members.
* **Dynamic** - a label selector evaluated against cluster labels, so clusters join and leave the group automatically as their labels change.

Manage groups on the **Roles** page of your organisation (**Organisation → Roles**, section **Cluster Groups**). A preview shows exactly which clusters a group currently resolves to before you use it in an assignment.

### Matching on a cluster's environment

In a dynamic group, the `environment` key matches the **Environment** set on each cluster - on the cluster's **Overview** page, or with `--environment` on `ankra cluster aws create`. The match is exact and case-sensitive, so `production` does not match a cluster set to `Production`, and a cluster with no environment never matches. Change a cluster's environment and it moves in or out of every group on that key, but access does not follow at once: platform permissions catch up within about a minute, and the Kubernetes access those assignments bundle within about a minute and a half. That applies in both directions, so a cluster moved out of `production` keeps the access its old groups gave for that long.

Every other key matches the cluster's labels. Labels cannot be set from the console or the CLI yet, so build environment-based access on the `environment` key.

***

## Example: restrict production to a DevOps role

Give a DevOps team full control of production, including Secret values, and everyone else read-only access with no actions.

**1. Mark the production clusters**

Set **Environment** to `production` on each production cluster's **Overview** page.

**2. Create a production group**

Under **Organisation → Roles → Cluster Groups**, create a **dynamic** group with the selector `environment` = `production`. Check that the preview lists exactly your production clusters.

**3. Create the DevOps role**

Create a custom role holding the permissions the team needs - for full control, `kubernetes.read`, `kubernetes.write`, `kubernetes.exec`, `kubernetes.secrets_reveal` and `clusters.operate` - and give it the `cluster-admin` Kubernetes access level so `kubectl` has full control too. The `admin` level stops short of that: it does not manage cluster-wide objects such as nodes, namespaces and custom resource definitions. The built-in `operator` role holds the same platform permissions but bundles no `kubectl` access.

**4. Assign it to the production group**

Assign the DevOps role to each team member with the production group as the scope.

**5. Give everyone else viewer**

Assign `viewer` at organisation scope. Viewers read resources across every cluster but cannot apply, delete, restart, scale, open a terminal or reveal Secret values.

> [!WARNING]
>
> Assignments only add permissions. A role assigned at organisation scope also reaches production, so do not give anyone outside the DevOps team a writing role at organisation scope. Scope it to a non-production group instead, such as a dynamic group on `environment` = `staging`.

> [!NOTE]
>
> `viewer` still reads pod logs, ConfigMaps and environment values written directly into a pod spec, because `kubernetes.read` covers them. Only Secret values need `kubernetes.secrets_reveal`, so keep credentials in Secrets.

***

## Assigning a role

**1. Open Roles & Access**

Go to **Organisation → Roles**. The same page holds **Cluster Groups** if you need a group scope. It is shown to members who can manage members (`admin` and `owner` by default).

**2. Pick a member and role**

Choose an organisation member, then a built-in or custom role.

**3. Choose the scope**

Assign at the organisation, a single cluster, a cluster group, or a [project](/concepts/projects). On the **People** page, **Give more access on some clusters** offers the same places, with each project listed as `<name> (project)`.

**4. Save**

Ankra applies the assignment immediately. If the role bundles Kubernetes access, it reconciles the grants onto every cluster in scope.

To list the built-in and custom roles from the [CLI](/reference/cli/org):

```bash theme={null}
ankra org roles
```

The CLI has no commands for assignments or cluster groups; manage them on the **Roles** page. `ankra project members <project>` lists who reaches a project and whether each person's role was given for the whole organisation or for that project. See [Projects in the CLI](/integrations/ankra-cli#projects).

***

## Audit log

Every access change - invitations, role assignments, cluster-group edits, revocations - is recorded in the organisation **Audit log** under **Organisation → Audit log**, so you can see who changed what and when.

***

## Related

> [card] [Cluster Access](/guides/cluster-access)
>
> Scoped, SSO-backed kubectl access.

> [card] [Organisations](/concepts/organisations)
>
> Invite and manage members.

> [card] [Organisation Settings](/platform/organisation-settings)
>
> Configure organisation-wide behaviour.

> [card] [API Tokens](/reference/tokens)
>
> Create tokens for scripts, CI, and MCP clients.


# Scaleway Clusters
Source: https://docs.ankra.ai/guides/scaleway-clusters

Create a Kubernetes cluster on Scaleway Instances in your own Scaleway project, behind a Public Gateway, with Ankra installing and operating Kubernetes, ingress, TLS and DNS.

Choose Scaleway Instances when you want a Kubernetes cluster on Scaleway servers in a project you own, with the nodes on a private network and no public addresses. Ankra creates the Instances, the Private Network and a Public Gateway in your Scaleway project, installs Kubernetes and the Scaleway cloud integration, and then operates the cluster for you - this is an **Ankra Managed** cluster. Scaleway bills you directly.

> [!WARNING]
>
> **Closed beta.** Scaleway as a cluster provider is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request - until it is, Scaleway does not appear in the create dialog or among the credential providers, and its endpoints are not served. [Contact support](/platform/support) to have it turned on for your organisation.

If you would rather have Scaleway run the control plane, use Scaleway Kapsule instead - see [Scaleway Kapsule](/guides/managed-kubernetes#scaleway-kapsule-closed-beta).

## Before you start

* A **Scaleway project**, ideally one dedicated to Ankra: every resource Ankra creates is scoped to that one project.
* An **API key on a Scaleway IAM application** with project-scoped permissions, stored as a [Scaleway credential](/platform/credentials/scaleway). A second, narrower key for the in-cluster components is recommended - see [Scaleway specifics](#scaleway-specifics).
* An **SSH key credential**. Scaleway clusters take exactly one. See [SSH Key Credentials](/platform/credentials/ssh-key).
* A **region and a zone** in that region, for example `fr-par` and `fr-par-1`, and either a private CIDR for a new Private Network (a prefix between `/20` and `/29`) or an existing Private Network in the region.

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **Scaleway** under **Ankra Managed**.
>
> **2. Credentials**
>
> Pick the **Scaleway credential**, the **Runtime credential** the in-cluster controller and CSI driver use (**Reuse provisioning credential** is the default), the **SSH Key**, then the **Region** and **Zone**. Regions and zones load live from your project.
>
> **3. Network**
>
> Choose **Create a dedicated network** and enter the **Network CIDR**, or **Use an existing network** in the region. Pick the **Gateway type**, set **Gateway allowed IPs** to the CIDRs that may reach the bastion (empty keeps Scaleway's defaults), and the **Managed bastion SSH port**. **Storage retention on teardown** decides what happens to persistent volumes and load balancers when the cluster is deleted: **Retain persistent storage (recommended)** or **Delete provider storage during teardown**.
>
> **4. Compute**
>
> Set the control-plane count (1, 3 or 5) and instance type, then one or more worker node pools, each with an instance type, count and optional autoscaling. Instance types can be filtered by **ARM** or **Intel/AMD**. The cost summary is marked incomplete: the gateway, flexible IP, storage, load balancer and transfer charges are not in it.
>
> **5. Kubernetes**
>
> Keep **kubeadm** (the default, Cilium only) or pick **K3s** with a choice of CNI, and optionally the version. On kubeadm, etcd runs stacked on the control plane or on 3 or 5 dedicated nodes. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time).
>
> **6. GitOps**
>
> Optionally connect a Git repository; without one the `scaleway-cloud-provider` stack is still deployed, just not committed. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind a Scaleway Load Balancer.
> * **Include DNS Integration** - external-dns, so Ingress hostnames publish their DNS records automatically.
>
> **7. Review**
>
> Name the cluster and click **Run preflight**. The checks read your project live; when they pass, click **Create cluster**. A progress view follows the network, gateway, Instances, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials scaleway create --name scw-prod --project-id <project-id> --access-key <access-key>   # prompts for the secret key
> ankra credentials scaleway ssh-key create --name my-ssh-key --generate
>
> # What the credential can use
> ankra cluster scaleway locations --credential-id <scaleway-credential-id>
> ankra cluster scaleway instance-types --credential-id <scaleway-credential-id> --zone fr-par-1
> ankra cluster scaleway gateway-types --credential-id <scaleway-credential-id> --zone fr-par-1
> ankra cluster scaleway networks --credential-id <scaleway-credential-id> --region fr-par
>
> # Create the cluster; `preflight` takes the same flags and checks the request first
> ankra cluster scaleway create \
>   --name my-cluster \
>   --credential-id <scaleway-credential-id> \
>   --runtime-credential-id <runtime-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --region fr-par \
>   --zone fr-par-1 \
>   --network-ip-range 10.64.0.0/20 \
>   --gateway-allowed-ips 203.0.113.10/32 \
>   --control-plane-type DEV1-M \
>   --worker-count 2 \
>   --worker-type DEV1-M
> ```
>
> Run `ankra cluster scaleway preflight` with the same flags first. Use `--private-network-id` instead of `--network-ip-range` to adopt an existing network. `--distribution`, `--cni`, `--etcd-topology`, `--gateway-type`, `--bastion-port`, `--retention-policy`, `--include-networking=false` and `--include-dns=false` cover the other choices. Preflight reports each check as pass, warn or fail; a quota warning means the instance types are in stock, not that your project has hard-quota headroom.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/scaleway/preflight \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d @cluster.json
>
> curl -X POST https://platform.ankra.app/api/v1/clusters/scaleway \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d @cluster.json
> ```
>
> With `cluster.json`:
>
> ```json theme={null}
> {
>   "name": "my-cluster",
>   "credential_id": "<scaleway-credential-id>",
>   "runtime_credential_id": "<runtime-credential-id>",
>   "ssh_key_credential_id": "<ssh-key-credential-id>",
>   "region": "fr-par",
>   "zone": "fr-par-1",
>   "network_ip_range": "10.64.0.0/20",
>   "gateway_allowed_ips": ["203.0.113.10/32"],
>   "control_plane_count": 1,
>   "control_plane_type": "DEV1-M",
>   "node_groups": [
>     {"name": "default", "instance_type": "DEV1-M", "count": 2}
>   ],
>   "retention_policy": "retain"
> }
> ```
>
> Defaults: `gateway_type` `VPC-GW-S`, `bastion_port` `61000` (or any port from 1024 to 59999), `control_plane_type` and `worker_type` `DEV1-M`, `distribution` `kubeadm`, `etcd_topology` `stacked`, `retention_policy` `retain`, and `include_networking` and `include_dns` `true`. `private_network_id` and `network_ip_range` are mutually exclusive; without either, Ankra derives a CIDR. `control_plane_count` is 1 to 9.

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created in your project

* **A Private Network** with its IPAM subnet, unless you adopted an existing one. An adopted network is never deleted.
* **A Public Gateway** (v2) with a flexible IP, attached to the Private Network. It is the nodes' route to the internet and runs the managed SSH bastion.
* **A security group** that opens the Kubernetes and CNI overlay ports only to the cluster's private CIDR - never publicly.
* **The Instances** for the control plane, workers and any dedicated etcd nodes, with private addresses only, and a generated SSH key.
* **The `scaleway-cloud-provider` stack** in `kube-system`: the Scaleway cloud controller manager (Load Balancers for `LoadBalancer` Services) and the CSI driver (block volumes), both using the runtime credential.

## Scaleway specifics

* **Region and zone.** Private Networks are regional; Instances, block volumes, security groups and the Public Gateway are zonal. The zone must belong to the region (`fr-par-1` in `fr-par`).
* **Runtime credential.** The runtime credential's key is installed in the cluster for the controller and CSI driver, so give it a second IAM application with narrower permissions than the provisioning one - see [Scaleway Credentials](/platform/credentials/scaleway#least-privilege-permissions). It must target the same project. Without one, the provisioning credential is reused.
* **The bastion is the gateway's.** SSH goes through the Public Gateway's managed bastion as the user `bastion` on port `61000` by default - not port 22 on a VM. **Settings → Access** shows the commands, and `GET /api/v1/clusters/scaleway/{cluster_id}/access-info` returns the host, port and users. Restrict **Gateway allowed IPs** to your own addresses. `ankra cluster scaleway bastion status` reports its health; there is no bastion resize.
* **Storage classes.** `scw-bssd` (the default) deletes a volume when its claim is deleted; `scw-bssd-retain` keeps it. That Kubernetes reclaim policy is separate from the cluster's `retention_policy`, which decides what a cluster teardown does with tagged volumes and load balancers.
* **Stopping keeps the Instances.** A stop powers the Instances off and keeps them with their volumes, so the cluster comes back with its state. Root storage, the Public Gateway, flexible IPs, load balancers and retained volumes keep billing while it is stopped.
* **Estimates are incomplete.** Scaleway's APIs do not return gateway, flexible IP, block storage or load balancer prices, so the wizard total leaves them out. Check Scaleway's pricing and your billing console.

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `scaleway`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| `401` or `403` from Scaleway | Check the Project ID, that the API key is active and project-scoped, and that its IAM application has the permission sets listed on [Scaleway Credentials](/platform/credentials/scaleway#least-privilege-permissions). Rotate the key rather than widening it to the Organization |
| `404` for a resource you know exists | Scaleway IDs are region- or zone-qualified; check the region and zone |
| `429` or `5xx` from Scaleway | Ankra retries these with backoff; let the operation finish, then retry the Ankra operation rather than creating the cluster again |
| Instance type unavailable | Refresh the zone's catalog or pick another type or zone. Stock is not the same as quota |
| Preflight fails on the network | The adopted network has no IPv4 subnet, or the CIDR is outside `/20` to `/29` or overlaps another network |
| Nodes stay `NotReady` or keep the `uninitialized` taint | Check the CCM, CSI and CNI pods in `kube-system` and the private routes through the gateway |
| Resources remain after a delete | With `retention_policy: retain`, tagged volumes and load balancers are kept on purpose and keep billing; delete them in the Scaleway console when you no longer need them |


# Security Reports
Source: https://docs.ankra.ai/guides/security-reports

Email a weekly or monthly summary of a cluster's vulnerability posture to the people who need it, or send one on demand.

Ankra can email a recurring security report for a cluster - a snapshot of its vulnerability posture drawn from the [Security Center](/guides/cluster-security). Reports run on a weekly or monthly schedule, go to a recipient list you control, and can also be sent immediately.

***

## What the report contains

The report reflects the same data as the cluster's Security view: actionable findings by severity, and how the posture has moved since the previous report. Findings on the CISA Known Exploited Vulnerabilities catalog get their own banner and a **KEV** marker in the top-CVE table, with the FIRST EPSS exploitation probability where the platform holds one; package upgrades that clear a known-exploited CVE are listed first under **Fix these first**. Accepted risk is excluded from actionable counts - the report is built for the people who need to know what still requires attention, not for restating everything Trivy has ever observed.

***

## Prerequisites

* The cluster has the [Trivy Operator integration](/guides/cluster-security#prerequisites) installed and producing reports. If the scanner state is `not_installed` or `installed_no_reports`, there is no data to report on.
* Access to the cluster's settings.

***

## Schedule a report

**1. Open the cluster's settings**

Open the cluster in Ankra, go to its settings, and choose **Integrations**.

**2. Schedule the security report**

Open the security report scheduling options and choose a **weekly** or **monthly** cadence.

**3. Add recipients**

Enter the email addresses that should receive the report. Recipients do not need to be Ankra users.

**4. Save**

Save the schedule. The report is generated and emailed on the chosen cadence from now on.

> [!TIP]
>
> Report scheduling is also offered from the cluster's **Security** view, as a secondary action next to the scanner status.

***

## Send a report now

Next to the schedule there is a send-now action that emails the current report to the configured recipients immediately. Use it to verify delivery after setting up a schedule, or to share the current posture ahead of a review without waiting for the next scheduled run.

**From the CLI and MCP.** `ankra security report-schedule --cluster <cluster>` shows the stored schedule (or "not configured"), `ankra security report-schedule set --cluster <cluster> --frequency weekly|monthly --recipient ops@example.com --recipient sec@example.com [--disabled]` creates or replaces it after asking (`--yes` skips the prompt; `--disabled` stores it paused), and `ankra security report-schedule send --cluster <cluster>` queues one report now. From chat or the MCP server the same three are `get_cluster_security_report_schedule`, `set_cluster_security_report_schedule` and `send_cluster_security_report_now`; the two writes are confirmed before they run and need `clusters.write`. With an API token the routes are `GET`/`PUT /api/v1/org/clusters/imported/{cluster_id}/security/report-schedule` and `POST .../report-schedule/send-now`.

***

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| Report is empty or shows no data | Trivy Operator is not installed, or it has not produced scan reports yet | Install the [Trivy Operator add-on](/guides/cluster-security#prerequisites) and wait for the first scans to complete |
| No email arrives | No recipients saved, or the schedule was not saved | Re-open the integration, confirm the recipient list, and use send-now to test delivery |

***

## Related

> [card] [Cluster Security](/guides/cluster-security)
>
> The Security Center the report draws from.

> [card] [Alerts](/guides/alerts)
>
> Threshold-based notifications instead of a scheduled summary.


# Service Tokens
Source: https://docs.ankra.ai/guides/service-tokens

API credentials owned by the organisation rather than by a person, so an integration keeps working when the person who created it leaves.

A **service token** is an API credential that belongs to your organisation. It authenticates as a **service account** - a principal Ankra owns, carrying a role you chose - rather than as the person who created it.

That difference matters the day someone leaves. A personal API token is tied to its owner's membership, so removing them from the organisation stops every token they minted. If one of those was deploying your production cluster, the pipeline fails with a `401` and nothing in the deploy log explains why.

> [!NOTE]
>
> Personal API tokens still exist and are still the right choice for your own scripting and CLI use. Service tokens are for anything that runs without a person behind it: CI/CD, Terraform, agents, integrations.

***

## Personal token or service token?

| | Personal API token | Service token |
| - | - | - |
| Belongs to | The person who created it | The organisation |
| Where it lives | **Profile → API** | **Organisation → Service tokens** |
| Survives offboarding | No - it stops with the owner's membership | Yes |
| Authority | Everything its owner can do | One role you pick for it |
| Reaches other organisations | Yes, any the owner belongs to | No - pinned to one organisation |
| Reaches other [projects](/concepts/projects) | Yes, it follows the owner's current project and accepts `X-Ankra-Project-Id` | Not when pinned - the create dialog pins it to the project you choose |
| Who can see it | Only its owner | Any administrator |

***

## Create one

**1. Open Organisation → Service tokens**

The page requires the `members.manage` permission, so it is visible to owners and admins. That covers reading the list too - knowing which standing credentials exist, and what each one can do, is administrator-only.

**2. Name the service account**

Name it after the thing that will use it - `ci-deploy`, `terraform`, `backup-runner` - not after yourself. The name is how you will recognise it in the audit log a year from now.

**3. Pick its role**

The token carries this role and nothing else. Pick the narrowest one that does the job: a pipeline that deploys stacks does not need to manage members or read billing. See [Roles & Access](/guides/roles-and-access) for what each built-in role holds.

You can only grant a role whose permissions you already hold yourself. A token is usable the moment it is created, so this stops "can manage members" from quietly becoming "can escalate to owner".

**4. Pick its project**

The dialog offers the organisation's [projects](/concepts/projects) and defaults to the one you are working in. The token is **pinned** to the project you choose: it reads and writes there and nowhere else, and the list of service tokens says which project each one acts in. A token for a pipeline that deploys one team's clusters belongs in that team's project.

**5. Copy the token**

The secret is shown once. Put it straight into the consuming system's secret store - GitHub Actions secrets, GitLab CI variables, your Terraform backend - before leaving the page.

***

## Use it

A service token authenticates exactly like a personal one:

```bash theme={null}
export ANKRA_API_TOKEN="<your-service-token>"

curl -sS \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Accept: application/json" \
  https://platform.ankra.app/api/v1/clusters
```

Two behaviours differ from a personal token, both deliberate:

* **It cannot switch organisations.** The `X-Ankra-Organisation-Id` header (what `ankra --org` uses) is refused. A service account belongs to one organisation and there is nowhere else for it to go, so "this credential reaches this organisation and no other" is something you can rely on.
* **It cannot use the personal account surface.** `/org/account/*` - profile, MFA, personal tokens - is refused, so a service token can never mint further credentials for itself outside the page administrators watch.
* **A pinned token cannot leave its project.** A service token created with a project is pinned to it: `X-Ankra-Project-Id` naming another project and `project_id=all` on a cost route are refused, and a token whose project is deleted stops authenticating with `403 The project this token is pinned to no longer exists`, until you mint one in the project that replaced it. Service tokens created before [projects](/concepts/projects) were released carry no pin: they act in the project `X-Ankra-Project-Id` names and otherwise in the Default project, and they reach whatever their role reaches across the organisation. Rotate one into a pinned token when you want the project boundary.

***

## Rotate without downtime

Rotating means overlapping the old credential and the new one, never a gap.

**1. Mint a second token under the same account name**

Reusing the name adds a token to the **existing** service account rather than creating a new one. Both tokens work, both carry the same role, and the account keeps one continuous audit history across the rotation.

**2. Update the consuming system**

Replace the secret in your CI, Terraform, or integration, and let it run once to confirm the new token works.

**3. Revoke the old token**

Revoking stops that one credential immediately and leaves the account's other tokens untouched.

***

## Revoke and delete

**Revoke** stops a token working, immediately. Do this the moment you suspect a credential has leaked - it takes effect within the authentication cache window and does not wait for the token's expiry.

**Delete** removes an already-revoked token from the list. A token must be revoked before it can be deleted, so a credential can never disappear from the page while still working somewhere.

> [!WARNING]
>
> Deleting an account's **last** token also stands the service account down: it keeps its history, so past actions stay attributable, but it loses its role. A token minted under that name later starts from nothing and needs its role granted again deliberately.

***

## REST or MCP - pick one

Creating a token asks what it is **for**, and the two answers are mutually exclusive:

* **REST API** - the default. Works with the REST API, the `ankra` CLI, Terraform, and integrations.
* **MCP server only** - for agents such as Cursor or Claude Code. Carries `mcp:read`, and optionally `mcp:write` for the mutating tools (apply, scale, delete).

> [!WARNING]
>
> An MCP token reaches the hosted MCP server and **nothing else**. The REST API, the CLI, Terraform and every integration will refuse it — an agent's credential must not double as a general-purpose API key.
>
> The refusal is an HTTP 403, and clients commonly report that as a bad credential. So if an integration says your token was not accepted and the token is new and unexpired, check you did not create it as an MCP token: mint a REST one instead.

***

## What is recorded

Every mint, revoke, and delete is written to the [audit log](/guides/audit-log) with the administrator who did it, the service account, and the role involved. Actions the token itself takes are attributed to its service account, not to whoever created it - which is the point: a year later the log says `ci-deploy` restarted that workload, not a colleague who has since left.

***

## Related

> [card] [Roles & Access](/guides/roles-and-access)
>
> What each role can do, and how scopes narrow it.

> [card] [API reference](/api-reference/introduction)
>
> Authenticating and calling the REST API.

> [card] [Audit log](/guides/audit-log)
>
> Reviewing who did what, including token lifecycle events.

> [card] [CI/CD](/guides/cicd-pipeline)
>
> Wiring a pipeline that deploys through Ankra.


# Set Up a Managed Service
Source: https://docs.ankra.ai/guides/set-up-a-managed-service

Add a database, cache or queue from the application that will use it, or from the catalogue - connect its environments, place it on one of your clusters, size it and confirm the reviewed plan, then follow the installation.

> [!WARNING]
>
> **Closed beta.** Setting up a service is part of [Managed services](/concepts/managed-services), which is in closed beta and enabled per organisation on request. [Contact support](/platform/support) to have it turned on for your organisation.

Setting up a managed service takes four steps: **Connect**, **Place**, **Configure** and **Review**. The last step shows the plan Ankra prepared from your choices, and nothing is installed until you confirm it.

The quickest way in is from the application that will use the service: [Start from your application](#start-from-your-application) opens the same four steps with the application and its environment already chosen, and brings you back to the application when you are done. You can also start from the catalogue in **Managed services**.

***

## Prerequisites

Managed services are in the new Ankra portal. Choose **Managed services** in its sidebar, or open `/next/services` on your portal's address, for example `https://platform.ankra.app/next/services`. If the page says managed services are not offered to your organisation yet, [contact support](/platform/support).

Before you start, check the following:

* **The service cluster uses the native deployment engine.** Services generate their credentials in the cluster, which only the [native engine](/concepts/deployment-engines) supports. New clusters use it by default. A cluster that still deploys with ArgoCD can be [migrated](/concepts/deployment-engines#migrating-a-cluster-to-the-native-engine).
* **The service cluster has a default StorageClass.** Every service keeps its data on persistent volumes from the cluster's default StorageClass.
* **The application is deployed.** Setup offers only the environments an application is actually deployed to, each one a namespace on a cluster. All environments that one service connects must be in the same data boundary.
* **To be connected for you, the application runs on the service cluster.** Setup also accepts environments on other clusters, but Ankra delivers the service's connection only to environments on the cluster the service runs on. See [How your application receives the connection](/guides/connect-to-a-managed-service#how-your-application-receives-the-connection).
* **Your role allows it:**

| Permission | Needed to |
| - | - |
| `applications.deploy` and `profiles.read` | Set up a service at all |
| `clusters.operate` on each cluster involved | Connect an environment on that cluster, or place the service on it |
| `clusters.write` on a cluster | Declare or change its data policy |
| `applications.read` | See **My services** |

The built-in `owner`, `admin` and `operator` roles hold all of them. See [Roles and access](/guides/roles-and-access).

***

## Declare a data policy

A data policy says where a cluster keeps data. It is optional: a cluster without one takes services in the default location, region and data boundary `unspecified`. Declare one when services must keep data within a boundary; see [Data policies](/concepts/managed-services#data-policies) for what it then restricts. In the new portal, open the cluster's **Settings** and find **Where managed services may keep data**.

**1. Open the policy**

Choose **Declare data policy**, or **Change data policy** when the cluster already has one.

**2. Enter the region and data boundary**

Enter a **Region**, such as `eu-north`, and a **Data boundary**, such as `eu`. Both take lowercase letters, digits and single hyphens, start with a letter, and are at most 63 characters.

**3. Choose whether services must stay on this cluster**

Tick **Services bound to this cluster must run on this cluster only** if an application on this cluster may only use services running on the same cluster.

**4. Review and confirm**

Choose **Review policy**, read the summary, then **Confirm data policy**.

The policy is your organisation's declaration. Ankra records who made it and when, and does not verify the location. A service already reviewed against an earlier policy needs a new review.

***

## Start from your application

In the new Ankra portal, open the application. Its **Overview** has a **Services** card listing the managed services the application uses: each one's name, kind and package, which of the application's environments it serves, and how it is doing (deployment progress until it finishes, then its health and readiness). Services that need a look come first, and **My services** opens the full list for this application.

**1. Choose what to add**

Choose **Add a service** to pick from the catalogue, or one of the quick choices, such as **Add a database** or **Add a cache**. A quick choice goes straight to setting up the newest package of that kind. The card offers a quick choice only for a kind the catalogue has a package for that can be set up.

**2. Set it up for the application**

The setup page says which application and environment it is for, and **Connect** starts with that environment's namespaces chosen. Continue with the [four steps](#set-up-the-service) below. If the application is not deployed to that environment yet, Connect says so: deploy it there first.

**3. Deploy the application**

After you confirm, the service's page follows its deployment. Once the service is ready, Ankra copies its connection into the application's namespace by itself while none of the application's running pods references it, without a redeploy. Workloads deployed before the service was connected read the connection only after the application's next deploy adds the reference to it, so once the service is running, deploy the application to that environment: its containers then read the connection as environment variables such as `DATABASE_URL`. See [How your application receives the connection](/guides/connect-to-a-managed-service#how-your-application-receives-the-connection).

The application's other pages lead into the same flow, with the application and environment chosen:

* **Settings › Secrets** offers **Connect a managed service**.
* The deploy form offers **Add a managed service** under its secrets and dependencies. It opens in a new tab, so the deployment you are preparing stays open.

Every one of these opens the same setup page, with the application and environment in its address (`?application=<application-id>&environment=<environment-id>`). The card and the links appear only where managed services are offered to your organisation and your role may set one up. Anyone else is told to ask someone who can deploy applications.

***

## Set up the service

**1. Open the package**

From an application, **Add a service** or a quick choice brings you here: see [Start from your application](#start-from-your-application). From **Managed services**, open the **Catalogue** tab, choose the service and choose **Set up**. Catalogue cards also carry a **Set up** button.

**2. Connect: choose the application environments**

Find an application and tick the environments that will use the service. Each environment is listed as a namespace on a cluster, together with that cluster's data policy when it declares one. You can add environments from several applications, up to 100. They all use this one service and share its credentials, so to keep data apart, for example production from staging, set up a separate service for each. When you came from an application, its environment is already ticked.

**Continue** stays disabled while the chosen environments keep data in different boundaries, including a cluster that declares a policy beside one that does not, or while your role cannot operate one of their clusters. An application that is not deployed yet offers no environments: deploy it first.

**3. Place: choose who runs it and where**

**Your infrastructure** is how every service runs today: Ankra installs it on one of your clusters, and your team operates it.

Choose the **Service cluster** from the clusters your environments run on. When the cluster declares a data policy, the page shows its region and data boundary. An environment that cannot use a service on the chosen cluster is listed with the reason before you continue. The usual reasons are a different data boundary, or a cluster that keeps its services local.

> [!TIP]
>
> A service's addresses resolve only inside its own cluster, and Ankra connects only the environments on that cluster. Place it on the cluster your environments run on. An environment on another cluster needs a network path you provide and the values set by hand: see [Connect from another cluster](/guides/connect-to-a-managed-service#connect-from-another-cluster).

**4. Configure: name it and size it**

**Service name** is suggested from the application and the package, for example `storefront-postgresql`. It must follow the [name rules](#service-name-rules).

Each setting shows its range and default. A package with more than three settings keeps the rest under **More settings**. [Managed Service Settings](/reference/managed-services) explains each one.

Choose **Review setup**. This records the chosen environments as consumers of managed services and asks Ankra to prepare a plan. It installs nothing.

**5. Review: confirm the plan**

The plan lists the service name, the package and version, who operates it, the service cluster with its region and data boundary, every setting, and the connected environments.

Choose **Confirm setup** before the review window ends, **10 minutes** after the plan was prepared. The page shows when that is. **Change choices** takes you back. If the window passes, **Review again** prepares a fresh plan with the same choices.

A review waiting for confirmation is also listed under **My reviews**, where you can confirm it within its window. Each person can hold at most 20 reviews waiting for confirmation, and each organisation 100.

### Service name rules

The name becomes the service's namespace and its stack name on the service cluster. It must:

* be a DNS label: lowercase letters, digits and single hyphens, starting with a letter;
* be at most **36 characters**;
* not be `default`, and not start with `kube-`, `ankra`, `cnpg-system`, `cert-manager`, `ingress-nginx`, `argocd` or `flux-system`;
* not already be used on that cluster, by a stack or by another service. A name stays taken from the moment its setup is confirmed, even if the installation then fails, until that service is [deleted](/guides/delete-a-managed-service).

The form checks the characters as you type. The platform checks the rest when it prepares and confirms the review. A name another service on the cluster holds is refused at both points: the page says `Another service on the service cluster already uses this name.` and flags the name until you change it. A stack of that name that no service holds is found only when Ankra installs the service, after you confirm, and the installation then needs attention.

### What confirming does

Confirming asks Ankra to install the service. It does not verify that the service is ready or that your applications can reach it. After you confirm:

1. The service appears in **My services** and on the **Services** card of each application it serves, and its page opens with **Setup confirmed. Deployment submitted; readiness is not yet verified.**
2. For PostgreSQL, Ankra makes sure the cluster runs the CloudNativePG operator. It is installed once per cluster, as its own stack `cloudnative-pg` in the `cnpg-system` namespace. A cluster that already runs CloudNativePG, installed by Ankra or any other way, keeps its operator. The operator is shared by every PostgreSQL service on the cluster, so leave it in place while any of them run.
3. Ankra deploys the service as a stack named after the service, into a namespace of the same name.
4. Each environment on the service cluster receives the service's connection once the service is ready. Ankra writes it into the application's namespace without a redeploy while none of the application's running pods references it, and leaves it to the application's next deploy otherwise. Workloads deployed before the service was connected read it after their next deploy. When Ankra leaves an environment's connection to a deploy, the service's page offers to deploy it; see [How your application receives the connection](/guides/connect-to-a-managed-service#how-your-application-receives-the-connection) for what each environment's state means.

The first PostgreSQL service on a cluster can take a few minutes longer while its operator comes up.

***

## Follow the installation

Open **My services** and choose the service. **Deployment progress** shows where it stands, and **View cluster operations** opens the cluster's operations with the detail. Once Ankra has observed the deployed service, it also carries a **Health** badge in **My services**, and its page's **Service health** section shows what was observed: see [Health](/concepts/managed-services#health).

| Status | Meaning |
| - | - |
| **Installation requested** | Your request is saved. Deployment has not been confirmed yet. |
| **Deployment in progress** | The deployment operation has not finished. |
| **Verification needed** | The deployment finished. Ankra has not yet verified that a client can connect, and has not yet observed the service serving. |
| **Running** | The deployment finished and Ankra observes the service serving in its cluster. Its readiness check has not passed yet, or has not run. |
| **Deployed** | The deployment finished and the service passed its last readiness check: a client could connect. |
| **Installation needs attention** | The installation request did not complete. Check the cluster's operations before trying again. |
| **Deployment needs attention** | The deployment did not complete successfully. Check the cluster's operations for the next step. |
| **Progress unavailable** | Ankra does not have enough current operation records to report progress. Your request is still saved. |
| **Retired** | The service was [deleted](/guides/delete-a-managed-service) and its name released. The record is kept as history. |
| **Deleted, data may remain** | The service was deleted and its name released, but Ankra cannot show that its data is gone. Its page lists the volumes that may still hold it: see [When data may remain](/guides/delete-a-managed-service#when-data-may-remain). |

While a deletion runs, **My services** shows the service as **Deleting** instead.

Next to the progress, the page reads **Readiness unverified**: a finished deployment does not show that your application can connect. Check that the service answers before you rely on it: see [Check that the service answers](/guides/connect-to-a-managed-service#check-that-the-service-answers).

### See the services an application uses

The application's **Services** card lists them, and **My services** next to it opens the full list for that application. From the command line, give the application's name or id:

```bash theme={null}
ankra services list --application <application>
```

A service is listed when its reviewed plan names one of the application's namespaces as a consumer. The **Used by** column says which of the application's environments it serves, or the namespace where the application is not deployed yet. Retired services are left out unless you add `--include-released`.

***

## Troubleshooting

| What you see | Cause | Remedy |
| - | - | - |
| `<application> is not deployed to <environment> yet.` | You came from an application whose environment has no deployment yet | Deploy the application to that environment, then add the service again |
| `The environment this link names is not one of <application>'s environments now.` | The link names an environment the application no longer has | Choose an environment in **Connect** |
| `These environments keep data in different boundaries` | The chosen environments sit in more than one data boundary, or one cluster declares a data policy and another does not | Set up one service per data boundary, or declare the same boundary on each cluster |
| `Services it uses must run on <cluster> itself.` | That environment's cluster keeps its services local | Place the service on that cluster, or set up a separate service for it |
| `Your role cannot operate ...` | You lack `clusters.operate` on that cluster | Remove the environment, or ask an administrator for access |
| `The platform refused these choices.` | The service name breaks a [name rule](#service-name-rules), usually by being longer than 36 characters, or a setting is out of range | Shorten or change the name, check the settings, and review again |
| `Delivering credential grants into a deployed stack is not available yet; this package's secret inputs cannot be installed` | The package version declares secret inputs for that way of running it. Ankra refuses it when it checks the choices and when it prepares the review, before any name is reserved | Choose a package version, or a mode, that declares no secret inputs |
| `The setup could not be completed.` when preparing the review | Often a service cluster that deploys new stacks through ArgoCD | [Migrate the cluster to the native engine](/concepts/deployment-engines#migrating-a-cluster-to-the-native-engine), or choose a native-engine cluster |
| `Another service on the service cluster already uses this name.` | A service that has not been deleted holds the name on the service cluster | Choose another name in **Configure** (when confirming, **Choose another name** takes you there) and review again, or [delete the other service](/guides/delete-a-managed-service) first |
| `This setup changed after you reviewed it.` | Something in the plan changed after it was prepared | **Review again** to see the current plan |
| `This review expired before it was confirmed.` | The 10-minute window passed | **Review again** |
| `You have too many setup reviews waiting.` | 20 reviews of yours, or 100 in the organisation, are waiting | Confirm one in **My reviews**, or let them expire after 10 minutes |
| `An application is no longer deployed in one of the chosen environments.` | The application was removed from that namespace | Remove the environment, or deploy the application again |
| **Installation needs attention**, with `Ankra cannot currently tell whether the selected cluster runs this service's shared operator` | Ankra could not see whether the cluster runs CloudNativePG, so it did not risk installing a second operator | Make sure the cluster's agent is online and reporting. Then set the service up again under a new name, or [delete the service](/guides/delete-a-managed-service) to release its name and set it up again under the same one |

***

## Next steps

> [card] [Connect to a managed service](/guides/connect-to-a-managed-service)
>
> How your application receives the connection, and the variables it reads.

> [card] [Delete a managed service](/guides/delete-a-managed-service)
>
> Remove a service and its data through a reviewed plan.

> [card] [Managed service settings](/reference/managed-services)
>
> Every setting of each service, with its range and default.

> [card] [Managed services](/concepts/managed-services)
>
> What the services are, how they run, their health and readiness, and their current limits.

> [card] [Deployment engines](/concepts/deployment-engines)
>
> The native engine, and moving a cluster to it from ArgoCD.


# Single Sign-On
Source: https://docs.ankra.ai/guides/single-sign-on

Connect your organisation's own OpenID Connect identity provider - Microsoft Entra ID, Okta or any other - so it decides who is a member, which role they hold, and when their access ends.

Single sign-on lets your organisation's own identity provider decide who is a member of it in Ankra. People the provider admits become members when they sign in. People it stops admitting lose access on their own, without anyone removing them in Ankra.

The same organisation identity can protect [proxied `ankra.cc` hostnames and custom domains](/guides/private-proxied-domains) through the Ankra Cloud access gateway.

You set it up yourself under **Organisation** → **Settings** → **Single sign-on**. Ankra does not need to enable anything for you first.

The whole setup in two minutes, from connecting the provider to what happens when someone leaves:

[Ankra single sign-on: your identity provider decides who is in](https://www.youtube-nocookie.com/embed/XQUPrsFSaQg?rel=0)

> [card] [Who may sign in](#who-becomes-a-member)
>
> Whoever is assigned to the Ankra application in your provider.

> [card] [Which role they hold](#set-roles-from-groups)
>
> The provider's groups, mapped to Ankra roles. Optional.

> [card] [When access ends](#how-access-ends)
>
> At the end of the re-verification window: 24 hours by default.

```mermaid theme={null}
flowchart LR
    Member([Member]) -->|"sign-in link"| Provider[Your identity<br/>provider]
    Provider -->|"signs them in"| Ankra[Ankra checks the<br/>verified domain]
    Ankra --> Active([Active member])
```

A sign-in through your provider

***

## Before you start

| You need | Why |
| - | - |
| **The `organisation.manage` permission** | Held by owners and admins. See [Roles & Access](/guides/roles-and-access). |
| **An OpenID Connect identity provider** | Microsoft Entra ID (Microsoft 365), Okta and Keycloak all speak it. SAML is not supported. |
| **Access to the DNS of your email domain** | You publish one TXT record to prove the domain is yours. |
| **The Enterprise plan** | Single sign-on is part of [Enterprise](/platform/billing#plans). To use it on another plan, [contact support](/platform/support). It is not available on the single-user Homebuilder plan, because single sign-on adds members. |

***

## Set it up

![The Single sign-on page under Organisation settings: an Identity provider card showing Enabled, the issuer, client ID and client secret fields, the redirect URI to register with the provider, and Microsoft Entra ID hints](https://mintcdn.com/ankra/O_3kIfS4u-iVfb0E/images/single-sign-on-settings.png?fit=max\&auto=format\&n=O_3kIfS4u-iVfb0E\&q=85\&s=64cf33aa71aae162b13df8470b37f044)

The Single sign-on settings page with a provider connected and enabled (example data)

**1. Register Ankra with your identity provider**

Open **Organisation** → **Settings** → **Single sign-on** and copy the value under **Redirect URI to register with your provider**. Then create an application for Ankra in your provider.

> [tab] Microsoft Entra ID
>
> 1. In the Microsoft Entra admin centre, open **App registrations** → **New registration**.
> 2. Under **Supported account types**, choose **Accounts in this organizational directory only**.
> 3. Under **Redirect URI**, choose the **Web** platform and paste the redirect URI from Ankra.
> 4. On the registration's **Overview**, copy the **Application (client) ID** and the **Directory (tenant) ID**.
> 5. Open **Certificates & secrets** → **New client secret** and copy the secret's **Value**.
> 6. Open **Enterprise applications**, select the application, and under **Properties** set **Assignment required?** to **Yes**. Then assign the people or groups who should have access under **Users and groups**.
>
> Your issuer is `https://login.microsoftonline.com/<tenant-id>/v2.0`.
>
> > [!WARNING]
> >
> > Without **Assignment required**, everyone in your tenant with an address on a verified domain can sign in, and joins your Ankra organisation while just-in-time membership is on. Removing someone from the assignment is also how their access ends, so it is the control this whole feature rests on.
>
> Ankra reads the `email` claim, which Entra ID fills from the user's email address. A user with no email address set in Entra ID cannot sign in.

> [tab] Okta
>
> 1. In the Okta Admin Console, open **Applications** → **Create App Integration**.
> 2. Choose **OIDC - OpenID Connect** and **Web Application**.
> 3. Under **Sign-in redirect URIs**, paste the redirect URI from Ankra. Keep the **Authorization Code** grant.
> 4. Under **Assignments**, limit access to the people or groups who should have access.
> 5. Copy the **Client ID** and **Client secret**.
>
> Your issuer is your Okta organisation URL, `https://<your-okta-domain>`. If you sign people in through a custom authorization server, use its issuer instead, for example `https://<your-okta-domain>/oauth2/default`.

> [tab] Another provider
>
> Any OpenID Connect provider works if it meets these requirements:
>
> * It publishes a discovery document at `<issuer>/.well-known/openid-configuration`, reachable from the internet over HTTPS.
> * The application is a confidential client: authorization code flow with a client secret.
> * It releases the `email` claim when Ankra requests the `openid`, `profile` and `email` scopes.
> * The redirect URI from Ankra is registered on the application.
>
> Restrict who may use the application in the provider itself. Ankra admits whoever the provider signs in with an address on one of your verified domains.

**2. Connect the provider in Ankra**

Back on **Single sign-on**, under **Identity provider**, fill in the three fields and click **Connect provider**.

| Field | What to enter |
| - | - |
| **Issuer** | The issuer URL itself, not the discovery document URL. For Entra ID it must be your own tenant's issuer: the shared `common`, `organizations` and `consumers` authorities admit accounts from any tenant and are refused. |
| **Client ID** | The application's client ID. |
| **Client secret** | Passed to the identity broker that performs the sign-in. It is not stored in Ankra or shown again. |

The provider now shows as **Connected, not enabled**. Nobody can sign in through it yet.

> [!TIP]
>
> To rotate the secret later, enter the new one and click **Save provider**. Changing the issuer or the client ID needs the secret again.

**3. Verify your email domain**

Under **Email domains**, enter the domain your members' addresses use and click **Add domain**. Ankra shows a record to publish at your DNS provider:

| Type | Record name | Record value |
| - | - | - |
| `TXT` | `_ankra-challenge.<your-domain>` | `ankra-domain-verification=<token>` |

Publish it, then click **Verify**. DNS changes can take a few minutes to appear, and you can click **Verify** again until the domain shows **Verified**. A **Sign-in link** then appears under **Email domains**.

Ankra accepts a sign-in through your provider only when the address is on a domain you have verified. That is what stops a provider from signing people in under addresses its owner does not control.

* A verified domain covers exactly that domain. `example.com` does not cover `eu.example.com`; add and verify each one.
* Public email providers such as `gmail.com` and `outlook.com` cannot be claimed.
* A domain can be verified by one organisation only.

**4. Enable single sign-on**

Under **Access policy**, turn on **Enable single sign-on**. It can only be turned on once at least one domain is verified.

**5. Sign in through the provider once**

Open the sign-in link in a private browser window and sign in as someone assigned to the application. You should land in your organisation, and the **Identity provider** card should show the time under **Last sign-in through the provider**.

Do this before you tell anyone else. It proves the provider works, and Ankra will not let you require single sign-on until one sign-in has succeeded.

> [!TIP]
>
> Single sign-on is now on and optional: members can use it, and everyone can still sign in the way they did before. To make the provider the only way in, see [Require single sign-on](#require-single-sign-on).

***

## How members sign in

There are two ways to reach your provider:

```text Sign-in link theme={null}
https://platform.ankra.app/auth/sso/login?domain=<your-domain>
```

```text Single sign-on page theme={null}
https://platform.ankra.app/auth/sso
```

> [card] The sign-in link
>
> Shown under **Email domains**. It goes straight to your provider. Share it, or set it as the application's home page URL in your provider so that the Ankra tile in your members' application portal opens it.

> [card] The single sign-on page
>
> A member enters their work email address and Ankra sends them to the provider that serves its domain.

Every sign-in through the provider has to be a fresh one: Ankra accepts it only when the provider authenticated the person within the last ten minutes.

Ankra's second factor is separate from your provider's. A member who has one enrolled is still asked for it after the provider signs them in, and an organisation that [requires MFA](/platform/account-security) still requires each member to enrol.

***

## Who becomes a member

**Just-in-time membership** is on by default: anyone the provider admits, with an address on a verified domain, becomes a member the first time they sign in. Turn it off under **Access policy** and only people you have invited can join through the provider.

| Who signs in through the provider | Just-in-time on (default) | Just-in-time off |
| - | - | - |
| Someone new, with no invitation | Becomes a member with the **Default role**, which is **Member** unless you change it | Refused, and told to ask an administrator for an invite |
| Someone you invited | The invitation is accepted, with the role it carries | The invitation is accepted, with the role it carries |
| An existing member | Stays a member, and is governed by single sign-on from now on | Stays a member, and is governed by single sign-on from now on |

Someone who already has an Ankra account under the same address keeps it. The provider is connected to their existing account, so their API tokens, second factors and memberships of other organisations are unchanged. This needs the existing account's address to have been verified; an account that never verified its address is refused, and the message says so.

> [!NOTE]
>
> While just-in-time membership is on, removing a governed member on the members page lasts only until their next sign-in: the provider still admits them, so they join again. To remove someone, remove them from the application in your provider.

***

## Set roles from groups

By default the provider decides who is a member and you decide roles in Ankra. Add mappings under **Group to role** and the provider decides roles too.

**1. Send the member's groups to Ankra**

Your provider has to put the member's groups in a `groups` claim on the ID token. Ankra requests the `openid`, `profile` and `email` scopes only, so the claim has to be released without an extra scope.

> [tab] Microsoft Entra ID
>
> On the app registration, open **Token configuration** → **Add groups claim** and include it in the ID token. Choose **Groups assigned to the application** so the claim stays small.
>
> The claim carries group object IDs unless you configure the application to emit names.

> [tab] Okta
>
> On the application's **Sign On** tab, set a groups claim filter in the **OpenID Connect ID Token** section.

**2. Map groups to roles**

Click **Add mapping**, enter a group exactly as the provider sends it - a name or an object ID - and pick **Member**, **Admin** or **Read-only**. Then click **Save mappings**.

**3. Check it**

Sign in as a member of a mapped group and look for the `sso_member_role_synced` entry in the [audit log](/guides/audit-log).

While at least one mapping exists, every sign-in through the provider sets the member's role from the groups it sent:

| Situation | Role the member gets |
| - | - |
| In one mapped group | That group's role |
| In several mapped groups | The highest: **Admin**, then **Member**, then **Read-only** |
| In no mapped group | The **Default role** |
| You changed the role by hand in Ankra | Your change lasts until that member's next sign-in |
| An **owner** or a **break-glass member** | Never moved by groups. Ownership is granted by hand, and break-glass members are your way back in if the provider is wrong. |

Mappings set the organisation-wide built-in role. [Custom roles](/guides/roles-and-access) and roles assigned on a single cluster or cluster group are left as they are. Remove every mapping and roles are yours to set in Ankra again.

***

## How access ends

Your provider does not tell Ankra when you remove someone, so access through single sign-on is a lease that each sign-in renews.

```mermaid theme={null}
flowchart TD
    SignIn([Signs in through your provider]) --> Active[Active, and the window starts again]
    Active -->|"the window ends with no new sign-in"| Suspended[Suspended]
    Suspended -->|"signs in through the provider again"| Active
    Suspended -->|"removed in the provider, so the sign-in fails"| Ended([Access stays ended])
```

The life of a membership that single sign-on governs

A member is **governed** by single sign-on once they have signed in through the provider. Each of those sign-ins records that the provider vouched for them. When the latest one is older than the **Re-verification window**, Ankra suspends the membership.

A suspended member loses everything at once: portal sessions, personal API tokens, and Kubernetes access granted through Ankra. They show as **Suspended** on the members page. Ankra checks every five minutes, and a suspension takes effect everywhere within about six minutes of the window ending.

Signing in through the provider again restores the membership, with the role it had. Someone you removed from the application in your provider cannot complete that sign-in, so their access ends at the window.

The window therefore sets two things:

| What it sets | How |
| - | - |
| **How long a removed person keeps access** | At most one window after their last sign-in through the provider |
| **How often everyone else signs in through the provider** | At least once per window, or they are suspended until they do |

The default is 24 hours, and you can set anything from 1 to 720 hours under **Access policy**. A shorter window revokes faster and asks members to sign in more often.

Two kinds of member are never suspended: break-glass members, and everyone while single sign-on is switched off for the organisation.

> [!TIP]
>
> A suspended member's personal API tokens stop working with them. Run pipelines and integrations on [service tokens](/guides/service-tokens), which belong to the organisation and are not governed by single sign-on.

***

## Require single sign-on

Under **Access policy**, set **Require single sign-on** to **Required**. Ankra allows this once single sign-on is enabled and someone has signed in through the provider.

| Who | What changes when it is required |
| - | - |
| A member with an address on a verified domain | Signing in any other way sends them to your provider |
| A new sign-up with an address on a verified domain | Sent to your provider |
| Every active member on a verified domain, except break-glass members | Governed immediately, with one full window to sign in through the provider |
| A member whose address is on another domain | Nothing. They keep signing in the way they do today |
| An account that shares your domain but belongs only to other organisations | Nothing |

### Break-glass members

Break-glass members keep their other sign-in methods when single sign-on is required, and are never suspended. They are how you get back in when the provider is misconfigured or down.

* The list can never be empty, and at least one break-glass member must be able to manage the organisation.
* Whoever sets single sign-on to **Required** is added to the list.
* Choose them under **Break-glass members** and click **Save break-glass members**.

> [!WARNING]
>
> Keep at least one break-glass member whose own sign-in you have tested. If the provider fails and no break-glass member can sign in, nobody in your organisation can reach the settings to turn single sign-on off, and you will need [Ankra support](/platform/support) to recover access.

***

## Change or remove it

| Action | What happens to members |
| - | - |
| Turn off **Enable single sign-on** | Nobody can sign in through the provider, nobody is suspended, and **Required** returns to **Optional**. Members with a password or social sign-in use that; members who only ever signed in through the provider cannot sign in until it is enabled again. |
| Remove a verified domain | Active members on that domain return to ordinary membership. Suspended members stay suspended. The last verified domain cannot be removed while single sign-on is enabled. |
| **Remove single sign-on** | Active members become ordinary members. Suspended members stay suspended. |

> [!WARNING]
>
> Removing single sign-on cannot be undone for accounts that existed only through your provider. They lose their sign-in, and their personal API tokens and Kubernetes access are revoked. Members who also have a password or social sign-in keep it.

A member who is still suspended after single sign-on is turned off or removed can be removed and invited again from the members page.

***

## Audit trail

Every change and every membership decision is written to the organisation's [audit log](/guides/audit-log):

| Action | Recorded when |
| - | - |
| `sso_connection_created`, `sso_connection_updated`, `sso_connection_deleted` | The provider is connected, re-keyed or removed |
| `sso_policy_updated` | Enabling, requiring, the default role, the window or the break-glass list changes |
| `sso_domain_added`, `sso_domain_verified`, `sso_domain_removed` | An email domain is claimed, verified or removed |
| `sso_group_mappings_updated` | The group mappings are saved |
| `sso_member_provisioned` | The provider admits a new member |
| `accept_invite` | An invited person joins by signing in through the provider |
| `sso_member_role_synced` | A sign-in changes a member's role from their groups |
| `sso_member_suspended` | The window ends without a sign-in through the provider |
| `sso_member_restored` | A suspended member signs in through the provider again |

For an access review, filter the [audit export](/security/audit-export) to these actions: together they are the joiner, mover and leaver record for members the provider governs.

***

## Limits

| Limit | Value |
| - | - |
| **Protocol** | OpenID Connect. SAML is not supported. |
| **Providers** | One per organisation |
| **Email domains** | Up to 20 |
| **Group mappings** | Up to 50, to **Member**, **Admin** and **Read-only**. **Owner** cannot be mapped. |
| **Break-glass members** | 1 to 20 |
| **Re-verification window** | 1 to 720 hours, 24 by default |
| **Deprovisioning** | Removal in the provider is not pushed to Ankra (there is no SCIM provisioning). Access ends at the re-verification window. |
| **Management** | In the portal. There is no CLI command or API token endpoint for these settings. |

***

## Troubleshooting

Entries are titled with the message Ankra shows, to an administrator on the settings page or to a member at sign-in.

### Connecting a provider

> [accordion] Single sign-on could not be prepared on this installation right now
>
> Ankra could not get its sign-in service ready for single sign-on. Try again in a few minutes, and [contact support](/platform/support) if it keeps failing.

> [accordion] The identity provider configuration was not accepted
>
> The issuer or the client was refused. Check that the issuer is the issuer URL itself and that its discovery document is reachable from the internet.

> [accordion] Single sign-on adds members to the organisation, and the Homebuilder plan is limited to a single user
>
> The organisation's plan allows one member. Upgrade the plan under [Billing](/platform/billing), then connect the provider.

### Verifying a domain

> [accordion] No TXT record with the expected value was found
>
> The record is not visible in DNS yet, or its name or value differs from what the page shows. Check it and click **Verify** again.

> [accordion] The domain is already verified by another organisation
>
> Another Ankra organisation has verified this domain, and a domain belongs to one organisation only. One of your own organisations may hold it.

### Signing in

> [accordion] Not a domain your organisation has verified with Ankra
>
> The provider signed the person in with an address outside your verified domains. Verify that domain, or correct the email address the provider sends.

> [accordion] Your identity provider did not share an email address with Ankra
>
> The application does not release the `email` claim, or the user has no email address in the provider.

> [accordion] You have not been invited to it yet
>
> Just-in-time membership is off and the person has no invitation. Invite them, or turn just-in-time membership on.

> [accordion] An Ankra account already exists for this email address, but the address was never verified
>
> Sign in to that account the way it was created and verify the address, then sign in through the provider again.

> [accordion] This organisation is on the Homebuilder plan, which is limited to a single user
>
> The provider admitted the person, but the organisation's plan allows one member. The organisation needs to upgrade before anyone else can join.

> [accordion] Single sign-on is not enabled for this organisation
>
> The provider is connected but **Enable single sign-on** is off.

> [accordion] Single sign-on is not set up for the domain
>
> Shown on the single sign-on page when no enabled provider serves the address's domain. Check the address, or that the domain is verified and single sign-on is enabled.

> [accordion] Ankra could not confirm a fresh sign-in with your identity provider
>
> The provider did not authenticate the person just now. Close the window and start again from the sign-in link.

> [accordion] Your organisation requires single sign-on, but the sign-in did not complete through your identity provider
>
> Start again from the sign-in link. If it repeats, [contact support](/platform/support).

> [accordion] A member shows as Suspended
>
> The provider has not vouched for them within the window. They are restored by signing in through the provider.

### Requiring single sign-on

> [accordion] Sign in through single sign-on successfully once before requiring it
>
> Nobody has signed in through the provider yet. Use the sign-in link once, then set **Required**.

***

## Related

> [card] [Identity & Access Controls](/security/identity-and-access)
>
> The compliance view of sign-in, MFA, roles and tokens.

> [card] [Roles & Access](/guides/roles-and-access)
>
> What each role grants, and scoped and custom roles.

> [card] [Service Tokens](/guides/service-tokens)
>
> Credentials for automation that do not depend on a person.

> [card] [Audit Log](/guides/audit-log)
>
> Review who was admitted, suspended and restored.


# SOPS Encryption
Source: https://docs.ankra.ai/guides/sops

Encrypt sensitive values in your Stacks with SOPS for secure GitOps workflows

> [!NOTE]
>
> SOPS (Secrets OPerationS) encryption allows you to securely store sensitive values like passwords, API keys, and credentials in your GitOps repository. Encrypted values are automatically decrypted during deployment.

## What is SOPS?

[SOPS](https://github.com/getsops/sops) is an editor for encrypted files that supports YAML, JSON, ENV, INI and BINARY formats. Ankra uses SOPS with [AGE](https://github.com/FiloSottile/age) encryption to protect sensitive values in your Stack configurations.

### How It Works

```mermaid theme={null}
flowchart LR
    Editor[Stack Builder or CLI] -->|Value as entered| Ankra[Ankra control plane]
    Ankra -->|Sealed with the AGE public key on every push| Git[Git Repo]
    Git -->|Decrypted by the agent in your cluster| Cluster[Cluster]
```

1. **In the Stack Builder**: You enter the value in plaintext and list its key under **Encrypted Keys (SOPS)**
2. **In Ankra**: The control plane stores the value as you entered it, together with the list of keys to seal. Listing a key does not encrypt the value inside Ankra
3. **On every push to Git**: Ankra seals the listed keys with your organisation's AGE public key, so your repository only ever receives `ENC[AES256_GCM,...]` for them
4. **On Deploy**: The Ankra agent decrypts inside your cluster - directly with `sops` on the native engine, or through ArgoCD's helm-secrets plugin on the ArgoCD engine (see [Deployment Engines](/concepts/deployment-engines))

> [!NOTE]
>
> Because sealing happens at the push, the Stack Builder shows the value you typed, not ciphertext, including after you save and reopen it. That is expected. What protects the value is that it is never written to Git unsealed: a push that cannot seal a listed key is refused instead of committed. To confirm a value is sealed, look at the file in your Git repository.

***

## Getting Started

Setting up SOPS encryption is a single step. Once initialized, encryption is enabled by default and cluster decryption is handled automatically.

**1. Navigate to Encryption Settings**

Go to **Organisation Settings** → **Encryption**.

**2. Initialize Encryption**

Click **Initialize Encryption**. This generates an AGE key pair:

* **Public key**: Used to encrypt values (visible to you)
* **Private key**: Used to decrypt values (stored securely in Ankra's secret store)

That's it. After initialization:

* **Encryption is enabled** by default - fields you mark as encrypted will be protected immediately.
* **Cluster decryption is automatic** - on the native engine the agent requests the key from Ankra when it deploys a sealed value, and on the ArgoCD engine Ankra installs the key into the cluster for helm-secrets. There is nothing to configure per-cluster.

The AGE public key is displayed on the Encryption settings page. You can copy it for use with external SOPS tools if needed.

The public key looks like: `age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p`

***

## Encrypting Values in Stacks

### Using the Stack Builder

When editing a manifest or add-on values in the Stack Builder:

1. Look for the **Encrypted Keys (SOPS)** section
2. Add key names that should be encrypted (e.g., `password`, `apiKey`, `token`)
3. Enter the plaintext value as normal
4. Save. Ankra seals those specific keys every time it writes the file to your Git repository

> [!TIP]
>
> Only the specified keys are encrypted. Other values remain in plaintext for easy review and debugging.

### Common Keys to Encrypt

| Key Name | Use Case |
| - | - |
| `password` | Database passwords, admin credentials |
| `apiKey` | Third-party API keys |
| `token` | Authentication tokens, tunnel tokens |
| `secretKey` | Encryption keys, signing keys |
| `connectionString` | Database connection strings with credentials |
| `privateKey` | SSH keys, TLS private keys |

### Example: Encrypting a Database Password

**Before encryption** (what you see in the editor):

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
  namespace: database
type: Opaque
stringData:
  username: app_user
  password: super-secret-password
```

**After encryption** (what's stored in Git):

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: postgres-credentials
  namespace: database
type: Opaque
stringData:
  username: app_user
  password: ENC[AES256_GCM,data:vxvYs7vKw+bPqNWO3tE=,iv:...,tag:...,type:str]
sops:
  age:
    - recipient: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBxVEdI...
        -----END AGE ENCRYPTED FILE-----
  encrypted_regex: ^(password)$
  version: 3.9.4
```

### Example: Encrypting a Registry Pull Secret (`.dockerconfigjson`)

A `kubernetes.io/dockerconfigjson` Secret stores its payload under a key whose
name literally begins with a dot: `.dockerconfigjson`. Add that key, leading dot
included, to the **Encrypted Keys (SOPS)** list (or pass `--key .dockerconfigjson`
to the CLI). The leading dot marks it as a literal key name rather than a nested
dotted path, so it is matched and encrypted as-is.

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: registry-auth
  namespace: platform
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: ENC[AES256_GCM,data:vxvYs7vKw+bPqNWO3tE=,iv:...,tag:...,type:str]
sops:
  age:
    - recipient: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBxVEdI...
        -----END AGE ENCRYPTED FILE-----
  encrypted_regex: ^(\.dockerconfigjson)$
  version: 3.9.4
```

***

## Encrypting Helm Values

For add-ons (Helm charts), you can encrypt specific values:

1. Open the add-on in the Stack Builder
2. In the values editor, find the **Encrypted Keys (SOPS)** section
3. Add paths to sensitive values

### Helm Values Path Examples

| Path | Description |
| - | - |
| `adminPassword` | The key `adminPassword` |
| `auth.password` | Dot notation locates the key `password` under `auth` |
| `credentials.apiKey` | Dot notation locates the key `apiKey` under `credentials` |
| `glob:*Password` | Every key whose name ends in `Password`, at any depth (see [pattern entries](#encrypting-keys-by-pattern)) |

**Example**: Encrypting Grafana admin password

```yaml theme={null}
# Values for grafana chart
adminUser: admin
adminPassword: my-grafana-password  # ← This gets encrypted
persistence:
  enabled: true
```

Add `adminPassword` to the encrypted keys list.

### What an Entry Actually Matches

Dot notation tells Ankra **which key you mean**; it does not confine the
encryption to that one place in the file. Ankra compiles the entries into a SOPS
`encrypted_regex` built from the key **names**, and SOPS applies that regex to
every key at every depth of the document. A dotted entry contributes its **last
segment** as one of those names. So an entry `auth.password` names the key
`password`, and **every** key called `password` in that file is sealed -
`auth.password`, `backups.password`, and any other.

That is usually what you want, and it is why a key added under a new section
next month is sealed without changing the declaration. It becomes a problem when
the key name is not unique to your secret.

> [!WARNING]
>
> **Do not mark a key whose name is a structural YAML or Kubernetes field**, such
> as `key`, `name`, `path`, `value`, `type`, `host`, `port` or `operator`. The
> entry seals every field of that name in the file, including the ones the chart
> needs to read in plaintext.
>
> **This applies to dotted entries too, by their last segment.** `tls.key`,
> `metadata.name` and `spec.host` end in a structural field name, so they seal
> every `key`, `name` and `host` in the document exactly as the bare entry would.
> Writing the parent section does not scope the seal to it.
>
> Marking a key called `key` in a kube-prometheus-stack values file produces
> `encrypted_regex: ^(key)$`, which seals the node-affinity term as well:
>
> ```yaml theme={null}
> prometheusSpec:
>   affinity:
>     nodeAffinity:
>       requiredDuringSchedulingIgnoredDuringExecution:
>         nodeSelectorTerms:
>           - matchExpressions:
>               - key: ENC[AES256_GCM,data:...]   # ← sealed by ^(key)$, not a secret
>                 operator: In
>                 values: [linux]
> ```
>
> Marking `tls.key` on the same file produces `^(key|tls\.key)$` — a different
> regex, but it still carries `key` as an alternative, so it seals that same
> affinity term.
>
> The rendered chart then fails, and every GitOps sync of that cluster fails to
> decrypt with `Input string kubernetes.io/hostname does not match sops data
>   format`, until the file is decrypted again.
>
> Give the value a distinctive key name instead (`opsgenieApiKey`, `smtpPassword`),
> or seal the whole credential as its own Secret manifest. Renaming the parent
> section does not help; only the last segment decides what is matched.

***

## Encrypting Keys by Pattern

An entry in the **Encrypted Keys (SOPS)** list is normally a literal key name, matched exactly. Prefix an entry with `glob:` to seal every key whose name matches a pattern instead - including keys added to the document later:

```yaml theme={null}
encrypted_paths:
  - username     # literal entry - matches the key "username" exactly
  - glob:DB_*    # pattern entry - matches every key whose name starts with DB_
```

### Pattern Rules

* **`glob:` is the opt-in.** Entries without the prefix keep their exact-match meaning, so a literal key name that contains a dot (`cloud.conf`, `.dockerconfigjson`) is never reinterpreted as a pattern.
* **Only `*` is a wildcard.** It matches any run of characters, including none. Every other character is literal.
* **A pattern describes a key name, not a path.** SOPS matches key names at every depth of the document, so `glob:DB_*` seals a top-level `DB_PASSWORD` and a nested `backups.DB_PASSWORD` alike.
* **A leading `data.` or `stringData.` section is accepted and stripped**, the same as for a literal entry: `glob:stringData.DB_*` and `glob:DB_*` select the same keys.
* **The entry is stored as written.** `encrypted_paths` keeps `glob:stringData.DB_*` verbatim, and Ankra re-expands it into the SOPS `encrypted_regex` on every push. A key added to the document next month is sealed by the same rule, with no change to the declaration - and because the rule lives in the SOPS metadata, a key you seal by hand with the `sops` editor is matched the same way.

**Example**: Sealing every `DB_` key of a Secret with `glob:stringData.DB_*`

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: app-database
  namespace: app
type: Opaque
stringData:
  LOG_LEVEL: info    # no entry matches - stays plaintext
  DB_HOST: ENC[AES256_GCM,data:vxvYs7vKw+bPqNWO3tE=,iv:...,tag:...,type:str]
  DB_PASSWORD: ENC[AES256_GCM,data:aXvYs7vKw+bPqNWO3tF=,iv:...,tag:...,type:str]
sops:
  age:
    - recipient: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
      enc: |
        -----BEGIN AGE ENCRYPTED FILE-----
        YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBxVEdI...
        -----END AGE ENCRYPTED FILE-----
  encrypted_regex: ^(DB_.*)$
  version: 3.9.4
```

### Rejected Patterns

A pattern that cannot mean what was intended is rejected when you save, with an error naming the entry and the reason (over the API this is an HTTP 422, for example `Invalid encrypted_paths entry "glob:password": contains no * wildcard; declare an exact key name without the glob: prefix`):

| Entry | Why it is rejected |
| - | - |
| `glob:` | The prefix must be followed by a key-name pattern, such as `glob:stringData.DB_*` |
| `glob:stringData.` | Names a section but no key-name pattern |
| `glob:password` | Contains no `*` wildcard - declare the exact key name without the prefix so it keeps exact-match semantics |
| `glob:*` | Would match every key in the document, `metadata.name` and `kind` included - keep at least one literal character |

A valid pattern that matches **zero keys** fails later, at encrypt or push time, exactly like a misspelled literal key: rather than write a file that only looks encrypted, Ankra refuses with an error such as `declared encrypted_paths [glob:DB_*] match no key in this document, so sops encrypted nothing`. Fix the pattern (or add the keys it should match) and save again.

### An Empty or Absent Declaration

What keeps a file sealed on a platform write is its declaration. Ankra seals the file from `encrypted_paths` on every push it makes, and a manifest or add-on with no entries is written as plain content.

* **No entries, no checks.** Every check on a declaration runs on the entries it carries. The store-time guard, the `match no key in this document` refusal and the over-match warning `ankra cluster validate` reports (category `encrypted_paths_over_match`) are all skipped when there are none; only plaintext-secret detection still runs, on the content itself. Silence from those checks on a resource with an empty declaration is not evidence that its file is sealed.
* **Over the API, `[]` and an absent key mean different things.** On an update, omitting `encrypted_paths` keeps the stored declaration; sending `encrypted_paths: []` replaces it with nothing. If the file is sealed in your repository, the next platform write renders it as plain content and overwrites the sealed copy. Send the key only when you mean to set the declaration.
* **The CLI drops an empty list.** `ankra cluster apply` sends `encrypted_paths` only when it has entries, so `[]` in a cluster YAML applied with the CLI behaves like an absent key and keeps whatever is stored. A sealed `from_file` is sent as it is on disk; when no declaration is stored for it, the apply is refused with `content is SOPS-encrypted but encrypted_paths is empty`.
* **In a Git repository Ankra syncs, the file wins.** When Ankra reads the cluster directory, the declaration for a sealed file is derived from its `sops` metadata and replaces whatever the cluster YAML declares; the cluster YAML is rewritten with the derived entries on the next platform write. The cluster YAML Ankra renders lists `encrypted_paths: []` for every add-on and manifest without a declaration, so that line on its own only says that nothing is declared.

***

## Using the CLI

You can also encrypt and decrypt values using the Ankra CLI for local GitOps workflows.

### Encrypting Manifest Values

```bash theme={null}
# Encrypt a key in a manifest
ankra cluster encrypt manifest trinity-database-secret --key TRINITY_DB_PASSWORD -f cluster.yaml
```

This will:

1. Find the manifest in the cluster YAML
2. Read the referenced manifest file
3. Encrypt the specified key using your organisation's SOPS key
4. Update the manifest file with encrypted values
5. Add the key to `encrypted_paths` in the cluster YAML

### Encrypting Addon Values

```bash theme={null}
# Encrypt a key in addon configuration
ankra cluster encrypt addon --name grafana --key adminPassword -f cluster.yaml
```

### Encrypting Keys by Pattern with the CLI

`--key` also accepts the `glob:` pattern form described in [Encrypting Keys by Pattern](#encrypting-keys-by-pattern):

```bash theme={null}
# Encrypt every key ending in Password, now and on every later re-encrypt
ankra cluster encrypt addon --name grafana --key 'glob:*Password' --cluster prod

# Encrypt every DB_ key of a Secret manifest
ankra cluster encrypt manifest db-secret --key 'glob:stringData.DB_*' --cluster prod
```

The pattern is recorded in `encrypted_paths` as written, so keys added later are sealed automatically the next time the values are encrypted. A pattern that matches no key fails the same way a misspelled exact key does. See [ankra cluster encrypt](/reference/cli/cluster#ankra-cluster-encrypt) for the full flag reference.

### Decrypting for Inspection

To view the decrypted contents of a manifest file:

```bash theme={null}
# View decrypted manifest content
ankra cluster decrypt manifest trinity-database-secret -f cluster.yaml
```

> [!TIP]
>
> The decrypt command prints to stdout, so you can pipe it to other tools or redirect to a file if needed.

### Adding Keys to Existing Encrypted Files

You can add new encrypted keys to files that are already SOPS-encrypted:

```bash theme={null}
# File already has 'password' encrypted, now add 'api_token'
ankra cluster encrypt manifest my-secret --key api_token -f cluster.yaml
```

The CLI will automatically decrypt the file, merge the encrypted paths, and re-encrypt with all keys protected.

> [!WARNING]
>
> This only works if the file was encrypted with your organisation's SOPS key. If the file was encrypted by a different organisation, you'll see an error message and need to decrypt it first using the original key.

For more CLI commands, see the [Ankra CLI documentation](/reference/cli/cluster#ankra-cluster-encrypt).

***

## How Decryption Works

Your organisation's AGE private key is kept in Ankra's secret store. How a cluster uses it depends on the [deployment engine](/concepts/deployment-engines) of the add-on or manifest being deployed.

### Native engine

The Ankra agent decrypts sealed values itself. When a deploy reaches a sealed file, the agent requests the organisation's private key from Ankra, runs `sops --decrypt` inside your cluster, and hands the result to Helm or applies the manifest. Nothing is installed in the cluster beforehand and there is no per-cluster setup. This is the default engine for clusters created since May 2026.

### ArgoCD engine

On clusters that use ArgoCD, Ankra configures ArgoCD to decrypt during Helm template rendering:

1. **Deploys the AGE private key** as a Kubernetes Secret in the ArgoCD namespace
2. **Configures helm-secrets plugin** on the ArgoCD repo-server
3. **Sets up automatic decryption** during Helm template rendering

| Component | Namespace | Purpose |
| - | - | - |
| `ankra-sops-age-key` Secret | `argocd` | Stores the AGE private key |
| helm-secrets plugin | ArgoCD repo-server | Enables SOPS decryption in Helm |
| SOPS binary | ArgoCD repo-server | Performs the actual decryption |

The helm-secrets plugin is automatically configured with:

* `HELM_SECRETS_BACKEND=sops` - Use SOPS for decryption
* `SOPS_AGE_KEY_FILE=/ankra-sops-age-key/age.agekey` - Path to the private key
* Support for `secrets://` value file scheme

***

## Troubleshooting

> [accordion] Deployment Fails with Decryption Error
>
> 1. Verify SOPS is initialized at the organisation level (**Organisation Settings** → **Encryption**)
> 2. Ensure the content was encrypted with the current organisation key (compare `sops.age.recipient` in the file with the public key on the Encryption settings page)
> 3. On the ArgoCD engine only, confirm the cluster has ArgoCD installed and that the repo-server has restarted:
>
> ```bash theme={null}
> # Check ArgoCD repo-server logs
> kubectl logs -n argocd -l app.kubernetes.io/component=repo-server | grep -i sops
> ```
>
> On the native engine the failing step's own message in the deployment view names the file and the reason.

> [accordion] Cluster Not Decrypting Encrypted Values
>
> On the native engine the agent decrypts on its own and needs nothing installed in the cluster, so check the first entry above instead.
>
> An add-on that uses the ArgoCD engine needs ArgoCD to decrypt. If ArgoCD is not installed:
>
> 1. Create a Stack with the ArgoCD add-on
> 2. Deploy and wait for ArgoCD to become ready
> 3. The SOPS decryption key will be deployed automatically

> [accordion] Values Not Being Encrypted
>
> 1. Look in your Git repository, not in the Stack Builder. The Stack Builder always shows the value you entered; sealing happens when Ankra writes the file to Git
> 2. Check that the key name matches exactly (case-sensitive)
> 3. Verify SOPS is initialized at the organisation level
> 4. Ensure the key is added to the **Encrypted Keys** list before saving
>
> Name a top-level key directly, or use dot notation to locate a nested one. Either way the entry names a key, and every key of that name in the document is sealed - see [What an Entry Actually Matches](#what-an-entry-actually-matches).

> [accordion] A Chart Field Was Encrypted That Should Not Have Been
>
> An entry seals every key of that name at every depth, so an entry named after a structural field (`key`, `name`, `path`, `value`, `type`, `host`, `port`, `operator`) also seals the chart's own fields. Check dotted entries by their **last segment**: `tls.key` and `metadata.name` are the same hazard as a bare `key` or `name`. The symptom is a render or sync failure naming a value that was never a secret, such as `Input string kubernetes.io/hostname does not match sops data format`.
>
> Decrypt the file, remove the over-broad entry from **Encrypted Keys (SOPS)**, give the secret a distinctive key name, and re-encrypt. See [What an Entry Actually Matches](#what-an-entry-actually-matches).
>
> If that entry is the **last** `encrypted_paths` entry anywhere on the cluster, removing it also stops Ankra rendering the cluster's `.sops.yaml`, and the next platform write prunes the file along with any creation rules you keep there by hand. Keep a copy first - see [Merging the SOPS configuration file](/concepts/gitops#merging-the-sops-configuration-file).

> [accordion] Save Rejected with an Invalid encrypted\_paths Entry
>
> A `glob:` pattern entry the grammar rejects fails the save with `Invalid encrypted_paths entry "...": <reason>`. The reason names the fix:
>
> * `contains no * wildcard` - the pattern has no `*`; declare the exact key name without the `glob:` prefix
> * `would match every key in the document` - the pattern is only wildcards; keep at least one literal character
> * `must be followed by a key-name pattern` or `names a section but no key-name pattern` - add the pattern after the prefix or section, such as `glob:stringData.DB_*`
>
> An error saying declared paths `match no key in this document` means every entry (literal or pattern) selected nothing - check the spelling against the document's actual key names. See [Encrypting Keys by Pattern](#encrypting-keys-by-pattern) for the full rules.

> [accordion] A Sealed File Came Back as Plaintext After an API Update
>
> An update sent over the API with `encrypted_paths: []` clears the stored declaration, and the next platform write renders the file as plain content over the sealed copy. Restore the declaration (declare the keys again, or re-encrypt with `ankra cluster encrypt`) and rotate any value that reached the repository in plaintext. On updates, omit the key to keep the stored declaration - see [An Empty or Absent Declaration](#an-empty-or-absent-declaration).

***

## AI Prompts

Press `⌘+J` to open the AI Assistant and use these prompts:

> [accordion] Set Up SOPS for a Stack
>
> ```
> I have a Stack with database credentials. Help me encrypt
> the password field with SOPS before pushing to Git.
> ```

> [accordion] Troubleshoot Decryption Failure
>
> ```
> My Stack deployment is failing with a SOPS decryption error.
> Help me troubleshoot.
> ```

***

## Advanced Configuration

The defaults described above work for most setups. The following sections cover optional configuration that you may need if you want to change the default behaviour.

### Disabling Organisation Encryption

SOPS encryption is enabled by default after initialization. If you need to temporarily stop encrypting new values (existing encrypted content remains encrypted):

1. Go to **Organisation Settings** → **Encryption**
2. Toggle **SOPS Encryption** off

While it is off, Ankra does not write a file with listed keys to Git unsealed: a push of that file is refused until encryption is re-enabled. Re-enable at any time to resume encryption. This does not affect clusters' ability to decrypt already-encrypted values.

### Per-Cluster Decryption Toggle

On the ArgoCD engine, Ankra automatically deploys the SOPS decryption key to every cluster that has ArgoCD. If you need to manage this manually for a specific cluster:

1. Go to your cluster → **Settings** → **Encryption**
2. Toggle **Enable SOPS Decryption** on or off

> [!WARNING]
>
> Disabling cluster decryption will cause deployments with encrypted values to fail on that cluster. Only disable this if the cluster should not process encrypted Stacks.

### Key Rotation

Key rotation is not available as a self-service control in the portal or the CLI today.

Rotating the organisation key is more than generating a new pair: every file already sealed in your Git repositories has to be re-encrypted with the new public key before the old private key is retired, or those files can no longer be decrypted at deploy time.

***

## Related

> [card] [Stacks](/concepts/stacks)
>
> Build and deploy reusable Stack configurations.

> [card] [GitOps](/concepts/gitops)
>
> Sync Stacks with Git repositories.

> [card] [Cloudflare Tunnel](/guides/cloudflare-tunnel)
>
> Encrypt tunnel tokens with SOPS.

> [card] [Manifests](/concepts/stacks#manifests)
>
> Create custom Kubernetes resources with encryption.


# Stack Profile Demos
Source: https://docs.ankra.ai/guides/stack-profile-demos

Run a stack profile on your staging cluster as a throwaway, time-limited deployment - no cluster of your own required, and it tears itself down

> [!NOTE]
>
> A stack profile demo installs a profile's add-ons and manifests into their own isolated namespace on your organisation's staging cluster, and stops itself when the timer runs out. Use it to see what a profile actually deploys before you instantiate it onto a real cluster, to check a new version against the old one, or to hand a colleague something running instead of a YAML file.

This is the profile-side twin of [branch demos](/guides/branch-demos). A branch demo runs an application's build; a profile demo runs the stack itself, with no application in front of it.

***

## Prerequisites

**1. Set the organisation's staging cluster**

An admin sets it under **AI** → **Settings** → **Workspaces**. Every demo lands there. Without it, the Demos tab explains that and offers nothing to launch.

**2. Have a stack profile you can read**

Your own profiles, profiles shared with your organisation, and public profiles can all be demoed. The demo runs on your staging cluster, so demoing someone else's public profile costs them nothing.

**3. Hold the stacks deploy permission**

A demo is a real deployment through the resource engine. Without the permission the Demos tab is read-only and says so.

***

## Launch a demo

Open the profile and go to the **Demos** tab, then choose **Launch demo**.

The dialog asks for two things:

* **Parameters** - whatever the profile's current version declares. Required inputs are marked; secret parameters bind to an organisation secret slot rather than a typed value, so the plaintext never travels through the browser and is resolved from Ankra's secret store only at deploy time.
* **Lifetime** - how long the demo lives, defaulted to your organisation's demo TTL and capped by your role.

Ankra then creates the namespace, applies its quota, and instantiates the profile into it with every member forced into that one namespace.

### One demo per profile

A profile has at most one live demo per organisation. Its namespace is derived from the organisation and profile ids - `ankra-demo-sp-<org>-<profile>` - so launching again **replaces** the running demo rather than adding a second copy. That is also why renaming a profile never strands a demo.

Relaunch to pick up a new profile version or changed parameter values.

### Capacity

The demo namespace carries a hard `ResourceQuota` at the full-stack tier, because a profile installs a whole stack rather than one workload:

| | Pods | CPU limit | Memory limit |
| - | - | - | - |
| Stack profile demo | 20 | 8 | 16 Gi |

***

## Watch it come up

The demo list shows the status and what the stack is doing - *waiting to instantiate*, *installing add-ons*, *stack deployed*. Open **Details** for the live picture, read from the staging cluster on every poll:

* **Progress** - namespace created, guardrails applied, stack instantiated. A profile demo deploys no workload of its own, so there is no image or routing step to wait on: the stack operation completing *is* readiness.
* **What the profile installed** - every Deployment, Service, Ingress, ReplicaSet and Pod in the namespace, with the live manifest behind each one.
* **Events** - the Kubernetes events for the namespace, newest first.
* **Logs** - a bounded tail from any pod in the namespace, fetched on demand.

If a chart fails to install, the failure text is the stack's own - "no matching PVC storage class" rather than "the demo failed".

***

## Stopping

**Stop** uninstalls the stack and deletes the namespace. Because Helm uninstall jobs have to drain before the namespace can go, a stop is asynchronous: the demo is marked *stopping* and the reaper finishes the teardown. Every demo also stops on its own at the end of its lifetime, whether or not anyone remembers it.

***

## Application demos and profile demos

An application's demo settings can designate a stack profile, in which case every demo of that application deploys **its own replica** of the profile alongside the app (see [Branch Demos](/guides/branch-demos#full-stack-demos)). That replica and a profile demo are the same stack seen from two sides, so each list links to the other:

* The application's **Previews** section names the profile its demos replicate and lists that profile's own live demos, each linking straight to its details.
* The profile's **Demos** tab lists the applications designating it.

When you only want to look at the stack, launching the profile demo is cheaper than launching a whole application demo for it.

***

## API

All endpoints sit under the profile and require authentication; the mutations require a CSRF header for browser-originated requests. Bearer-PAT twins live under `/api/v1/org/stack-profiles/...` for the CLI.

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/org/stack-profiles/{profile_id}/demos` | The profile's live demos, your TTL policy, the staging cluster, the current version's parameters, and the applications designating this profile |
| `POST` | `/org/stack-profiles/{profile_id}/demos` | Launch a demo (`version`, `parameters`, `ttl_hours`) |
| `GET` | `/org/stack-profiles/{profile_id}/demos/{workspace_id}/detail` | The demo plus the live inspection of its namespace |
| `GET` | `/org/stack-profiles/{profile_id}/demos/{workspace_id}/logs` | A bounded log tail (`pod`, `container`, `tail_lines`) |
| `DELETE` | `/org/stack-profiles/{profile_id}/demos/{workspace_id}` | Stop the demo |

See [Stack Profiles](/concepts/stack-profiles) for authoring and versioning, and [Branch Demos](/guides/branch-demos) for the application lane.


# Stack Profile Suggestions
Source: https://docs.ankra.ai/guides/stack-profile-suggestions

Propose changes to a stack profile you can see but do not own, and review, approve, or reject the suggestions other organisations send to profiles you publish

> [!NOTE]
>
> When a [stack profile](/concepts/stack-profiles) is public or shared with your organisation, you can do more than deploy it: open it in the builder, edit it, and send the result to the owning organisation as a **suggestion**. The owner reviews the diff and either approves it - publishing it as the profile's next version - or rejects it with a note. The profile itself stays owner-only throughout: a suggestion never changes anything until an owner approves it.

This is how a fix you have proven in production travels back to a shared or public profile without the owner handing out write access - and without exporting YAML and mailing it around. It is also the right lane for the owner's own updates: a builder draft keeps the version's input annotations (titles, descriptions, enum choices, and choices that set other inputs), while editing an IaC export and re-importing it re-detects the inputs from the spec, drops those annotations, and creates a separate new profile instead of a new version.

***

## Propose a change to a profile you do not own

### Prerequisites

**1. Be able to see the profile**

Public profiles and profiles [shared with your organisation](/concepts/stack-profiles#share-with-specific-organisations) both qualify. Shared profiles carry a "Shared with you" label in your profile list.

**2. Not own it**

On profiles your organisation owns you have **Edit Builder** and publish directly; the suggestion lane exists for everyone else's profiles.

### Edit and submit

**1. Open the profile and choose Suggest changes**

On a profile you do not own, the builder button reads **Suggest changes** instead of **Edit Builder**. It opens the stack builder on a draft seeded from the profile's latest version, held in your own organisation. Choosing it again later resumes the same draft - your organisation has one open suggestion draft per target profile, so a second click never forks a second copy.

**2. Edit like any other draft**

Change add-ons, manifests, variables, and inputs exactly as in your own profiles. The draft autosaves as you work, and the header shows a readiness chip - **Ready to publish**, or a count of blockers you can click to see what submit would refuse.

**3. Submit the suggestion**

Choose **Submit suggestion**. Give it a title (one line summarising the proposed change - this is what the owner's review queue shows) and, optionally, a description explaining why the owning organisation should apply it. On submit you land on the profile's **Suggestions** tab with your proposal listed as *open*.

Submitting freezes the draft into the suggestion: the exact spec and inputs at that moment, plus the profile version the draft was seeded from (its base). The draft itself is consumed. A submitted suggestion cannot be edited - to revise one, withdraw it, choose **Suggest changes** again, and submit anew.

### While it is open

* Your suggestion appears on the profile's **Suggestions** tab. On a profile you do not own, the tab shows only your own organisation's suggestions; the owner sees everyone's.
* **Withdraw** takes an open suggestion out of review - the owning organisation can no longer approve it. Withdrawing still works even if the owner revoked your share grant in the meantime.
* Each suggestion carries a status: *open*, *approved* (with the version it was published as), *rejected* (with the owner's note, if they left one), or *withdrawn*.

### If the profile moves on while you edit

The draft's base is pinned to the version it was seeded from. You can still submit, and the owner's review flags the drift (see below), but your proposal will not include the newer changes. To start from the newer version instead, discard the draft with **Discard draft** and choose **Suggest changes** again - suggestion drafts cannot be rebased.

### Keep it as your own copy instead

A suggestion draft can also be published as a profile of your own: **Publish as copy** creates a brand-new profile in your organisation from the draft, independent of the original. Use it when the owner rejects your change, or when your variant diverges too far to be a suggestion.

***

## Review suggestions on a profile you own

Open the profile's **Suggestions** tab. It badges the number of open suggestions, and each row shows the title, status, proposing organisation, and when it was submitted.

**1. Expand a suggestion**

You get the proposer's description and the full change list from the suggestion's base version to the proposal - the same rendering as a version diff, covering structure, manifest settings, and add-on chart versions - plus the raw before/after view.

**2. Check for upstream drift**

If you have published versions since the suggestion was based, the review warns you: the proposal was based on an older version, and approving publishes the proposed contents as the next version *without* the newer changes. Approving never merges - it publishes exactly what was frozen at submit.

**3. Approve or reject**

**Approve** publishes the frozen contents as the profile's next version and closes the suggestion in one step - the row then shows which version it was published as. The release notes default to one composed from the suggestion's title; edit them before confirming if you want the version history to say more. **Reject** closes the suggestion without publishing; the note you leave is shown to the proposing organisation.

Only the owning organisation can approve or reject, and only the proposing organisation can withdraw. Resolving is first-writer-wins: if a colleague approves or rejects a suggestion while you have it open, your action reports it was already resolved and the list refreshes. Every submit, approve, reject, and withdraw is recorded in the [audit log](/guides/audit-log).

***

## Secrets never travel through a suggestion

The suggestion lane applies the same secret handling as publishing a profile version, in both directions:

* The draft behind **Suggest changes** is seeded from the published version, which stores secret *inputs*, never secret values - so the owner's credentials are not in what you edit.
* At submit, the payload goes through the same redaction as publish: any secret value in the draft is stripped and declared as a required secret input instead. A suggestion that would still carry a plaintext secret is refused outright, as is a spec carrying a secret placeholder at paths nothing declares as a secret input - so an approved version can never deploy a literal placeholder as a credential.
* The same checks run again at approve, before the frozen payload becomes a published version.

Whoever instantiates the approved version binds their own secret values at deploy time, exactly as with any other profile version.

***

## Stale drafts and rebase on your own profiles

The owner-side twin of upstream drift: you are editing your own profile in the builder and someone else publishes a new version first. Publishing your draft refuses rather than silently overwriting, and the builder offers the choice:

* **Reset to latest** replaces the draft's contents with the latest published version, discarding your edits.
* **Publish my edits anyway** keeps your edits and publishes them as the next version - an explicit decision that your draft supersedes the version published in between, whose changes are not merged in.

Rebasing applies only to drafts editing a profile your organisation owns. A suggestion draft pins its base instead, and its drift is surfaced to the owner at review time.

***

## From the CLI

The same lane is scriptable with the [Ankra CLI](/integrations/ankra-cli) (v0.13.0 or later); the full flag reference is at [ankra stack-profiles](/reference/cli/stack-profiles).

```bash theme={null}
# Open a draft on the profile you want to change. On a profile another
# organisation owns, this is a suggestion draft.
ankra stack-profiles drafts create --profile <profile-id>

# Refine what the launch form shows for an input
ankra stack-profiles drafts annotate <draft-id> --parameter replicas \
  --description "Replicas per zone; 3 is the tested production value"

# Preflight the checks submit will run
ankra stack-profiles drafts validate <draft-id>

# Send it for review
ankra stack-profiles drafts submit-suggestion <draft-id> \
  --title "Raise the default replica count to 3"
```

Reviewing as the owner:

```bash theme={null}
ankra stack-profiles suggestions list <profile-id>
ankra stack-profiles suggestions get <profile-id> <suggestion-id>
ankra stack-profiles suggestions approve <profile-id> <suggestion-id> \
  --changelog "Adopt the community replica defaults"
ankra stack-profiles suggestions reject <profile-id> <suggestion-id> \
  --note "We keep single-replica defaults for the starter tier"

# Proposer side: take an open suggestion back
ankra stack-profiles suggestions withdraw <profile-id> <suggestion-id>
```


# Talos Linux Clusters
Source: https://docs.ankra.ai/guides/talos-clusters

Run Ankra on Talos Linux clusters - Talos secures and runs the nodes and the control plane, Ankra runs everything above the Kubernetes API: Stacks, GitOps, applications, pipelines, backups, access and AI operations. Covers what each one owns, what Ankra adds that Talos leaves out, and how to import a Talos cluster.

[Talos Linux](https://www.talos.dev) is an operating system built only to run Kubernetes. It is immutable, has no shell or SSH, and is managed entirely through an API. Ankra runs everything that goes on top of it. Talos stops at a healthy, conformant Kubernetes API, and that API is where Ankra starts.

The two share a philosophy. Both are declarative and API-driven, and both take hand-run commands out of production: Talos removes SSH from the node, and Ankra changes the cluster only from Git through its own engine and governed access. Together, the estate is changed through declarations and governed APIs, not from a shell on a node.

A Talos cluster joins Ankra as an [imported cluster](/guides/import-cluster#import-an-existing-cluster). Nothing about how you run Talos has to change.

## How the layers fit

```mermaid theme={null}
flowchart TB
    subgraph ankra["Ankra - what runs on the cluster, and how people reach it"]
        apps["Applications and pipelines"]
        stacks["Stacks, add-ons and GitOps"]
        access["Access, audit and AI operations"]
        observe["Metrics, logs and backups"]
    end
    api["Kubernetes API - the hand-off between the two"]
    subgraph talos["Talos - the node, the OS and the control plane"]
        cp["Control plane and etcd"]
        os["Immutable node OS, no SSH"]
        mapi["Machine API: talosctl, Omni"]
    end
    infra["Bare metal, Proxmox, any cloud"]
    ankra --> api
    api --> talos
    talos --> infra
```

The Kubernetes API is the only contract between the two layers. Talos keeps it healthy and secure; the [Ankra Agent](/concepts/cluster-agent) uses it for everything Ankra deploys and observes.

## What Talos gives you

* **Immutable and minimal.** A read-only root filesystem, no package manager, no shell and no SSH, so there is very little on a node to patch or attack.
* **API-managed.** Every node is configured from a machine config through the `talosctl` API, authenticated with mutual TLS.
* **A declarative node lifecycle.** Bootstrapping, joining nodes, OS upgrades and Kubernetes upgrades all go through the same API.
* **Secure defaults.** Hardened kernel and services, KubeSpan for encrypted node-to-node networking, and disk encryption.
* **Runs anywhere.** Bare metal, VMs, Proxmox and the major clouds, often managed at scale with Sidero Omni.

When Talos has done its job you have a hardened, conformant and empty Kubernetes cluster. What goes into it, and how it is run day to day, is out of its scope.

## What Ankra adds that Talos leaves out

Each row is something a Talos team otherwise has to build and run itself.

| Capability | Talos on its own | What Ankra adds |
| - | - | - |
| Platform add-ons (ingress, cert-manager, DNS, monitoring, policy) | Not in scope. You install and upgrade Helm charts yourself. | [Stacks](/concepts/stacks) of pinned Helm add-ons and manifests, deployed in dependency order with `parents` and deploy waves. |
| GitOps for workloads | Not in scope. You bring and operate your own GitOps controller. | A built-in [GitOps](/concepts/gitops) engine: Stacks live in your Git repository, Ankra syncs them and shows drift. |
| Deploying your own code | Not in scope. | [Applications](/concepts/applications): connect a repository and get a generated Dockerfile, chart and pipeline, deployed to one or many clusters. |
| CI/CD | Not in scope. | [Ankra Pipelines](/pipelines/overview) run `.ankra/pipeline.yaml` on your own CI cluster: rootless builds, Semgrep, Checkov and Trivy scans, immutable `sha-` tags and promotion. |
| Secrets in Git | Not in scope beyond Kubernetes Secrets. | [SOPS and AGE encryption](/guides/sops) with `ankra cluster encrypt`, decrypted at deploy time through `encrypted_paths`. |
| Observability | Node logs and kernel messages through `talosctl`. No metrics stack or dashboards. | [Central metrics and logs](/guides/monitoring-stack) across clusters, metrics pages, log history, `ankra cluster top` and PromQL queries. |
| Backups and restore | etcd snapshots through `talosctl etcd snapshot`. No application data. | [Backup vaults](/guides/backups), scheduled protection per Stack, restore in place, and cloning a Stack with its data onto another cluster. |
| People's access to workloads | An admin kubeconfig and talosconfig, shared by whoever holds them. | The kube gateway with SSO, roles, time-boxed grants, break-glass elevation and an audit log. See [Cluster Access](/guides/cluster-access). |
| Debugging without a shell | No SSH and no shell on the node. | [Debug pods](/platform/debug-pods) that impersonate a workload under a tools image, with recorded terminal sessions, and `ankra cluster exec`. |
| One view of the fleet | Per cluster, or per Omni instance. | One organisation across Talos, managed and cloud clusters: inventory, operations, cost and security posture. |
| Reuse across clusters | Machine config patches, for the OS only. | [Stack profiles](/concepts/stack-profiles): a parameterised Stack published once and rolled out across the fleet. |
| Vulnerabilities in workloads | Hardens the OS only. | [Security reports](/guides/security-reports) with fleet-wide CVE findings and exploitation intelligence. |
| AI operations | None. | [Ankra's AI](/platform/ai-overview) for troubleshooting, incident summaries, pull request reviews and fix pull requests, governed by roles. |

Talos secures and runs the machine; Ankra runs what the machine is for.

## Connect a Talos cluster

**1. Build the cluster with Talos**

Create it as you normally would - `talosctl gen config`, `talosctl apply-config` and `talosctl bootstrap`, or a cluster in Omni - and confirm the Kubernetes API is healthy.

**2. Import it into Ankra**

A new organisation needs a [payment method](/platform/billing#credit-and-payment-method) saved before it can import a cluster; the free playground runs without one. Go to **Clusters**, import a cluster (**Connect a cluster** in the new portal), and run the `helm` command Ankra shows against the Talos cluster. [Import an existing cluster](/guides/import-cluster#import-an-existing-cluster) walks through it. `ankra cluster agent token` prints the cluster's agent token again if you need it.

**3. Check the connection**

```bash theme={null}
ankra cluster select my-talos-cluster
ankra cluster agent status
ankra cluster info
```

The agent reports as connected and the cluster's nodes and Kubernetes version appear in the portal.

**4. Declare the platform in Git**

Write an `ImportCluster` file that points at your GitOps repository and declares your first Stack:

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: my-talos-cluster
spec:
  git_repository:
    provider: github
    credential_name: my-git-credential
    repository: my-org/my-repo
    branch: main
  stacks:
    - name: ingress
      deploy_wave: 1
      manifests:
        - name: namespace-traefik
          parents: []
          from_file: "manifests/traefik-namespace.yaml"
      addons:
        - name: traefik
          chart_name: traefik
          chart_version: 37.1.1
          registry_name: traefik
          registry_url: https://traefik.github.io/charts
          namespace: traefik
          parents:
            - kind: manifest
              name: namespace-traefik
```

Check it, stage it for review, then apply it:

```bash theme={null}
ankra cluster validate -f cluster.yaml
ankra cluster draft -f cluster.yaml
ankra cluster apply -f cluster.yaml
ankra cluster operations list
```

**5. Add the rest as Stacks**

Monitoring, cert-manager, storage, policy and your applications each go in their own small Stack, with every chart version pinned.

## Who owns what on day 2

Each recurring task has exactly one owner, so the two never fight over the same object.

| Task | Owner | How |
| - | - | - |
| Talos OS upgrades | Talos | `talosctl upgrade` or Omni |
| Kubernetes version upgrades | Talos | `talosctl upgrade-k8s` or Omni |
| Adding or replacing nodes | Talos | The machine config and `talosctl apply-config`, or Omni |
| etcd snapshots | Talos | `talosctl etcd snapshot` on a schedule |
| Cordon and drain before node work | Either | `ankra cluster cordon` and `ankra cluster drain`, or Talos during an upgrade |
| Add-on upgrades | Ankra | Bump `chart_version` in Git and let Ankra reconcile |
| Application releases | Ankra | Pipelines build once and promote the same `sha-` tag |
| Secrets | Ankra | SOPS-encrypted in the GitOps repository |
| Application data backup and restore | Ankra | Backup vaults and Stack protection |
| Who can reach the cluster | Ankra | Kube gateway grants, roles and the audit log |
| Troubleshooting workloads | Ankra | `ankra cluster logs`, `describe` and `events`, debug pods, and Ankra's AI |

Keep the talosconfig with a small infrastructure group and give everyone else access through Ankra, so developers and on-call engineers never need cluster-admin credentials.

## Things to know

> [!WARNING]
>
> Ankra does not build or upgrade Talos clusters. Ankra builds kubeadm and k3s clusters on its [Ankra Managed](/guides/import-cluster#ankra-managed) providers, and `ankra cluster upgrade` applies only to those. On Talos, the OS and the Kubernetes version stay with `talosctl` or Omni.

* **Pod Security admission.** Talos enforces the `baseline` Pod Security level in every namespace except `kube-system`. A workload that needs host access needs its namespace labelled `pod-security.kubernetes.io/enforce: privileged`. That covers the node agents of monitoring, log shipping and backup stacks, such as node-exporter, Promtail and Velero's node agent, which mount host paths or use the host's network, and a CNI or storage driver installed outside `kube-system`. Ankra does not add the label for you. Until those namespaces allow privileged pods, the node agents behind the metrics, logs and backups rows above are refused. In a Stack you write, put the label on the namespace manifest, so it is in Git with everything else. Ankra's backup stack owns its `velero` namespace, so exempt `velero` through Talos's [Pod Security configuration](https://docs.siderolabs.com/kubernetes-guides/security/pod-security) (`exemptions.namespaces`) instead.
* **The CNI.** Talos ships Flannel by default. To run Cilium instead, install it while you build the cluster, before you import it into Ankra: set `cluster.network.cni.name: none` in the machine config and install Cilium as [Talos documents it](https://docs.siderolabs.com/kubernetes-guides/cni/deploying-cilium), for example as an inline manifest in the machine config or with `helm install` right after `talosctl bootstrap`. Ankra cannot install the first CNI: until one runs, the nodes stay `NotReady` and the Ankra agent cannot be scheduled. Upgrade Cilium the way that method documents; an inline manifest, for example, changes through the machine config and `talosctl upgrade-k8s`.
* **No second GitOps controller.** Ankra's engine syncs your Stacks from Git, so you do not need to run another one beside it.
* **Omni works alongside Ankra.** Omni manages Talos machines and clusters; Ankra manages what runs inside them. They sit on different layers.


# Sync Board Tickets to Jira, Linear, or a Webhook
Source: https://docs.ankra.ai/guides/ticket-sync

Add a sync connection so AI board tickets are mirrored into your own tracker - where every provider value comes from, what gets synced, and how to verify deliveries.

A **sync connection** mirrors [AI board](/platform/ai-board) tickets outbound. Each ticket that matches the connection's filters gets an issue created once in your tracker, and its timeline events follow as comments on that issue. Three providers are available: **Jira**, **Linear**, and a generic **webhook**.

Sync is **one-way**. Ankra creates the issue, adds comments and keeps its title current, and never reads anything back: editing, commenting on, reassigning or closing the issue in Jira or Linear changes nothing on the board, and a status change on the board arrives as a comment rather than moving the issue's own status. To act on a ticket from outside the portal, use the ticket's Slack or Teams thread, [`ankra tickets`](/reference/cli/tickets), or [your own agent over MCP](/guides/board-own-agent).

This is a different system from [webhook destinations](/guides/webhooks), which deliver alert firings and platform events. Sync connections carry board tickets only.

## Prerequisites

* You are an organisation **admin**. Members can see the connection list, but only admins can add, edit, enable, or delete one.
* The AI board is available in your organisation (**AI** → **Board** in the sidebar).
* The destination is reachable from the public internet.

> [!WARNING]
>
> Ankra dials sync destinations from its own infrastructure and refuses any address that is not publicly routable - loopback, private ranges, link-local (including the `169.254.169.254` cloud metadata endpoint), and IPv6 unique-local. A self-hosted Jira or a webhook receiver that only exists inside your VPN or cluster network cannot be reached. Literal private IPs are rejected when you save; a hostname that resolves to one is refused at delivery time and shows up as a failed delivery.

## What gets synced

A new connection picks up your organisation's **live** tickets plus anything that changes afterwards. The closed backlog stays out, so enabling Jira sync does not file a thousand finished tickets into a fresh project. Closed tickets only sync if they change again after the connection was created.

Three filters narrow it further, all set in the same dialog:

| Filter | Options | Default |
| - | - | - |
| **Kinds** | Incident, Insight, Gap, Automation, Request, Chore | none checked, which means every kind |
| **Minimum priority** | Low and above (every ticket), Medium and above, High and above, Urgent only | Low and above |
| **Timeline events** | Relay timeline events as comments, or create the external issue only | Relay timeline events as comments |

> [!WARNING]
>
> **Create the external issue only** (`anchor_only`) is not a pause. The timeline cursor moves to the tail as tickets change, so events skipped while the connection is in this mode are skipped permanently. Switching back to relaying comments later resumes from that point and never backfills what was missed.

## Step 1: Collect your provider's details

Gather these before you open the dialog. It has no draft state, so a value you have to go and look up means starting the form again.

> [tab] Jira
>
> You need four values, plus one optional one.
>
> **1. Jira base URL**
>
> Your Jira site root, with no path after it - for example `https://my-team.atlassian.net`. Copy it from the address bar while you are in Jira, and drop everything from `/jira` onwards.
>
> **2. Project key**
>
> The short uppercase code for the project issues should land in. In Jira, open **Projects** and read the **Key** column, or take the prefix from any issue key in that project: `OPS-123` means the key is `OPS`.
>
> **3. Issue type (optional)**
>
> The name of the issue type to create, exactly as it appears in Jira - `Task`, `Bug`, `Story`. It has to exist in that project's issue type scheme. Leave the field blank to use `Task`.
>
> **4. Account email**
>
> The email address of the Atlassian account the API token belongs to. Issues and comments in Jira are attributed to this account, so a dedicated service account keeps your board traffic out of a person's name.
>
> **5. API token**
>
> Sign in as that account, go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens), and choose **Create API token**. Label it something you will recognise later, such as `ankra-ticket-sync`, then copy the token.
>
> > [!WARNING]
> >
> > Atlassian shows the token once. Copy it before closing the dialog.
>
> That account needs these permissions **in the target project**, or deliveries fail with a Jira `403`:
>
> * **Browse Projects** - to address the project at all
>
> * **Create Issues** - the issue Ankra opens per ticket
>
> * **Add Comments** - the timeline relay
>
> * **Edit Issues** - Ankra pushes the ticket title onto the issue when it changes
>
> > [!NOTE]
> >
> > Ankra talks to Jira over the REST v2 API using HTTP basic authentication, which is the Jira Cloud email plus API token shape. Jira Data Center serves the same API, so a Data Center username and password go in those same two fields - as long as the instance is reachable on the public internet.

> [tab] Linear
>
> You need one value: an API key. Ankra reads your teams from it, so there is no team id to look up.
>
> **1. Personal API key**
>
> In Linear, open **Settings** → **Security & access** → **Personal API keys** and choose **New API key**. Give it a label such as `Ankra ticket sync`, and grant it write access to the team you are syncing into. Copy the key - it starts with `lin_api_` and Linear shows it once.
>
> > [!TIP]
> >
> > The key acts as the Linear user who created it, so issues and comments appear under that person's name. Create it from a dedicated service user if you would rather board traffic did not look like one teammate's work.
>
> **2. Team**
>
> Paste the API key into the dialog, choose **Load teams**, and pick your team from the list by name. Ankra asks Linear which teams that key can reach and stores the team's id for you.
>
> When you edit an existing Linear connection, the list loads on its own from the key Ankra already holds - there is nothing to paste again.
>
> Two things to expect from the list:
>
> * It shows only the teams the key can see. If a team is missing, the key was created by someone without access to it.
>
> * Ankra remembers the team's name to label the connection, but delivers against its id. Renaming the team in Linear leaves the old name on the row until you pick it again.
>
> > [accordion] Finding the team id yourself
> >
> > The picker is the supported path in the interface. If you are creating the connection through the API instead, or the picker cannot reach Linear, `config.team_id` takes the team's **UUID** - not the short team key you see in the interface (`ENG`, `OPS`). Linear does not show the UUID in its settings screens, so query the API for it:
> >
> > ```bash theme={null}
> > curl -s https://api.linear.app/graphql \
> >   -H "Authorization: <your-linear-api-key>" \
> >   -H "Content-Type: application/json" \
> >   -d '{"query":"{ teams { nodes { id key name } } }"}'
> > ```
> >
> > The response lists every team the key can see:
> >
> > ```json theme={null}
> > {
> >   "data": {
> >     "teams": {
> >       "nodes": [
> >         { "id": "8f1a2b3c-4d5e-4f60-9a71-2b3c4d5e6f70", "key": "OPS", "name": "Operations" }
> >       ]
> >     }
> >   }
> > }
> > ```
> >
> > Take the `id` of the team whose `key` or `name` you want. In the dialog, **Enter a team ID instead** swaps the picker for a plain text field that accepts it.
> >
> > > [!TIP]
> > >
> > > Linear personal API keys go in the `Authorization` header **without** a `Bearer` prefix. If the command above returns an authentication error, check you have not added one.

> [tab] Webhook
>
> You need an endpoint URL, and optionally a signing secret.
>
> **1. Endpoint URL**
>
> An `http` or `https` URL Ankra can POST to from the public internet, for example `https://example.com/ankra-tickets`. It should answer within 30 seconds and return any 2xx status. Anything from 300 upwards counts as a failed delivery, and the response body is ignored. Redirects are followed up to five hops and must stay on `http` or `https`.
>
> **2. Signing secret (optional but recommended)**
>
> Any high-entropy string. Generate one locally:
>
> ```bash theme={null}
> openssl rand -hex 32
> ```
>
> Keep a copy for your receiver - Ankra never shows it again after you save. When it is set, every delivery carries an HMAC signature your endpoint can verify, as described in [Webhook payloads](#webhook-payloads) below. With no secret, deliveries are unsigned and your endpoint cannot tell they came from Ankra.

## Step 2: Add the connection

**1. Open the ticket sync settings**

Go to **AI** → **Settings** → **Connections** and find the **Ticket sync** card.

**2. Choose Add connection**

The **Add sync connection** dialog opens on a provider picker with the three options. Pick one and the form for that provider appears.

You can change your mind with **Back**, which returns to the picker. Re-picking keeps the name and filters you have typed, and clears the destination and credential fields, because those belong to the provider you just left.

**3. Name the connection**

A label for your own use, up to 200 characters, unique within the organisation. Saving a name that is already taken returns `A sync connection with this name already exists.`

**4. Fill in the destination and credential**

These are the values from step 1.

| Provider | Destination fields | Credential fields |
| - | - | - |
| **Jira** | Jira base URL, Project key, Issue type (optional) | Account email, API token |
| **Linear** | Team, picked from the list your API key can reach | API key |
| **Webhook** | Endpoint URL | Signing secret (optional) |

For Linear, fill the **API key** first: the **Team** picker needs it to ask Linear which teams the key reaches. **Enter a team ID instead** falls back to a plain text field if you already know the id, or if the picker cannot reach Linear.

**5. Set the sync filters**

Tick the ticket **kinds** to sync, or leave them all unticked to sync every kind. Then set the **Minimum priority** and whether **Timeline events** are relayed as comments.

**6. Decide whether it starts enabled**

**Start enabled** is on by default, so live tickets begin syncing as soon as the connection is created. Turn it off if you want to review the settings, or brief the team, before anything lands in the tracker.

**7. Create connection**

Ankra validates the fields, stores the credential in Vault, and adds the connection to the list. The credential is never written to the database and is never returned by the API afterwards.

## Verify it works

The connection row carries a status dot with four states, and it deliberately does not go green until something has actually been delivered:

| Dot | Meaning |
| - | - |
| Grey, "Sync disabled" | The connection is switched off |
| Pale, "No deliveries yet" | Enabled, but nothing has been delivered yet. A wrong credential looks exactly like this until the first ticket fires |
| Green, "Deliveries healthy" | The last delivery succeeded, and the row shows when |
| Red, "Deliveries are failing" | The last delivery failed. The error text from the provider is printed under the row |

To confirm the wiring end to end, change something on a live board ticket that matches the filters - move its status, or leave a comment. The sync loop runs roughly every 30 seconds, so within about a minute the row should show a **Synced** timestamp and the issue should exist in your tracker.

> [!NOTE]
>
> A large first batch drains over several passes rather than all at once: deliveries are throttled to stay under tracker rate limits, and each ticket relays up to 20 timeline events per pass. A busy board that has just been connected takes a few minutes to catch up.

## What lands in Jira and Linear

The issue title is `[T-<number>] <ticket title>`, matching the board's per-organisation ticket number.

The description opens with the classification, the cluster when the ticket names one, and a link back to the board, then the ticket body:

```
Ankra ticket T-412
Kind: incident
Priority: high
Status: triage
Cluster: my-cluster

[Open T-412 on the Ankra board](https://platform.ankra.app/organisation/ai/board/<ticket-id>)

The payments-api deployment has been restarting since 09:14 ...
```

Timeline events then arrive as comments: status changes as `Status: triage → **investigating**`, peer reviews as `Peer review: **approve**`, resolutions as `Resolved (**fixed**)`, comments prefixed with who wrote them. Chat thread messages are not relayed to Jira or Linear, to keep conversation noise out of the tracker. When a ticket's title or priority changes without producing a timeline event, Ankra pushes the updated title onto the external issue.

## Webhook payloads

Webhook connections receive JSON `POST` requests instead of rendered prose. Three event shapes exist, and each one carries the full ticket snapshot, so your consumer never needs a read-back call. A common consumer is a receiver that starts your own agent on each new ticket - see [Start your agent from new tickets](/guides/board-own-agent#start-your-agent-from-new-tickets).

| `X-Ankra-Event` | When |
| - | - |
| `ticket.created` | First delivery for a ticket on this connection |
| `ticket.event` | One timeline event |
| `ticket.updated` | A metadata-only change, such as a title or priority edit that appended no timeline event |

Every request carries these headers:

* `X-Ankra-Event` - the event name above
* `X-Ankra-Delivery` - a unique id for this delivery attempt
* `X-Ankra-Signature` - `sha256=<hex>`, present only when the connection stores a signing secret

A `ticket.created` body:

```json theme={null}
{
  "event": "ticket.created",
  "ticket": {
    "id": "3f6c2b1e-0a94-4a3d-9f0b-2c7d5e8a1b44",
    "ticket_number": 412,
    "title": "CrashLoopBackOff in payments-api",
    "body": "The payments-api deployment has been restarting since 09:14 ...",
    "kind": "incident",
    "status": "triage",
    "priority": "high",
    "cluster_name": "my-cluster",
    "board_url": "https://platform.ankra.app/organisation/ai/board/3f6c2b1e-0a94-4a3d-9f0b-2c7d5e8a1b44",
    "organisation_id": "8c1d0f2a-55b7-4e19-9c3a-6d2f8b7e4a10"
  }
}
```

A `ticket.event` body adds the event alongside the same snapshot:

```json theme={null}
{
  "event": "ticket.event",
  "ticket": { "id": "3f6c2b1e-0a94-4a3d-9f0b-2c7d5e8a1b44", "ticket_number": 412, "...": "..." },
  "ticket_event": {
    "sequence": 7,
    "event_type": "status_change",
    "author_kind": "agent",
    "author_name": "Investigator",
    "body": "",
    "payload": { "from_status": "triage", "to_status": "investigating" }
  }
}
```

`ticket.updated` has the same shape as `ticket.created` with a different `event` value.

Field vocabularies:

* `kind` - `incident`, `insight`, `gap`, `automation`, `request`, `chore`
* `priority` - `urgent`, `high`, `medium`, `low`
* `status` - `triage`, `investigating`, `planning`, `awaiting_review`, `awaiting_approval`, `executing`, `verifying`, `done`, `blocked`, `cancelled`
* `event_type` - `comment`, `status_change`, `assignment`, `plan_draft`, `review`, `session_linked`, `workspace_linked`, `link_added`, `thread_message`, `resolution`, `run_outcome`
* `author_kind` - `agent`, `user`, or the board itself
* `payload` - the raw members of that event type, such as `from_status` and `to_status` on a status change, `verdict` on a review, `resolution` on a resolution

> [!NOTE]
>
> Webhook consumers receive **every** timeline event, including the `thread_message` chat echoes that the Jira and Linear connectors skip. `sequence` is monotonic per ticket, so use it to order and de-duplicate.

### Verifying the signature

The signature is the hex HMAC-SHA256 of the **raw request body** using your signing secret, prefixed with `sha256=`. Compute it over the bytes as received, before any JSON parsing or re-serialisation.

```javascript Node.js theme={null}
import crypto from 'node:crypto'

function isFromAnkra(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const received = Buffer.from(signatureHeader ?? '')
  const computed = Buffer.from(expected)
  return received.length === computed.length && crypto.timingSafeEqual(received, computed)
}
```

```python Python theme={null}
import hashlib
import hmac

def is_from_ankra(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")
```

## Manage a connection

* **Disable** - the switch on the row stops deliveries without losing the configuration or the cursor. Re-enabling resumes from where it stopped, and anything that changed in the meantime is delivered then.
* **Edit** - the pencil opens the same dialog with the provider locked, since a connection cannot change provider. Create a second connection instead.
* **Rotate a credential** - open **Edit**, fill in the credential fields, and save. Leaving every credential field blank keeps the stored one; filling them in replaces it wholesale. A partly filled credential is refused, because the replacement is all or nothing.
* **Retry a failing connection** - saving a failing connection again clears its failure state and retries immediately, rather than waiting out the normal cadence.
* **Delete** - the bin removes the connection and its stored credential.

> [!WARNING]
>
> Deleting a connection stops the sync and cannot be undone. External issues that were already created are left exactly as they are in Jira or Linear - Ankra does not close or delete them. Adding the connection back later starts a fresh cursor and files new issues for the tickets that are live at that moment.

## Troubleshooting

| What you see | What it means |
| - | - |
| `Only organisation admins can manage ticket sync connections.` | Your role can read the list but not change it. Ask an organisation admin. |
| `A sync connection with this name already exists.` | Names are unique per organisation. Pick a different one. |
| **No credential** badge on the row | The connection has no stored credential and its provider needs one, so it cannot deliver. Open **Edit** and add it. |
| Row stays on "No deliveries yet" | Nothing has matched the filters yet, or nothing has changed. Check the kinds and the minimum priority, then touch a live ticket that qualifies. |
| `Jira API error 401` | The account email and API token do not match, or the token was revoked. Regenerate the token and rotate it. |
| `Jira API error 403` | The account authenticates but lacks a project permission. Check Browse Projects, Create Issues, Add Comments, and Edit Issues on that project. |
| `Jira API error 400` with an `issuetype` message | The issue type name does not exist in that project's scheme. Use the exact name Jira shows, or clear the field to fall back to `Task`. |
| `Linear API GraphQL errors` mentioning the team | The stored team is not one this key can see. Open **Edit**, choose **Load teams**, and pick the team again with the current key. |
| `Linear API error 400` or `401` | The API key is wrong or was revoked. Note that Linear personal keys carry no `Bearer` prefix. |
| `The linear provider rejected this credential.` when loading teams | Linear refused the key itself. Check it was pasted whole, starts with `lin_api_`, and has not been revoked. |
| **Load teams** is greyed out | The API key field is still empty. The picker has nothing to ask Linear with until it is filled. |
| **Load teams** returns no teams | The key authenticated but reaches no team - it was created by a Linear user without team access. Create the key from an account that is a member of the target team. |
| `webhook delivery returned status <code>` | Your endpoint answered with a status of 300 or above, which Ankra treats as a failed delivery. It is retried on the next pass. |
| `ticket sync destination <address> is not publicly routable` | The destination resolves to a private, loopback, or link-local address. Expose it on the public internet, or use a provider that is. |
| `webhook delivery failed: ... timeout` | Your endpoint did not answer within the 30 second budget. Acknowledge fast and process asynchronously. |

Failures are retried automatically on the next pass. A failing connection does not block the others, and one failing ticket does not starve the queue behind it.

## Related pages

* [AI Board](/platform/ai-board) - ticket kinds, statuses, priorities, and the plan approval flow
* [Work the AI board with your own agent](/guides/board-own-agent) - act on tickets over MCP, the way back in that sync does not provide
* [AI Connections](/platform/ai-connections) - the rest of the Connections settings page
* [Webhooks](/guides/webhooks) - alert and platform event destinations, a separate system from ticket sync
* [Roles and Access](/guides/roles-and-access) - who counts as an organisation admin


# UpCloud Kubernetes (UKS)
Source: https://docs.ankra.ai/guides/uks-clusters

Provision, import, and operate UpCloud Managed Kubernetes (UKS) clusters with Ankra - live pricing, node pools, upgrades, GitOps, and AI-assisted operations.

[UpCloud Managed Kubernetes (UKS)](https://upcloud.com/products/managed-kubernetes) is UpCloud's managed Kubernetes service, hosted in UpCloud's European and global zones. UpCloud runs the control plane; Ankra provisions the cluster, then manages everything on top - node pools, Kubernetes upgrades, addons, stacks, GitOps, and AI-assisted operations.

This page covers UKS specifically. For the shared concepts across all managed providers - live options, discovery/import, and day-2 API patterns - see [Managed Kubernetes](/guides/managed-kubernetes).

## Why UKS with Ankra

* **Live pricing and options** - zones, Kubernetes versions, and node plans are fetched live with your UpCloud token, with a monthly cost summary as you build the cluster.
* **Development and production control-plane plans** - choose the UKS control-plane plan that fits the workload.
* **Full day-2 from the CLI, portal, or API** - add and scale node pools, upgrade Kubernetes, and manage addons and stacks the same way as any Ankra cluster.

## Prerequisites

An **UpCloud API credential** (API access for an UpCloud subaccount), stored in Ankra. See [UpCloud API Credentials](/platform/credentials/upcloud).

GitOps is optional: connect a repository at creation and Ankra commits the cluster's stack definitions to Git.

## Creating a UKS cluster

> [tab] Portal
>
> **1. Create Cluster**
>
> Go to **Clusters** → **Create Cluster** and pick UpCloud's **Cloud Managed** action.
>
> **2. Credential & Zone**
>
> Select the UpCloud credential and a zone (for example `de-fra1`). Zones load live from UpCloud.
>
> **3. Node Pools**
>
> Define one or more worker pools: name, node plan (with live pricing), count, labels, and taints.
>
> **4. Kubernetes**
>
> Pick a Kubernetes version or keep the default, and select the control-plane plan (development or production).
>
> **5. GitOps (optional) & Create**
>
> Optionally connect a Git repository, then create. Ankra runs UpCloud preflight checks, provisions the cluster, retrieves the kubeconfig, and installs the Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra cluster managed create \
>   --provider uks \
>   --name my-uks-cluster \
>   --credential-id <upcloud-credential-id> \
>   --location de-fra1 \
>   --node-pool-name workers \
>   --node-pool-size K8S-2xCPU-4GB \
>   --node-pool-count 2
> ```
>
> The control-plane plan is set from the portal or the API.

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/org/clusters/managed/uks \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-uks-cluster",
>     "credential_id": "<upcloud-credential-id>",
>     "location": "de-fra1",
>     "node_pools": [
>       {"name": "workers", "size": "K8S-2xCPU-4GB", "count": 2}
>     ],
>     "cluster_plan": "production"
>   }'
> ```

### UKS options

| Field | Description |
| - | - |
| `cluster_plan` | Control-plane plan (`development` or `production`) |
| `gpu_plan.storage_size` | Storage size for GPU node pools |

## Verify

The create progress view follows the control plane, the node pools, kubeconfig retrieval and the Ankra Agent install. The cluster shows **Online** once the agent has connected. Then point `kubectl` at it through Ankra - this needs a [Cluster Access](/guides/cluster-access) grant - and check that every node is `Ready`:

```bash theme={null}
ankra cluster kubeconfig add <cluster-name> --use
kubectl get nodes
```

See [Accessing Clusters with kubectl](/guides/kubeconfig).

## Day-2 operations

Node pools, upgrades, and deletion work from the CLI, portal, or API. The CLI examples use `--provider uks`:

```bash theme={null}
# scale a pool to a fixed count
ankra cluster managed node-pool scale <cluster_id> workers --provider uks --count 5

# upgrade the cluster
ankra cluster managed upgrade <cluster_id> --provider uks --version 1.33

# delete the cluster
ankra cluster managed delete <cluster_id> --provider uks
```

> [!NOTE]
>
> Ankra does not manage node-pool autoscaling on UKS: a pool you scale through Ankra is set to a fixed count, and Ankra never changes that count on its own. To autoscale a pool, run UpCloud's Cluster Autoscaler in the cluster and mark the pool as [externally managed](/guides/managed-kubernetes#externally-managed-node-pools) so nothing in Ankra can override the count the autoscaler reaches. See [Managed Kubernetes - day-2 operations](/guides/managed-kubernetes#day-2-operations) for the shared mechanics.

## Importing an existing UKS cluster

Already running UKS? Discover clusters at UpCloud and adopt them into Ankra without touching them. Discovery and import run from the portal, the CLI (`ankra cluster managed discover|import --provider uks`) or the API - see [Managed Kubernetes - importing existing clusters](/guides/managed-kubernetes#importing-existing-clusters).

## Related

* [Managed Kubernetes overview](/guides/managed-kubernetes)
* [UpCloud API Credentials](/platform/credentials/upcloud)
* [Cluster settings](/platform/cluster-settings)


# UpCloud Clusters
Source: https://docs.ankra.ai/guides/upcloud-clusters

Create a Kubernetes cluster on servers in your own UpCloud account, with Ankra installing and operating Kubernetes, ingress, TLS and DNS.

Choose UpCloud when you want Kubernetes on UpCloud servers in an account you own, with private nodes behind a managed NAT gateway and, if you need it, a cluster stretched across several UpCloud zones. Ankra creates the router, private network, NAT gateway, bastion and servers, installs Kubernetes and the UpCloud cloud integration, and then operates the cluster for you - this is an **Ankra Managed** cluster. UpCloud bills you directly for the servers.

## Before you start

* An **UpCloud API token** with permission to manage servers, networking, storage and Kubernetes, stored as an [UpCloud credential](/platform/credentials/upcloud).
* An **SSH key credential** - your own public key, or one Ankra generates. See [SSH Key Credentials](/platform/credentials/ssh-key).
* Room in your account's limits for the servers, networks, routers and IP addresses. Check them in the [UpCloud Control Panel](https://hub.upcloud.com/); UpCloud support raises them.

## Create the cluster

> [tab] Dashboard
>
> **1. Open the create dialog**
>
> Go to **Clusters**, click **Create cluster** and pick **UpCloud** under **Ankra Managed**.
>
> **2. Credential & Zone**
>
> Pick the UpCloud credential and the SSH key (or add either inline), and the zone, for example Helsinki, Frankfurt, Chicago or Amsterdam.
>
> **3. Network & Compute**
>
> Keep or change the private network range, then pick the bastion plan, the control plane count and plan, and the worker plan and count, with optional autoscaling bounds. The wizard shows each plan's vCPUs, RAM and monthly price. Add more node groups once the cluster is running.
>
> **4. Kubernetes**
>
> Keep **kubeadm** (the default, with Cilium) or pick **k3s**, and optionally the version. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) for the CNI and etcd options.
>
> **5. GitOps**
>
> Optionally connect a Git repository; Ankra commits the cluster's stacks to it. Two checkboxes are on by default:
>
> * **Include Networking Stack** - Traefik, cert-manager and a Let's Encrypt ClusterIssuer, with Traefik behind an UpCloud load balancer.
> * **Include Public DNS** - a delegated subdomain on `ankra.cc` with external-dns wired, so an ingress hostname under it gets its DNS record and TLS certificate automatically.
>
> **6. Details**
>
> Name the cluster, set its environment, and click **Create cluster**. A progress view follows the router, network, gateway, bastion, servers, Kubernetes installation and Ankra Agent.

> [tab] CLI
>
> ```bash theme={null}
> ankra credentials upcloud create --name my-upcloud-token   # prompts for the token
> ankra credentials upcloud ssh-key create --name my-ssh-key --generate
>
> ankra cluster upcloud create \
>   --name my-cluster \
>   --credential-id <upcloud-credential-id> \
>   --ssh-key-credential-id <ssh-key-credential-id> \
>   --zone fi-hel1 \
>   --control-plane-count 1 \
>   --control-plane-plan 2xCPU-4GB \
>   --worker-count 2 \
>   --worker-plan 4xCPU-8GB
> ```
>
> Left unset, `--network-ip-range` is picked from ranges free in your account. `--distribution k3s`, `--etcd-topology external`, `--include-networking=false` and the `--gitops-*` flags cover the other choices; `--zones` and `--network-mode` are for [multi-zone clusters](#multi-zone-clusters).

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://platform.ankra.app/api/v1/clusters/upcloud \
>   -H "Authorization: Bearer $ANKRA_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "my-cluster",
>     "credential_id": "<upcloud-credential-id>",
>     "ssh_key_credential_id": "<ssh-key-credential-id>",
>     "zone": "fi-hel1",
>     "control_plane_count": 1,
>     "control_plane_plan": "2xCPU-4GB",
>     "node_groups": [
>       {"name": "default", "instance_type": "4xCPU-8GB", "count": 2}
>     ],
>     "include_networking": true,
>     "include_dns": true
>   }'
> ```
>
> Every field, the zone list and the plans are in the [UpCloud Reference](/reference/upcloud).

## Verify

1. The cluster moves from **Provisioning** to **Online** in the clusters list once the Ankra Agent has connected.
2. Point `kubectl` at it through Ankra (this needs a [Cluster Access](/guides/cluster-access) grant) and check the nodes:

   ```bash theme={null}
   ankra cluster kubeconfig add my-cluster --use
   kubectl get nodes
   ```

   Every control plane and worker should be `Ready`. See [Accessing Clusters with kubectl](/guides/kubeconfig).

## What Ankra created in your account

* **An SDN router and a private network** with DHCP handing out the default route. Nodes have no public interface.
* **A managed NAT gateway** on the router - the egress path for all node traffic.
* **A bastion** - the only server with a public IP. It is an SSH jump host only: Ankra reaches the nodes through it to provision, upgrade and reconcile, and no workload or egress traffic flows through it.
* **Control plane and worker servers**, and your SSH key on every server.
* **The upcloud-cloud-provider stack** - the UpCloud cloud controller manager and CSI driver, for `LoadBalancer` Services and persistent storage, using your credential.

On a multi-zone cluster, every additional zone gets its own router, private network and NAT gateway, and the nodes are joined by a WireGuard mesh. The [UpCloud Reference](/reference/upcloud#architecture) has the diagram.

## UpCloud specifics

* **Plan changes go one way.** A node group moves to a larger plan only; each node is powered off, resized and powered on, with brief downtime for its workloads. For smaller nodes, create a new group and delete the old one.
* **Stop.** A stop releases the node servers, the bastion and the NAT gateway, and keeps the networking definition and SSH keys. The CSI storage volumes are kept and billed while the cluster is stopped.
* **Terminate** deletes the servers, networks, routers, gateways and SSH keys. The storage volumes Ankra deletes, once you accept it, are exactly the ones it recorded for this cluster - never other disks in the account.

### Multi-zone clusters

UpCloud has no multi-zone region: every private SDN network, router and managed load balancer lives in one zone, so a cluster is single-zone by construction. Ankra can stretch a cluster across a **zone pool** instead - one private network and NAT gateway per zone, the nodes joined by a platform-managed kernel WireGuard mesh over UpCloud's account-wide utility network, and Kubernetes advertising the overlay address on every node. Losing a zone then costs capacity, not the cluster.

> [!NOTE]
>
> Multi-zone placement needs the `kubeadm` distribution (the default).

Two rules shape everything below. A pool has **at least three zones and three control planes** - one per zone - so etcd keeps quorum when any one zone is lost; a two-zone pool is refused. And the mesh is decided at create: a cluster created without it cannot be stretched later, so a single-zone cluster that may grow is created with `network_mode: wireguard_mesh`.

#### Create a cluster across zones

`zone` stays the primary zone - bastion, first control plane and default network - and must be in `zones`. Control planes spread one per zone; workers spread per node group unless a group is pinned.

```bash CLI theme={null}
ankra cluster upcloud create \
  --name my-cluster \
  --credential-id <upcloud-credential-id> \
  --ssh-key-credential-id <ssh-key-credential-id> \
  --zone fi-hel1 \
  --zones fi-hel1,fi-hel2,se-sto1 \
  --control-plane-count 3 \
  --control-plane-plan 2xCPU-4GB \
  --worker-count 3 \
  --worker-plan 4xCPU-8GB
```

```bash cURL theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/upcloud \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<upcloud-credential-id>",
    "ssh_key_credential_id": "<ssh-key-credential-id>",
    "zone": "fi-hel1",
    "zones": ["fi-hel1", "fi-hel2", "se-sto1"],
    "control_plane_count": 3,
    "control_plane_plan": "2xCPU-4GB",
    "worker_count": 3,
    "worker_plan": "4xCPU-8GB",
    "distribution": "kubeadm"
  }'
```

`network_mode` is derived - `wireguard_mesh` for a pool, `private_network` otherwise - and can be set to `wireguard_mesh` on a single-zone cluster to make it mesh-capable:

```bash theme={null}
ankra cluster upcloud create --name my-cluster --zone fi-hel1 --network-mode wireguard_mesh \
  --credential-id <upcloud-credential-id> --ssh-key-credential-id <ssh-key-credential-id>
```

#### Grow the pool

Zones can be added to a `wireguard_mesh` cluster, never removed. Pass the full desired pool, primary zone first; every new zone gets its router, private network and NAT gateway, and later node groups spread across the grown pool.

```bash CLI theme={null}
ankra cluster upcloud zones <cluster> --zones fi-hel1,fi-hel2,se-sto1,de-fra1
```

```bash cURL theme={null}
curl -X PUT https://platform.ankra.app/api/v1/clusters/upcloud/<cluster_id>/zones \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zones": ["fi-hel1", "fi-hel2", "se-sto1", "de-fra1"]}'
```

#### Pin a node group to one zone

Pin the group that runs zonal storage: an UpCloud volume cannot attach from another zone.

```bash theme={null}
ankra cluster node-group add <cluster> \
  --name database-sto \
  --instance-type 4xCPU-8GB \
  --count 1 \
  --zone se-sto1
```

Day-2 growth follows the stored pool: node group add, node group scale, worker scale, autoscaling and control plane growth balance new servers around where the existing ones are. A group whose nodes all share one zone is treated as pinned and grows there; a spread group keeps spreading. Control planes cannot be scaled below three on a multi-zone pool. `ankra cluster node-group list` ends each line with `zones=` and the zones the group's nodes were placed in (`zones` on the node-group listing API).

#### Node topology labels

Every node carries `topology.kubernetes.io/zone` (the UpCloud zone, e.g. `fi-hel2`) and `topology.kubernetes.io/region` (the zone without its index, e.g. `fi-hel`), so `topologySpreadConstraints` and zone-aware scheduling work without extra configuration.

#### Node addressing on a meshed cluster

Every node advertises its **overlay address** to Kubernetes, so that is what `kubectl get nodes -o wide` reports as `INTERNAL-IP` - not the node's private SDN address. Overlay addresses are allocated per cluster from a range Ankra manages (`172.30.0.0/16` by default) and stay stable for the life of a node, so anything keyed on a node IP - monitoring targets, `NO_PROXY` lists, allow-lists - should use the overlay address:

```console theme={null}
$ kubectl get nodes -o wide
NAME             STATUS   INTERNAL-IP   ...
my-cluster-cp-0  Ready    172.30.0.4    ...   # fi-hel1
my-cluster-cp-1  Ready    172.30.0.2    ...   # fi-hel2
my-cluster-cp-2  Ready    172.30.0.3    ...   # se-sto1
```

Each zone in the pool also takes its own consecutive `/24` from the cluster's private range: with the default range, `fi-hel1` gets `10.166.78.0/24`, `fi-hel2` `10.166.79.0/24`, and so on. Pick `network_ip_range` with room for every zone you expect to add.

#### `LoadBalancer` Services on a meshed cluster

A meshed cluster advertises each node's overlay address as its Kubernetes `InternalIP`. An UpCloud load balancer is not part of the WireGuard mesh, so a backend registered at that address would be unreachable.

Ankra runs a cloud controller manager on meshed clusters that takes each backend member's address from the node's address on the private network the load balancer is attached to, rather than from the `InternalIP`. That is the one address a load balancer can always reach, so `LoadBalancer` Services - including the Traefik ingress the networking stack installs - work normally. You do not need to configure anything.

> [!NOTE]
>
> This is worth knowing if you compare a meshed cluster against a stock UpCloud CCM: the address behaviour is a deliberate difference, and the controller runs with its node controller disabled, because the overlay address it would otherwise reject is the whole point of a meshed cluster. Ankra applies the `topology.kubernetes.io/*` and `node.kubernetes.io/instance-type` labels itself instead.

#### What stays in the primary zone

UpCloud block storage is zone-local, and the cluster's CSI is scoped to the primary zone:

* `PersistentVolumeClaim`s are provisioned in the primary zone. Run stateful workloads there, or use replicated storage such as Longhorn for the other zones.
* The bastion is in the primary zone: if that zone is lost, workloads keep running in the others, but provisioning and node management pause until it returns.
* The cloud controller manager cannot match a node's overlay address to an address UpCloud reports for the server, so it does not maintain node addresses on a meshed cluster. Ankra runs the CCM with its node controller disabled there and stamps the `topology.kubernetes.io/*` and `node.kubernetes.io/instance-type` labels itself; nodes register, stay `Ready` and keep their `providerID`.

Pod MTU is 1370 inside the mesh (WireGuard and VXLAN overheads), and Cilium's own WireGuard encryption is refused on a meshed cluster - the overlay already encrypts every node-to-node byte.

## Operate it

Day-2 tasks work the same way on every Ankra Managed provider, with the CLI name `upcloud`:

* [Node groups](/guides/operate-ankra-managed-clusters#node-groups) and [legacy worker scaling](/guides/operate-ankra-managed-clusters#legacy-worker-scaling)
* [Control plane](/guides/operate-ankra-managed-clusters#control-plane)
* [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [the bastion](/guides/operate-ankra-managed-clusters#bastion)
* [SSH access and keys](/guides/operate-ankra-managed-clusters#ssh-access-and-keys)
* [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes)
* [Stop and start](/guides/operate-ankra-managed-clusters#stop-and-start)
* [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

## Troubleshooting

| Issue | Solution |
| - | - |
| Cluster stuck in provisioning | Check the token's permissions and the account's limits (servers, networks, routers, IP addresses) in the [UpCloud Control Panel](https://hub.upcloud.com/) |
| Invalid API token | Create a new token and [rotate the credential](/platform/credentials/upcloud) |
| Server plan unavailable | Try another zone or plan |
| Cannot scale workers | Ensure the cluster is online and no operation is running |
| `zones` or `network_mode` refused with "is not supported for upcloud clusters" | Multi-zone placement is switched off for your organisation - [contact support](/platform/support) |


# Alert on Manifest Failures
Source: https://docs.ankra.ai/guides/webhook-integrations

Set up Slack notifications when manifests fail to deploy or don't reach a healthy state

> [!NOTE]
>
> This guide walks you through setting up alerts for manifest deployment failures with Slack notifications. You'll create a Slack webhook and configure an alert rule to monitor specific clusters.

## What You'll Build

By the end of this guide, you'll have:

* A Slack webhook integration connected to Ankra
* An alert rule that triggers when manifest jobs fail
* Notifications sent to your Slack channel when deployments fail
* Automatic AI-powered root cause analysis for every failure

```mermaid theme={null}
flowchart LR
    A[Manifest Deploy] --> B{Job Status}
    B -->|Failed| C[Alert Triggered]
    C --> D[Slack Notification]
    C --> F[AI Analysis Job]
    F --> G[AI Incident Created]
    B -->|Success| E[No Alert]
```

***

## Prerequisites

Before you begin, ensure you have:

* An Ankra account with access to your organisation's alerts
* Admin access to a Slack workspace (to create an app)
* At least one cluster with manifests deployed

***

## Part 1: Create a Slack Webhook

### Step 1: Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App**
3. Choose **From scratch**
4. Enter the app details:
   * **App Name:** `Ankra Alerts`
   * **Workspace:** Select your workspace
5. Click **Create App**

### Step 2: Enable Incoming Webhooks

1. In your app settings, click **Incoming Webhooks** in the left sidebar
2. Toggle **Activate Incoming Webhooks** to **On**
3. Click **Add New Webhook to Workspace**
4. Select the channel for alerts (e.g., `#deployments` or `#alerts`)
5. Click **Allow**

### Step 3: Copy the Webhook URL

After authorization, copy your webhook URL. It will look like:

```
https://hooks.slack.com/services/TXXXXX/BXXXXX/your-webhook-token
```

> [!WARNING]
>
> Keep this URL secret. Anyone with it can post to your channel.

### Step 4: Create the Webhook in Ankra

1. In Ankra, navigate to **Alerts** in the sidebar
2. Click the **Integrations** tab
3. Click **Create Webhook**
4. Fill in the details:

| Field | Value |
| - | - |
| **Name** | `Slack Deployment Alerts` |
| **URL** | Paste your Slack webhook URL |
| **Description** | Notifications for manifest failures |
| **Template** | Select **Slack** |

5. Click **Create**

### Step 5: Test the Webhook

1. On the webhook detail page, click **Send Test**
2. Check your Slack channel for the test message
3. If it appears, your webhook is ready!

> [!TIP]
>
> The default Slack template includes alert name, severity, resource info, and a link to Ankra. You can customize it later if needed.

***

## Part 2: Create the Alert Rule

Now create an alert rule that monitors manifest deployments on specific clusters.

### Step 1: Start Creating an Alert

1. Go to **Alerts** in Ankra
2. Click the **Alert Rules** tab
3. Click **Create Alert**

### Step 2: Configure Basic Details

In the **Details** step:

| Field | Value |
| - | - |
| **Name** | `Manifest Deployment Failed` |
| **Description** | Alert when manifest jobs fail on production clusters |
| **Enabled** | Toggle **On** |

Click **Next** to continue.

### Step 3: Select Resource Type

In the **Resource** step:

1. **Resource Type:** Select **Cluster Resource**
2. **Cluster Resource Kind:** Select **Manifest**

This tells Ankra to monitor manifest resources specifically.

### Step 4: Select Specific Clusters

Under **Clusters**, select the clusters you want to monitor:

1. Click the cluster dropdown
2. Check the boxes for your target clusters (e.g., `production-cluster`, `staging-cluster`)
3. Only selected clusters will trigger this alert

> [!NOTE]
>
> Leave all clusters unchecked to monitor manifests across your entire organisation.

### Step 5: Configure the Condition

In the **Conditions** section, set up the failure condition:

**Condition 1:**

| Field | Value |
| - | - |
| **Condition Type** | Job Status |
| **Operator** | Equals |
| **Value** | Failed |

This condition triggers when any manifest job enters a `Failed` state.

> [accordion] Optional: Add additional conditions
>
> You can add multiple conditions with AND/OR logic:
>
> **Example: Alert on both failures and timeouts**
>
> * Condition 1: Job Status = Failed
> * **OR**
> * Condition 2: Job Status = Timeout
>
> **Example: Alert only when stuck for a while**
>
> * Condition 1: Job Status = Failed
> * **AND**
> * Condition 2: Stuck in State > 5 minutes

Click **Next** to continue.

### Step 6: Set Severity and Cooldown

In the **Severity** step:

| Field | Value | Description |
| - | - | - |
| **Severity** | `critical` | High priority for deployment failures |
| **Cooldown** | `15 minutes` | Prevent repeated alerts for the same issue |

Click **Next** to continue.

### Step 7: Attach the Slack Webhook

In the **Notifications** step:

1. Under **Webhooks**, find your `Slack Deployment Alerts` webhook
2. Check the box to enable it
3. The alert will now send notifications to Slack when triggered

Click **Create** to save the alert rule.

***

## What Happens When a Manifest Fails

When a manifest deployment fails on one of your selected clusters:

```mermaid theme={null}
sequenceDiagram
    participant M as Manifest
    participant A as Alert Engine
    participant W as Webhook
    participant AI as AI Analysis

    M->>A: Job Status = Failed
    A->>A: Evaluate conditions
    A->>W: Send notification
    W->>W: POST to Slack
    A->>AI: Create AI Analysis Resource
    AI->>AI: Schedule Analysis Job
    AI->>AI: Collect pods, events, logs
    AI->>AI: Generate root cause analysis
    AI->>A: AI Incident ready
```

### Step-by-Step Breakdown

1. **Ankra detects the failure** - Job status changes to `Failed`
2. **Alert rule evaluates** - Condition matches (Job Status = Failed)
3. **Cooldown check** - If no recent alert for this resource, proceed
4. **Webhook fires** - Slack receives the notification immediately
5. **AI Analysis Resource created** - Ankra creates a tracking resource for the analysis
6. **AI Analysis Job scheduled** - A background job starts collecting data
7. **Data collection** - The job gathers:
   * Pod status and container states
   * Kubernetes events (warnings, errors)
   * Container logs (last 50 lines)
   * Job results and error messages
8. **AI Incident generated** - Ankra's AI analyzes the data and produces:
   * Root cause identification
   * Severity assessment
   * Recommended actions
   * Links to affected resources

> [!NOTE]
>
> **View AI Incidents:** Open **AI** → **Inbox** to see all generated analyses. Each incident includes the AI's findings, affected resources, and suggested next steps. You can also ask follow-up questions directly in the incident view.

### Example Slack Notification

Your Slack channel will receive a message like:

```
🔴 Alert: Manifest Deployment Failed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Severity: critical
Resource: nginx-config (Manifest)
Cluster: production-cluster

Triggered at: Dec 15, 2024, 2:34 PM

🔗 View in Ankra
```

***

## Verifying Your Setup

Test your configuration end-to-end:

1. **Create a test manifest** with an intentional error (e.g., invalid YAML)
2. **Deploy the manifest** to one of your monitored clusters
3. **Watch for the failure** in the Operations page
4. **Check Slack** for the alert notification
5. **Review the AI Incident** for root cause analysis

***

## Additional Alert Scenarios

> [accordion] Alert on manifest state changes
>
> To alert when manifests enter an unhealthy state (not just job failures):
>
> | Field | Value |
> | - | - |
> | **Condition Type** | Resource State |
> | **Operator** | Equals |
> | **Value** | Down |
>
> This triggers when a manifest's health status becomes "Down".

> [accordion] Alert on stuck deployments
>
> To alert when manifests are stuck in a deploying state:
>
> | Field | Value |
> | - | - |
> | **Condition Type** | Stuck in State (duration) |
> | **Operator** | Greater than |
> | **Value** | 10 (minutes) |
>
> This triggers when a manifest has been in a transitional state for too long.

> [accordion] Alert on repeated failures
>
> To alert only after multiple failures:
>
> | Field | Value |
> | - | - |
> | **Condition Type** | Failed Job Count |
> | **Operator** | Greater than or equal |
> | **Value** | 3 |
>
> This triggers after 3 or more failed jobs on the same manifest.

***

## Troubleshooting

### Alert not triggering

* Verify the alert rule is **Enabled**
* Check that the correct **clusters** are selected
* Ensure the manifest is in a cluster you're monitoring
* Confirm the **condition** matches (Job Status = Failed)

### Slack message not appearing

* Test the webhook using the **Send Test** button
* Verify the webhook URL is correct
* Check that the Slack app still has channel access
* Look for errors in the webhook's delivery history

### Too many alerts

* Increase the **cooldown period** (e.g., 30 minutes)
* Add more specific conditions to filter alerts
* Consider monitoring only production clusters

***

## Related

* [Alerts](/guides/alerts) - Full alert rule configuration reference
* [Webhooks](/guides/webhooks) - Template variables and custom payloads
* [Alert-triggered analysis](/platform/ai-insights#alert-triggered-analysis) - the AI analysis attached to every firing
* [Operations](/platform/operations) - View job history and logs

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.


# Webhooks
Source: https://docs.ankra.ai/guides/webhooks

Send alert notifications to any service via customizable webhooks

> [!NOTE]
>
> Webhooks allow you to send alert notifications to any service that accepts HTTP POST requests - Slack, Microsoft Teams, Discord, PagerDuty, Opsgenie, Datadog, or your own custom endpoints.

## What are Webhooks?

Webhooks are HTTP endpoints that receive alert notifications when your alert rules trigger. Ankra sends a POST request with alert details to your configured URL, allowing you to integrate with virtually any notification or incident management system.

Key features:

* **Universal compatibility** - Works with any service accepting webhooks
* **Custom payloads** - Full control over the JSON structure sent to your endpoint
* **Template variables** - Dynamic values like alert name, severity, and resource details
* **Pre-built templates** - Quick setup for popular services

### How Webhooks Work

```mermaid theme={null}
sequenceDiagram
    participant Alert as Alert Rule
    participant Ankra as Ankra Platform
    participant Webhook as Webhook Endpoint
    participant Service as External Service
    
    Alert->>Ankra: Condition triggered
    Ankra->>Ankra: Apply template variables
    Ankra->>Webhook: HTTP POST with JSON payload
    Webhook->>Service: Process notification
    Service-->>Ankra: 200 OK
```

***

## Home channel

Set an organisation **home channel** and Ankra starts the conversation itself. Whenever something important happens - a deployment or reconcile failure, an agent going offline, a new severe CVE - and **no routing rule matches it**, Ankra posts to the home channel. It is the default destination, so your team hears about important events before anyone wires up a single rule.

**1. Connect Slack**

Connect a Slack workspace to Ankra from the **Slack integration** in your organisation settings, and invite the Ankra bot to any private channel you want to use.

**2. Pick the home channel**

Open **AI** → **Settings** → **Workspaces**, find **Ankra's home**, choose a Slack channel, and save.

> [!NOTE]
>
> Only **critical** and **warning** events reach the home channel; informational events stay in the in-app inbox. The home is a fallback - when a routing rule already matches an event it goes there instead, and the home is not double-notified. Alerts that already post to their own destinations are left to those destinations.

***

## Creating a Webhook

**1. Navigate to Webhooks**

Go to **Alerts → Integrations → Webhooks** and click **Create Webhook**.

**2. Configure Basic Settings**

* **Webhook Name:** A descriptive name (e.g., "PagerDuty Production")
* **Webhook URL:** The endpoint URL provided by your integration service
* **Description:** Optional notes about this webhook's purpose
* **Enabled:** Toggle to enable/disable the webhook

For **Slack** and **Microsoft Teams** you can skip the URL entirely: once the Ankra app is installed in your Slack workspace, or the Ankra AI bot has been added to a Microsoft Teams team, the URL field is replaced by a **channel picker** and the Ankra bot posts the alerts itself. Teams channels are listed as *Team / Channel* across every team the bot is in - add the bot to a team first for its channels to appear. See [Connecting Microsoft Teams](/platform/ai-connections#connecting-microsoft-teams) for installing the bot.

**3. Select or Create Template**

Choose a pre-built template for common services, or create a custom JSON payload:

* **Slack** - Rich message blocks with buttons
* **Microsoft Teams** - Adaptive card format
* **Discord** - Embed format with fields
* **Custom JSON** - Any JSON structure for other services

**4. Save and Test**

Save the webhook, then use the **Test** button to send a sample notification and verify your configuration.

***

## Template Variables

Use these variables in your custom templates. They are replaced with actual values when the notification is delivered.

One destination stores one template, and that template renders **every** notification it receives - alert firings, alert resolutions, and the operational notifications a routing rule sends it. The tables below mark which of those a variable carries a value for.

### Notification

| Variable | Description | Example |
| - | - | - |
| `{{kind}}` | Notification kind identifier | "execution\_failed" |
| `{{kind_label}}` | Human label for the kind | "Operation failed" |
| `{{title}}` | Notification headline | "Deployment failed for registry\_pull\_secret 'harbor-pull'" |
| `{{body}}` | Notification detail text | "Error: chart not found" |
| `{{message}}` | One-line summary - the title, or the alert name for alert firings | "Production Down Alert" |
| `{{name}}` | Destination name | "infra-channel" |
| `{{webhook_name}}` | Destination name, same value as `{{name}}` | "infra-channel" |
| `{{notification_type}}` | "triggered" or "resolved" | "triggered" |
| `{{notification_id}}` | Identifier of the notification | "abc123-def456" |
| `{{recurrence_count}}` | How many times this notification has recurred | "4" |
| `{{source}}` | Delivery pipeline | "alert\_trigger", "cluster\_notification" |
| `{{data}}` | Producer detail object for the kind, spliced in as JSON | `{"execution_id": "..."}` |
| `{{route_hint}}` | In-app deep link descriptor, spliced in as JSON | `{"name": "ORG_OPERATIONS_DETAIL"}` |

### Alert Information

Alert firings and resolutions carry all of these. Operational notifications carry `{{severity}}` and its two presentation values; the rest are empty for them, except a firing routed by a routing rule, which also carries `{{condition_type}}` and `{{trigger_value}}`.

| Variable | Description | Example |
| - | - | - |
| `{{alert_name}}` | Name of the alert, falling back to the rule name and then the notification title | "Production Down Alert" |
| `{{alert_id}}` | Unique alert identifier | "abc123-def456" |
| `{{rule_id}}` | Alert rule identifier | "def456-abc123" |
| `{{rule_name}}` | Alert rule name, or the kind label for operational notifications | "Cluster state check" |
| `{{trigger_id}}` | Identifier of this firing | "789abc-123def" |
| `{{severity}}` | Alert severity level | "critical", "warning", "info" |
| `{{severity_color}}` | Hex colour for severity | "#d9534f" |
| `{{severity_style}}` | Adaptive Card container style for severity | "attention", "warning", "accent" |
| `{{condition_type}}` | Condition types that fired, comma-separated | "cluster\_state" |
| `{{trigger_value}}` | Observed value that met the condition | "cluster\_state=online" |
| `{{trigger_details}}` | Full evaluation detail object, spliced in as JSON | `{"actual": 91, "threshold": 80}` |
| `{{resource_snapshot}}` | Resource state captured when the alert fired, spliced in as JSON | `{"state": "degraded"}` |
| `{{triggered_at}}` | Human-readable trigger time | "2026-08-22 09:15:04 UTC" |
| `{{triggered_at_iso}}` | ISO 8601 timestamp | "2026-08-22T09:15:04Z" |
| `{{resolved_at}}` | When the alert resolved | "2026-08-22T10:02:11Z" |
| `{{resolved_by}}` | Who resolved the alert | "[sara@example.com](mailto:sara@example.com)" |
| `{{previous_status}}` | Status the alert held before this notification | "triggered" |

### Resource Information

Every notification kind fills what it has. Where a producer records no finer resource kind, `{{resource_type}}` reads as the thing that went wrong - "operation", "resource", "agent", "insight", "gitops repository", "security report". Agent notifications are about the agent on a cluster, so their `{{resource_name}}` is that cluster's name.

| Variable | Description | Example |
| - | - | - |
| `{{resource_name}}` | Name of the affected resource | "nginx-deployment" |
| `{{resource_type}}` | Kind of the affected resource | "addon", "manifest", "deployment" |
| `{{namespace}}` | Kubernetes namespace of the affected resource | "production" |
| `{{job_name}}` | Job or operation the notification is about | "deploy-nginx" |
| `{{cluster_id}}` | Cluster identifier | "abc123-def456" |
| `{{cluster_name}}` | Cluster the notification came from | "production-us-east" |

### Action URLs

| Variable | Description |
| - | - |
| `{{alert_url}}` | Direct link to the firing in Ankra, or to the alerts dashboard when the notification has no firing page |
| `{{acknowledge_url}}` | Signed one-click acknowledge link (safe to put behind a button) |
| `{{dashboard_url}}` | Link to the Ankra dashboard |
| `{{snooze_url}}` | Link to the page the alert can be snoozed from |

### Empty values and fallbacks

No notification kind carries a value for every variable - a cluster-level alert has no job, an agent update has no condition. Two things stop that showing up as a column of blank rows in your card:

* **Empty rows are dropped for you.** After substitution Ankra removes the rows whose whole purpose was to show one value: Adaptive Card `FactSet` facts whose value came out empty (and a `FactSet` left with no facts), empty `TextBlock` entries, Slack `section` fields whose `*Label*` has no value under it, and the `{"name", "value"}` rows a Discord embed or a legacy Teams MessageCard carries. All four built-in presets therefore render correctly for every kind with no editing. Containers, columns and action sets are never removed, and a card is never pruned down to nothing.
* **You can supply your own fallback** with `{{variable|text}}`, for example `{{resource_name|not applicable}}`. The fallback is used both when the variable is unknown and when it resolves empty, so it wins over the row being dropped.

A variable name Ankra does not recognise renders as an empty string rather than as literal `{{...}}` text.

The JSON-valued variables (`{{data}}`, `{{route_hint}}`, `{{trigger_details}}`, `{{resource_snapshot}}`) follow where you put them: written unquoted they splice in as a nested object, and written inside a quoted string they are escaped for you so the payload stays valid JSON.

```json theme={null}
{
  "details": {{trigger_details}},
  "text": "Details: {{trigger_details}}"
}
```

Every other value is escaped for the string it sits in, so a resource name containing a quote or a newline cannot break your template.

***

## Integration Examples

### Slack

Slack webhooks use the Block Kit format for rich messages:

```json theme={null}
{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "🚨 Alert: {{alert_name}}"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Severity:* `{{severity}}`\n*Triggered:* {{triggered_at}}"
      }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Resource:*\n{{resource_name}}" },
        { "type": "mrkdwn", "text": "*Cluster:*\n{{cluster_name}}" }
      ]
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "View Alert" },
          "url": "{{alert_url}}"
        }
      ]
    }
  ]
}
```

> [!TIP]
>
> Create a Slack webhook at **Your Workspace → Apps → Incoming Webhooks**.

### Microsoft Teams

Microsoft retired Office 365 Connectors, so a Teams channel no longer offers an "Incoming Webhook" — the supported route is a Power Automate (Workflows) flow using the **"Send webhook alerts to a channel"** template, which hands you an HTTP POST URL to paste into Ankra.

Payloads on that route must be **Adaptive Cards** wrapped in a `message` attachment. The legacy MessageCard format is silently degraded: the flow reports success, but Teams drops every `potentialAction` button. Use `{{severity_style}}` for the card colour — Adaptive Cards cannot consume the `{{severity_color}}` hex value:

```json theme={null}
{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "msteams": { "width": "Full" },
        "body": [
          {
            "type": "Container",
            "style": "{{severity_style}}",
            "bleed": true,
            "items": [
              {
                "type": "TextBlock",
                "text": "{{alert_name}}",
                "weight": "Bolder",
                "size": "Large",
                "wrap": true
              },
              {
                "type": "TextBlock",
                "text": "Severity: {{severity}} | {{triggered_at}}",
                "spacing": "None",
                "isSubtle": true,
                "wrap": true
              }
            ]
          },
          {
            "type": "FactSet",
            "facts": [
              { "title": "Resource", "value": "{{resource_name}}" },
              { "title": "Cluster", "value": "{{cluster_name}}" },
              { "title": "Condition", "value": "{{condition_type}}" }
            ]
          }
        ],
        "actions": [
          { "type": "Action.OpenUrl", "title": "View Alert", "url": "{{alert_url}}" },
          { "type": "Action.OpenUrl", "title": "Acknowledge", "url": "{{acknowledge_url}}" }
        ]
      }
    }
  ]
}
```

> [!TIP]
>
> The built-in **Microsoft Teams** template in the destination form already uses this Adaptive Card format — pick the Teams preset and adjust from there. For interactive alerts inside Teams without Power Automate, connect the Ankra bot instead: see [AI Connections](/platform/ai-connections).

### Discord

Discord uses the embed format:

```json theme={null}
{
  "embeds": [
    {
      "title": "🚨 Alert: {{alert_name}}",
      "description": "**Severity:** `{{severity}}`",
      "color": 15158332,
      "fields": [
        { "name": "Resource", "value": "{{resource_name}}", "inline": true },
        { "name": "Cluster", "value": "{{cluster_name}}", "inline": true },
        { "name": "Triggered", "value": "{{triggered_at}}", "inline": false }
      ],
      "footer": { "text": "Ankra Alerts" },
      "timestamp": "{{triggered_at_iso}}"
    }
  ]
}
```

### PagerDuty

PagerDuty Events API v2 format:

```json theme={null}
{
  "routing_key": "YOUR_INTEGRATION_KEY",
  "event_action": "trigger",
  "dedup_key": "{{alert_id}}",
  "payload": {
    "summary": "{{alert_name}} - {{severity}}",
    "severity": "{{severity}}",
    "source": "{{cluster_name}}",
    "component": "{{resource_name}}",
    "group": "{{resource_type}}",
    "class": "{{condition_type}}",
    "custom_details": {
      "resource_name": "{{resource_name}}",
      "resource_type": "{{resource_type}}",
      "cluster_name": "{{cluster_name}}",
      "triggered_at": "{{triggered_at}}"
    }
  },
  "links": [
    { "href": "{{alert_url}}", "text": "View in Ankra" }
  ]
}
```

> [!TIP]
>
> Use PagerDuty's Events API v2 endpoint: `https://events.pagerduty.com/v2/enqueue`

### Opsgenie

Opsgenie Alert API format:

```json theme={null}
{
  "message": "{{alert_name}}",
  "priority": "P1",
  "description": "Severity: {{severity}}\nResource: {{resource_name}}\nCluster: {{cluster_name}}",
  "tags": ["ankra", "{{severity}}", "{{resource_type}}"],
  "details": {
    "alert_id": "{{alert_id}}",
    "resource_name": "{{resource_name}}",
    "cluster_name": "{{cluster_name}}",
    "triggered_at": "{{triggered_at}}"
  }
}
```

### Custom/Generic

For any other service, create a JSON payload that matches their expected format:

```json theme={null}
{
  "event_type": "alert",
  "alert": {
    "id": "{{alert_id}}",
    "name": "{{alert_name}}",
    "severity": "{{severity}}",
    "triggered_at": "{{triggered_at_iso}}"
  },
  "resource": {
    "name": "{{resource_name}}",
    "type": "{{resource_type}}",
    "cluster": "{{cluster_name}}"
  },
  "links": {
    "alert": "{{alert_url}}",
    "dashboard": "{{dashboard_url}}"
  }
}
```

***

## Testing Webhooks

After creating a webhook, use the **Test** button to:

1. Send a sample alert payload to your endpoint
2. Verify the message appears correctly in your target service
3. Confirm the JSON structure is valid for your integration

Test payloads populate **every** template variable, so a template that renders correctly under Test renders correctly on delivery - the Test button and the delivery pipeline run the same renderer. A real notification only fills the variables its kind has a value for, and the rows for the rest are dropped as described in [Empty values and fallbacks](#empty-values-and-fallbacks).

Testing a **routing rule** (Alerting → Routing rules → Test) sends the same sample through the rule's own kind, so you can check a rule and its destination's template together.

***

## Managing Webhooks

### Enable/Disable

Toggle webhooks on or off without deleting them. Disabled webhooks won't receive any notifications but retain their configuration.

### Edit

Update webhook URLs, templates, or settings at any time. Changes take effect immediately for future alerts.

### Delete

Remove webhooks you no longer need. Alerts using deleted webhooks will no longer send to that destination.

***

## Managing destinations and routes from the CLI

Everything above can be scripted with the `ankra` CLI, using the same personal access token as the rest of the CLI, so alert routing can live in Git and be applied from CI alongside your clusters. `-o json` and `-o yaml` keep the output parseable.

```bash theme={null}
# Destinations (webhooks and bot channels)
ankra alerts destinations list
ankra alerts destinations create --name "Ops Slack" --url https://hooks.slack.com/services/...
ankra alerts destinations create --name "Platform Teams" --type teams \
  --channel-id "19:...@thread.tacv2" --teams-tenant-id <tenant-id>
ankra alerts destinations channels            # channels the Ankra bot can post to (Slack and Teams)
ankra alerts destinations test <destination-id>
ankra alerts destinations update <destination-id> --description "On-call room"
ankra alerts destinations delete <destination-id>

# Notification routes (which notifications reach which destination)
ankra alerts routes list
ankra alerts routes create --destination-id <destination-id> --kind alert_trigger_fired --severity critical
ankra alerts routes update <route-id> --priority 10 --mode exclude
ankra alerts routes test <route-id>
ankra alerts routes delete <route-id>
```

Updates send only the flags you pass, so the rest of a destination or route stays untouched. The same endpoints are available directly for other tooling under `/api/v1/org/alerts/integrations` and `/api/v1/org/notifications/routes` with a bearer token.

Before you rely on a set of rules, run `ankra alerts routes preview` to see which destinations a notification would actually reach. [Notification routing](/guides/notification-routing) covers the full matching, ordering, and de-duplication behaviour.

***

## Related

* [Alerts](/guides/alerts) - Configure alert rules that trigger webhook notifications
* [Alert-triggered analysis](/platform/ai-insights#alert-triggered-analysis) - the AI analysis attached to every firing

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.


# Introduction
Source: https://docs.ankra.ai/index

Ankra connects or builds your Kubernetes clusters, deploys what they should run as versioned Stacks, and uses AI to explain and fix what breaks - from the web UI, the CLI, your AI assistant, or CI.

Running Kubernetes well usually means a pile of Helm values, a GitOps tool to babysit, a runbook per failure, and one person who knows how it all fits together. Ankra is the AI platform engineer that takes that pile off your team: you describe what a cluster should run, Ankra deploys it and keeps it in sync, and its AI reads your logs, events and deploy history to tell you why something broke and how to fix it.

It is built for platform engineers and developers who want production Kubernetes without hand-maintaining the machinery around it.

<video />

Connect a cluster and deploy a first Stack

## What you can do with Ankra

> [card] [Get a cluster](/guides/import-cluster)
>
> Connect the cluster you already run (EKS, GKE, AKS, k3s, on-prem, even minikube) with one helm command, or have Ankra build a new one on your own cloud account.

> [card] [Deploy what it runs](/concepts/stacks)
>
> Compose Helm charts and manifests into a Stack, visually or by asking the AI, and deploy the same Stack to every cluster that needs it.

> [card] [Find out why it broke](/platform/ai-assistant)
>
> Ask "why is this pod failing?" on any page. The AI already has the logs, events, manifests and recent deploys, and proposes a fix you approve.

> [card] [Automate it](/integrations/ankra-cli)
>
> Everything in the UI is also available from the `ankra` CLI, from your AI assistant over MCP, and from your CI pipelines.

## How it fits together

```mermaid theme={null}
flowchart LR
    O[Organisation] --> C[Cluster<br/>runs the Ankra agent]
    C --> S[Stacks]
    S --> A[Add-ons<br/>Helm charts]
    S --> M[Manifests<br/>Kubernetes YAML]
    G[(Git repository<br/>optional)] <-.-> S
```

* An **organisation** is your team's account: members, roles, credentials and billing.
* A **cluster** is any Kubernetes cluster running the lightweight [Ankra agent](/concepts/cluster-agent). The agent connects out to Ankra, so it works behind firewalls and NAT.
* A **Stack** is what a cluster should run: [add-ons](/concepts/addons) (Helm charts) and [manifests](/concepts/stacks#manifests) (your own YAML), with [variables](/concepts/variables) for what differs between clusters.
* **Git is optional.** Stacks deploy straight through the agent. Connect a repository when you want every change reviewed and versioned, and edits flow both ways - see [GitOps](/concepts/gitops).

## Start in 15 minutes

The [Quickstart](/get-started/quickstart) takes you from nothing to a connected cluster, a deployed Stack and your first answer from the AI. You do not need a cluster to follow it: the free [playground](/guides/cluster-sandbox) gives you a real one in about two minutes.

> [card] [Open the Quickstart](/get-started/quickstart)
>
> One path, a visible result at every step.

## Run your CI on your own clusters

Ankra CI runs a repository's tests, image builds and security scans as Kubernetes Jobs on a cluster you already connected, and reports back as a check on every pull request. [Get started with Ankra CI](/get-started/ankra-ci) moves your first repository in about 20 minutes.

> [card] [Get started with Ankra CI](/get-started/ankra-ci)
>
> From GitHub Actions or GitLab CI to a green Ankra pipeline check.

## Work from your own tools

The web UI, the CLI, the MCP server and the in-product AI all use the same tools and the same permissions, so anything you can do in one you can do in the others.

> [tab] CLI
>
> ```bash theme={null}
> brew install ankraio/tap/ankra
> ankra login
> ankra chat "why is the payments pod crashing?" --cluster prod
> ```
>
> See the [Ankra CLI](/integrations/ankra-cli) guide.

> [tab] AI assistants (MCP)
>
> Connect Claude, Cursor or any other MCP client to Ankra's remote MCP server. For Claude Code, register it once and sign in with `/mcp`:
>
> ```bash theme={null}
> claude mcp add --transport http ankra https://platform.ankra.app/api/v1/mcp
> ```
>
> Then run `ankra skills install` to teach the assistants on your machine Ankra's conventions. Setup for every client is in the [MCP Server](/platform/mcp-server) guide, and the [MCP Tool Reference](/platform/mcp-tools) lists every tool.

> [tab] CI/CD
>
> Your pipeline builds and pushes an image, commits the new tag to your GitOps repository, and Ankra deploys it - [Ship Your App](/guides/deliver-your-app) compares this with letting Ankra build and redeploy on every merge. Plain CI jobs can also call `ankra chat` and `ankra cluster apply` - see [Use the ankra CLI in CI](/guides/pipeline-agents).

> [!NOTE]
>
> **Automating Ankra or building an agent on it?** Use the [MCP server](/platform/mcp-server) or the [CLI](/integrations/ankra-cli) rather than driving the web UI with a browser. Both use scoped tokens, and every call lands in your organisation's audit log.

## Where to go next

> [card] [Add a cluster](/guides/import-cluster)
>
> Import one you have, or pick a provider for a new one.

> [card] [How Stacks work](/concepts/stacks)
>
> The model behind everything you deploy.

> [card] [AI Assistant](/platform/ai-assistant)
>
> What the AI can see, and what it may change.

> [card] [Security](/security/overview)
>
> What Ankra can access, and how to restrict it.

> [card] [Cloud Cost](/platform/cloud-cost)
>
> What each cluster, namespace and Stack costs.

> [card] [API Reference](/api-reference/introduction)
>
> The REST API behind every surface.

Need a hand? [Contact support](/platform/support) or ask in the [Ankra community Slack](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA).


# Agent Skills
Source: https://docs.ankra.ai/integrations/agent-skills

Install Ankra's curated Agent Skills into Claude Code, the Claude app, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI and other AI assistants, so they manage Kubernetes the Ankra way.

Ankra Agent Skills are `SKILL.md` instruction files that teach an AI coding assistant to follow
Ankra's practices: driving the CLI, authoring `ImportCluster` YAML, composing Stacks, taking a
repository from source to production, encrypting secrets with SOPS, reviewing access, and
supervising Ankra's own AI agents. Once installed, your assistant applies them automatically -
ask it to "get this service live on staging" and it reaches for the Ankra workflow instead of raw
`kubectl`.

The skills are embedded in the [Ankra CLI](/integrations/ankra-cli), so installation works
offline and the skill set is versioned with the CLI release.

> [!NOTE]
>
> These skills steer **your** editor or assistant. They are a different feature from
> [AI Skills](/platform/ai-skills), which teach **Ankra's own AI** your organisation's conventions
> inside the platform.

## Install

```bash theme={null}
ankra skills install
```

With no flags, the CLI detects the assistants configured on your machine and installs into all of
them. See what it found, and where each assistant's skills land:

```bash theme={null}
ankra skills clients
ankra skills list
```

Target assistants explicitly with `--client` (repeatable, comma-separated, or `all`):

```bash theme={null}
ankra skills install --client all
ankra skills install --client claude-code,cursor
ankra skills install --client copilot --dir .
ankra skills install --with-hooks
```

## Supported assistants

| Assistant | `--client` | How the skills are delivered |
| - | - | - |
| Claude Code | `claude-code` | Native skills directory, slash commands, optional hook |
| Claude app (claude.ai / desktop) | `claude-app` | One uploadable `.zip` per skill (see below) |
| Cursor | `cursor` | Native skills directory, rule, commands, optional hook |
| Codex CLI | `codex` | Skills library plus an index in `AGENTS.md`, prompts |
| GitHub Copilot | `copilot` | Skills library plus `.github/copilot-instructions.md`, prompt files |
| Windsurf | `windsurf` | Skills library plus rules, workflows |
| Gemini CLI | `gemini` | Skills library plus `GEMINI.md`, TOML commands |
| OpenCode | `opencode` | Skills library plus `AGENTS.md`, commands |
| Cline | `cline` | Skills library plus `.clinerules`, workflows |
| Zed | `zed` | Skills library plus `AGENTS.md` |
| OpenClaw | `openclaw` | Native skills directory - see [OpenClaw](/integrations/openclaw) |
| Any other assistant | `agents` | Skills library plus `AGENTS.md` |

Assistants that discover `SKILL.md` files themselves get a plain skills directory. Every other
assistant gets the skills in a shared library plus an **index** written into the file that
assistant always loads - naming each skill, what it covers, and the path to open. The index is
what makes the skills work in an assistant with no skills mechanism of its own.

### The Claude app

The Claude app cannot read your filesystem, so `--client claude-app` writes one uploadable
bundle per skill instead:

```bash theme={null}
ankra skills install --client claude-app
```

Upload each `.zip` at claude.ai under **Settings** → **Capabilities** → **Skills** →
**Upload skill**.

### Personal or per-repository

By default skills install for your user, available in every project. `--dir <dir>` installs
into a repository instead - the right scope for GitHub Copilot, whose instructions file is read
per repository. Commit the result so the whole team gets it:

```bash theme={null}
ankra skills install --client copilot --dir .
```

A repository-scoped install writes repository-relative paths, so the committed files work on
every teammate's machine.

## What gets installed

**Skills** - matched automatically against what you ask the assistant for. The set covers
getting started, the CLI, importing and building clusters, domains and DNS, Stacks and add-ons,
stack profiles, applications and CI/CD, GitOps, SOPS secrets, Helm registries, observability,
troubleshooting, alerting, security, and Ankra's AI agent surface. The
[Agent Skills Catalogue](/integrations/agent-skills-catalogue) breaks down every skill and when
your assistant reaches for it; `ankra skills list` prints the same from the CLI.

**Workflows** - named entry points you invoke deliberately, such as `/ankra-new-cluster` or
`/ankra-triage`, for jobs that span several skills. Installed in each assistant's own command
format, for assistants that have slash commands. The
[catalogue](/integrations/agent-skills-catalogue#workflow-commands) lists all seven. Skip them
with `--no-workflows`.

**A rule** that makes Ankra the default route for Kubernetes work: the assistant inspects
read-only freely, but routes changes through the GitOps repository or `ankra cluster apply`
instead of raw `kubectl`/`helm`. Skip it with `--no-rules`.

**A hook** (opt-in, `--with-hooks`) that intercepts direct `kubectl`/`helm` cluster mutations in
Claude Code and Cursor and pauses them for confirmation, pointing back at the Ankra workflow.

## Using the skills

Just ask - the assistant picks the right skills from the request:

* "Get this repo deployed to staging and then production"
* "Connect the API to our LiteLLM gateway"
* "The payments pod is crashlooping"
* "Set up a cluster on Hetzner and put our domain on it"

Or name one explicitly ("use ankra-stack-profiles"), or invoke a workflow (`/ankra-triage`).
Restart the assistant after installing so it loads the new files.

## Update and uninstall

Skills ship inside the CLI binary, so updating is:

```bash theme={null}
ankra upgrade
ankra skills install --force
```

Removal undoes what install did - the skills, the rule, the index, the workflows and the hook:

```bash theme={null}
ankra skills uninstall                    # everywhere an install is found
ankra skills uninstall --client cursor
ankra skills uninstall ankra-cli          # one skill, steering left in place
```

## Command reference

Every flag and subcommand is in the [CLI reference](/reference/cli/skills). The deprecated
`--editor` flag still resolves as an alias for `--client`.


# Agent Skills Catalogue
Source: https://docs.ankra.ai/integrations/agent-skills-catalogue

Every Ankra Agent Skill and the workflow commands, what each one covers, and when your assistant reaches for it.

The [Agent Skills](/integrations/agent-skills) install twenty-five `SKILL.md` files. Your
assistant matches them against what you ask for, so you rarely name one - but knowing what
exists tells you what you can ask. `ankra skills list` prints the same catalogue from the CLI,
and `ankra skills install <name> ...` installs a subset by name.

Two skills apply almost everywhere: `ankra-platform-principles` carries the cross-cutting rules
and the routing map from a request to the right skill, and `ankra-cli` is the command surface
everything else drives.

## Foundations

### ankra-platform-principles

The defaults every other skill builds on: Git as the source of truth, pinned chart and image
versions, variables over hardcoding, least-privilege credentials, promotion of the identical
artefact through environments, idempotent operations, explicit confirmation for destructive
actions, verify-then-claim, and read-only-by-default investigation. Also carries the routing
map, so an assistant that loads only this skill still knows which sibling to open next.

*Reaches for it when:* designing, reviewing or changing anything in an Ankra environment.

### ankra-getting-started

The ordered path from an empty organisation to a running application: CLI and login,
credentials, the GitOps repository, the first cluster (playground, import, or build), domain and
DNS, the base platform Stack, the first application, then access and hardening. Ordered so the
three decisions that are cheap now and expensive later - the GitOps repository, the batteries on
the first cluster, and the domain - come before anything is deployed.

*Reaches for it when:* someone is new to Ankra, sets up an organisation or a first cluster, or
asks "what do I do first".

### ankra-cli

Driving the `ankra` CLI end to end: login, switching organisation and cluster, the command map
across every family, applying configuration (validate, draft, apply), reading a cluster, triage,
AI from the terminal, support requests, and scripting with `-o json`, the token resolution
order, and the exit-code contract.

*Reaches for it when:* anything mentions the `ankra` CLI or managing an Ankra-managed cluster
from the terminal.

## Clusters

### Three ways to get a cluster

One skill per path:

| Skill | Path | Covers |
| - | - | - |
| `ankra-import-cluster` | Adopt a cluster you already run | Authoring and applying `ImportCluster` YAML: the GitOps wiring, stacks of manifests and Helm add-ons, dependency ordering with `parents`, validate and draft before apply |
| `ankra-cloud-clusters` | Ankra builds it on your infrastructure | Hetzner, OVHcloud, UpCloud, DigitalOcean, Proxmox VE, HPE Morpheus, Scaleway and AWS EC2: choosing region and instance family from live discovery, k3s vs kubeadm and etcd topology, the ingress/DNS/CCM batteries, GitOps at create time, availability zones, node groups, upgrades, and the difference between power, teardown and delete. A reference carries the per-provider instance-family guide, role sizing, GPU node groups and cost traps |
| `ankra-managed-kubernetes` | The provider runs the control plane | DOKS, UKS, GKE, OVH MKS, AKS, EKS and Kapsule: create with the first node pool and GitOps wiring, discover and adopt clusters that already exist, node pools and autoscaling, version upgrades, deletion |

### ankra-domains-dns

Public hostnames with DNS and TLS: the generated per-cluster subdomain under `ankra.cc`,
registering your own root domain delegated to Ankra, records in the organisation's zone, custom
DNS zones you serve with your own credential (organisation-wide or per cluster), and the
separate preview domain PR demos publish under - including that Ankra publishes nothing on a
preview domain you own, so an unpublished wildcard costs the URL and the certificate together.

*Reaches for it when:* a custom domain is wanted, an ingress hostname does not resolve, a
certificate never issues, or preview URLs are on the wrong domain.

## Building and deploying

### ankra-stacks-addons

Composing Stacks: Helm add-ons, raw manifests, variables, and the dependency edges (`parents`)
that control deployment order - including that every parent is a `kind` + `name` pair and the
shorthand form is silently dropped. One concern per Stack, namespace first, pinned versions.

*Reaches for it when:* designing or editing a Stack, adding a Helm add-on, or ordering
resources.

### ankra-stack-profiles

One definition serving many clusters: capturing a working Stack as a builder draft, turning
cluster-specific values into annotated parameters, option sets that move several inputs
together, secret parameters, validating and publishing versions, applying to a cluster as a
reviewable draft with `--dry-run`, diffing versions, sharing with other organisations, and
exporting as `ClusterInfrastructureAsCode` YAML.

*Reaches for it when:* a Stack would otherwise be copy-pasted to a second cluster, or anything
mentions stack profiles or the profile catalogue.

### ankra-ship

The default skill for shipping code: from a fresh or AI-generated project to a live URL through
Ankra Pipelines. It covers making the source shippable, the generated `.ankra/pipeline.yaml` that
tests, builds in your own cluster, scans with Semgrep, Checkov and Trivy, gates on the findings
and publishes an immutable `sha-` tag, then push-to-deploy, pull-request previews, environment
secrets, rollback, promotion and alerts. `ankra-applications` and `ankra-cicd` carry the detail.

*Reaches for it when:* you say ship it, deploy this, get it live, or ask for CI/CD for a new
project.

### ankra-applications

Your own source code from a Git repository to a running deployment on one or many clusters:
registering an application, the generated Dockerfile, chart and build workflow, declaring the
image registry at add time, environment secrets, deploys, auto-deploy, PR demos, security
scanning, and publishing the result as a catalogue add-on. A reference carries the registry
matrix (Harbor, ECR, GAR, ACR, GHCR, Docker Hub) and a complete greenfield walk-through.

*Reaches for it when:* deploying your own code, connecting a repository, or getting a service
live.

### ankra-cicd

Pipelines that build a container image, push it with an immutable tag, and bump that tag in the
GitOps repository so the Ankra engine syncs the change - rather than running `kubectl` or `helm`
against the cluster from CI. GitHub Actions and GitLab CI examples in the reference.

*Reaches for it when:* wiring CI/CD for an Ankra-managed app or asking how to deploy on push.

### ankra-gitops

The repository layout the Ankra engine syncs: connecting a repository in the `ImportCluster`
spec or at cluster create time, modular include paths, one directory per Stack, the
review-then-merge workflow, and `ankra cluster gitops status`.

*Reaches for it when:* connecting a Git repository to a cluster or organising a GitOps repo.

## Configuration and secrets

### ankra-sops-secrets

Secrets that live in Git: SOPS with AGE, `ankra cluster encrypt`/`decrypt` in cluster mode and
file mode, `glob:` key patterns that keep covering keys added later, `--all-data` for a whole
Secret, changing a value without ever committing plaintext (`encrypt --set`), and the
`encrypted_paths` declarations Ankra decrypts at deploy time.

*Reaches for it when:* a secret needs to be stored in Git, or anything mentions SOPS, AGE or
`encrypted_paths`.

### ankra-app-integrations

Connecting an application to what already runs: an LLM gateway such as LiteLLM or vLLM, a
container registry such as Harbor, a database, an object store, or an internal API - reusing the
credentials that already exist rather than minting new ones, and choosing correctly between
application env-secrets, SOPS-encrypted manifests, and cluster or organisation variables.

*Reaches for it when:* wiring an app to an existing service or secret, or asking where a
configuration value should live.

### ankra-helm-registries

Private chart sources: HTTP and OCI Helm registries, least-privilege registry credentials,
manual syncs and sync jobs when a chart is missing from the catalogue, and chart discovery with
`ankra charts list|search|info|values|template` before writing an add-on.

*Reaches for it when:* private charts, Helm registries, or registry credentials come up.

## Operating

### ankra-troubleshooting

The order of investigation when something is broken: platform executions first, then the object
(`describe`), events scoped with `--for`, logs including the `--previous` container of a
CrashLoopBackOff, live resources with `top` and PromQL - and a table classifying each symptom to
the layer that owns the fix.

*Reaches for it when:* a pod is crashlooping or Pending, a deploy failed, or a Stack will not
come up.

### ankra-observability

Deploying the monitoring and logging Stack (Prometheus, Grafana, Loki, Promtail), wiring
external Prometheus-compatible metrics sources (Grafana Cloud, Amazon Managed Prometheus, Google
Cloud Managed Prometheus, Thanos, VictoriaMetrics), and reading what you deployed with
`ankra cluster metrics` and `top`.

*Reaches for it when:* monitoring, dashboards, logging, or a metrics source is wanted.

### ankra-alerts-webhooks

Routing platform notifications: destinations (webhook URLs, or Slack and Teams bot channels),
routes filtering by kind, severity and cluster with include/exclude modes and priorities,
`routes preview` for "where would this go", and the `test`/`test-url` delivery checks that exit
non-zero for CI gating.

*Reaches for it when:* alerting, incident routing, on-call integration, or webhook delivery
comes up.

### ankra-security

The five independent places access is granted, and a review pass over them: API tokens and their
MCP scopes, organisation roles and membership, cluster access grants through the kube gateway,
credential scope for Git, registry and cloud (`ankra credentials repositories` shows what a
credential can really reach), secret handling, supply-chain scanning findings, and how much
autonomy the AI agents hold.

*Reaches for it when:* permissions, RBAC, token scopes, least privilege, hardening, or a
security review come up.

## Data and migration

### ankra-backups

The organisation's backup vaults with `ankra backup vaults` - provisioning a bucket from a
provider credential or registering one you already run - and the restore points over them: protecting a Stack on a schedule, taking a restore
point now, restoring a Stack in place, cloning a Stack with its data, and following the runs that
move the data.

*Reaches for it when:* backups, backup vaults, restore points, or a bucket for the platform
come up.

### ankra-migrate

Moving an existing deployment - docker-compose, a bare Dockerfile, or containers on a running
Docker daemon - into an Ankra-managed cluster with `ankra migrate`: plan first, convert to a
Stack, deploy, dump every database and restore it through a backup vault, then cut over.

*Reaches for it when:* migrating an app or server onto Kubernetes, docker-compose to
Kubernetes, lift-and-shift, or a cutover comes up.

## Ankra's AI

### ankra-ai-agents

Running and governing Ankra's own AI agents: choosing the model provider and catalogue (Ankra,
Anthropic, OpenRouter, or an OpenAI-compatible endpoint such as LiteLLM), registering MCP tool
servers and granting individual tools to organisation roles, supervising agent runs and reading
their transcripts, working the AI board of tickets and answering the decision a blocked ticket
waits on, and confirming or rejecting the writes an agent proposes.

*Reaches for it when:* Ankra AI, agent runs, MCP servers, the AI board, or the model catalogue
come up.

### ankra-ai-gateway

The Ask/Agent safety modes per Slack workspace, Teams tenant and SCM binding, the staging
cluster ephemeral AI workspaces and PR demos run on, and the pipeline-failure investigation and
auto-fix-PR flow.

*Reaches for it when:* connecting an AI integration, Ask vs Agent mode, AI workspaces, or PR
demos come up.

## As code

### ankra-terraform

The Terraform workflow for Ankra: where the token comes from, reviewing `terraform plan` before
every apply, pinning the provider, and managing each resource from Terraform or GitOps, never
both. What the released provider can do today is on the
[Terraform provider](/integrations/terraform) page.

*Reaches for it when:* the Ankra Terraform provider or IaC for the platform setup comes up.

## Workflow commands

Skills are matched against whatever you happen to say; a workflow is a named entry point you
invoke deliberately, for a job that spans several skills in a fixed order. Installed in each
assistant's own command format.

| Command | What it runs | Leans on |
| - | - | - |
| `/ankra-new-cluster` | Stand up a cluster from provider choice to a hostname that resolves with TLS | `ankra-getting-started`, `ankra-cloud-clusters`, `ankra-domains-dns` |
| `/ankra-ship-service` | Source code to a production deployment on one or many clusters | `ankra-applications`, `ankra-cicd`, `ankra-stack-profiles` |
| `/ankra-connect-app` | Connect an app to an existing service and its secrets | `ankra-app-integrations`, `ankra-sops-secrets` |
| `/ankra-triage` | Investigate a failing workload, deploy or operation, read-only until diagnosed | `ankra-troubleshooting` |
| `/ankra-promote` | Promote a verified change to the next environment without rebuilding it | `ankra-platform-principles`, `ankra-stack-profiles`, `ankra-gitops` |
| `/ankra-harden` | A ranked security pass over the organisation | `ankra-security`, `ankra-sops-secrets` |
| `/ankra-profile` | Capture a working Stack as a reusable, parameterised stack profile | `ankra-stack-profiles`, `ankra-stacks-addons` |

## See also

* [Agent Skills](/integrations/agent-skills) - installing, the supported assistants, and what
  else an install writes.
* [`ankra skills` reference](/reference/cli/skills) - every flag and subcommand.


# Ankra CLI
Source: https://docs.ankra.ai/integrations/ankra-cli

Comprehensive guide for installing, configuring, and using the Ankra CLI to manage clusters, chat with AI, browse charts, and automate platform operations.

## What is Ankra CLI?

The Ankra CLI is a powerful command-line interface for interacting with the Ankra platform. It enables you to manage clusters, chat with AI about your infrastructure, browse Helm charts, manage credentials, deploy stacks, and automate platform operations directly from your terminal.

## Installation

### Homebrew (recommended for macOS and Linux)

```bash theme={null}
brew install ankraio/tap/ankra
```

The formula lives in the [ankraio/homebrew-tap](https://github.com/ankraio/homebrew-tap) tap and is bumped automatically on every stable release. Upgrade later with Homebrew as usual:

```bash theme={null}
brew update && brew upgrade ankra
```

### Install script

For macOS and Linux without Homebrew - and for CI runners - use the universal installer:

```bash theme={null}
bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
```

It detects your OS and architecture, verifies the download against its published SHA-256 checksum, strips the macOS quarantine attribute where needed, and installs to `/usr/local/bin/ankra`. Pin an exact release by appending `--version <tag>`.

After installing either way, verify with:

```bash theme={null}
ankra --version
```

### Direct Download

Download the binary directly from [GitHub Releases](https://github.com/ankraio/ankra-cli/releases/).

```bash theme={null}
chmod +x ankra
mv ankra ~/bin/ankra  # or /usr/local/bin/ankra
```

### Upgrading the CLI

If you installed with Homebrew, upgrade through Homebrew:

```bash theme={null}
brew update && brew upgrade ankra
```

A Homebrew-managed binary refuses `ankra upgrade` and points you at `brew upgrade ankra` instead, so the two upgrade paths never fight over the same file.

For script and manual installs, the CLI can update itself in place with `ankra upgrade` (aliased as `ankra self-update`). The downloaded binary is verified against its published SHA-256 checksum before it replaces the running executable.

```bash theme={null}
# Upgrade to the latest stable release
ankra upgrade

# Check whether a newer release exists without installing
ankra upgrade --check

# Pin an exact version (also works as a downgrade / rollback)
ankra upgrade --version v0.3.0
```

| Flag | Description |
| - | - |
| `--version <tag>` | Install an exact release (e.g. `v0.3.0` or `0.3.0`); installs whether newer or older, so it doubles as a rollback |
| `--check` | Report whether a newer release is available without installing |
| `--beta` | Include pre-release versions for this run (overrides the saved channel) |
| `--force` | Reinstall even if already on the target version |
| `-y, --yes` | Skip the confirmation prompt |
| `--allow-unverified` | Install even when no checksum is published (insecure) |

> [!TIP]
>
> If the binary lives in a root-owned location, run `sudo ankra upgrade` or re-run the install script.

#### Beta (pre-release) channel

Opt in to release candidates (such as `v0.3.0-rc.1`) so `ankra upgrade` resolves the newest release including pre-releases:

```bash theme={null}
ankra config beta enable    # opt in
ankra config beta status    # show current channel
ankra config beta disable   # back to stable only
```

The channel preference is stored locally in `~/.ankra/settings.json` (separate from your credentials).

## Authentication

### SSO Login (Recommended)

The easiest way to authenticate is using browser-based SSO:

```bash theme={null}
ankra login
```

This will:

1. Open your browser to the Ankra login page
2. After you authenticate, save your credentials locally
3. You can then use all ankra CLI commands

Your credentials are saved to `~/.ankra.yaml`.

To logout and clear credentials:

```bash theme={null}
ankra logout
```

### Environment Variables (Alternative)

You can also use environment variables:

```bash theme={null}
export ANKRA_API_TOKEN=your-token-here
export ANKRA_BASE_URL=https://platform.ankra.app  # optional
export ANKRA_PROJECT=payments                     # optional: the project every command acts in
```

Add to your shell profile (`~/.zshrc` or `~/.bashrc`) for persistence.

## Quick Start

```bash theme={null}
# 1. Login with SSO
ankra login

# 2. List your clusters
ankra cluster list

# 3. Select a cluster to work with
ankra cluster select

# 4. Start chatting with AI about your infrastructure
ankra chat "What's the status of my deployments?"
```

## Machine-readable output (`-o json|yaml`)

Commands that read or return data support structured output via the shared `-o`/`--output` flag, so scripts and AI agents never have to parse tables or prose:

* `-o json` prints the result as indented JSON; `-o yaml` emits the same data as YAML.
* The kubectl-style commands (`cluster get ...`, `cluster describe`, `cluster events`, `cluster logs`, `cluster top ...`, `cluster helm releases`, `cluster metrics ...`) default to `-o table` and accept `json`/`yaml` as alternatives.

```bash theme={null}
ankra cluster list -o json
ankra cluster operations list -o json
ankra cluster get pods -o json
ankra org list -o json
```

Write commands (reconcile, provision, deprovision, scaling, node groups, token creation, …) also accept `-o json` and emit the API result - including operation IDs - so automation can poll `ankra cluster operations list <id> -o json` for completion. Asynchronous writes submitted without `--wait` emit `{"submitted": true, ...}`.

## Projects

> [!NOTE]
>
> `ankra project`, the global `--project` flag and `ANKRA_PROJECT`, `ankra tokens create --project`, `ankra org invite --role project` and the cost and usage project options require Ankra CLI v0.49.0 or later. Check with `ankra --version` and upgrade with `ankra upgrade`. Projects themselves are already on for every organisation on the new portal: older CLIs act in your current project, the one the console shows.

Every command acts in one [project](/concepts/projects) of your current organisation: the one `--project` or `ANKRA_PROJECT` names, else the one `ankra project switch` saved on this machine for this organisation, else your current project as the console shows it. `ankra project` manages projects and your place in them:

```bash theme={null}
# Where am I, and what else is there
ankra project current
ankra project list

# Switch - every command after this acts in payments, in the console too
ankra project switch payments

# Create, inspect, rename, delete (the Default project cannot be deleted)
ankra project create "Payments" --slug payments --description "The payments team"
ankra project get payments
ankra project rename payments "Payments platform"
ankra project delete old-team --yes

# Who reaches a project, and through which role
ankra project members payments

# Move a resource into another project, or make a shared kind organisation-wide
ankra project move --kind cluster --id prod-eu-1 --to payments
ankra project move --kind application --id storefront --to payments
ankra project move --kind credential --id <credential-id> --to org-wide

# Invite someone who reaches only one project
ankra org invite contractor@example.com --role project --project payments --project-role operator
```

A project is named by its slug, its name or its id; `--id` on a move also takes a cluster or application name. `ankra project switch` saves the project on this machine for the organisation you are in (`ankra org switch` forgets it), and it applies only when you act with your `ankra login` session, not with a token supplied by flag or environment variable; `ankra project current` says whether a flag, that saved selection or the platform's current project decides. To act in another project for one command, use the global `--project <slug|name|id>` flag or the `ANKRA_PROJECT` environment variable. Like `--org`, it applies to every command and every request of the invocation, sent as `X-Ankra-Project-Id`, without moving your current project:

```bash theme={null}
ankra cluster list --project payments
ANKRA_PROJECT=payments ankra cluster list
```

`--role project` on `ankra org invite` makes a [project-only member](/concepts/projects#project-only-members) of the project the global `--project` names; `--project-role` is `admin`, `operator`, `member` or `viewer`, `member` by default. `ankra project move` refuses with the platform's code and sentence when the resource is already in that project (`same_project`), when operations are still running on a cluster (`operations_in_flight`), or when a DNS zone is bound to a cluster and follows it (`follows_cluster`). The kinds it accepts are listed on the [Projects](/concepts/projects#moving-resources-between-projects) page.

Tokens take a project at creation: `ankra tokens create <name> --project payments` mints a token pinned to that project, see [API tokens](/reference/tokens). The fleet cost reads (`ankra cost summary`, `savings`, `ledger`, `trend`, `events`, `reconcile` and `cost budgets list`) cover the project you act in and take `--all-projects` for the whole organisation; `ankra cost object project <project>` prices one project, and `ankra org usage --group-by project` splits worker vCPU-hours by project. See [Cloud Cost](/platform/cloud-cost#from-the-cli-and-ankra-ai) and [Usage](/platform/usage#with-the-cli). In an organisation with projects off (one whose portal is not yet the new one; the new portal carries `/next` in its address), every `ankra project` command exits 3 and says so.

`ankra project` is unrelated to `ankra registry projects`, which are the projects of your image registry. Because `--project` is now the global flag, two older local flags were renamed: `ankra registry robots create --project` is `--registry-project`, and `ankra skills list|install|uninstall|clients --project <dir>` is `--dir <dir>`. The old spellings still work on those commands for one minor release with a deprecation line, and there they still mean the registry project or the directory; use `ANKRA_PROJECT` to pick an Ankra project on those commands until the old flags are removed.

## Command Reference

The full command reference - every command, subcommand, flag, and default - is generated from the CLI source on each release, so it never drifts:

> [card] [CLI Command Reference](/reference/cli/index)
>
> Browse all 32 command families: cluster, credentials, tokens, profile, org, chat, agents, application, skills, and more.

Every guide that shows an `ankra` command carries a `CLI vX.Y.Z+` marker above it: the first stable release that shipped the command. Compare it with `ankra --version`; a marker newer than the latest stable release means a pre-release command, reachable through the [beta channel](#beta-pre-release-channel).

Highlights:

| Task | Command | Since |
| - | - | - |
| Apply an ImportCluster manifest | `ankra cluster apply -f cluster.yaml` | v0.1.122 |
| Switch the project every command acts in | `ankra project switch payments` | v0.49.0 |
| Move a cluster into another project | `ankra project move --kind cluster --id prod-eu-1 --to payments` | v0.49.0 |
| Watch operations | `ankra cluster operations list` | v0.1.122 |
| Read the log a crash-looping container left behind | `ankra cluster logs my-pod -n default --previous` | v0.13.0 |
| Ask one object why it is not ready | `ankra cluster describe pod my-pod -n default` | v0.13.0 |
| See only the events for one object | `ankra cluster events --for pod/my-pod -n default` | v0.13.0 |
| Find what just ate the memory | `ankra cluster top pods -A --sort-by memory` | v0.13.0 |
| Chat with the AI about live cluster state | `ankra chat "why is my pod crashing?"` | v0.1.122 |
| Confirm a write that agent-mode chat proposed | `ankra chat actions confirm <action_id>` | v0.9.0 |
| Parse the AI's answer in a CI job | `ankra chat --mode ask -o json "is anything degraded?"` | v0.21.0 |
| Read one Secret's values, audited | `ankra cluster get secrets db-credentials -n default --reveal -o yaml` | v0.21.1 |
| Inspect what your AI agents are doing | `ankra agents runs` | v0.9.0 |
| Answer the choice a blocked AI board ticket is waiting on | `ankra tickets decide T-8 --option a` | v0.13.0 |
| See which of your vulnerabilities CISA lists as exploited in the wild | `ankra security findings --known-exploited` | v0.14.0 |
| Read the fleet's security posture and CISA KEV exposure | `ankra security overview` | v0.14.0 |
| Read the platform's advisory for a CVE - the parsed NVD/OSV record, CISA's guidance, affected versions and your exposure | `ankra security advisory <cve>` | v0.14.0 |
| Accept the risk of a finding with a reason and a review deadline, after a server-side preview | `ankra security dispositions create --occurrence <id> --disposition accepted_risk --reason "…"` | v0.15.0 |
| Download the compliance evidence report an auditor asks for | `ankra security compliance export --format csv` | v0.15.0 |
| Switch a cluster's pod-security policies from audit to enforce | `ankra security policy-mode enforce --cluster production` | v0.15.0 |
| Clone a stack between clusters | `ankra cluster stacks clone` | v0.1.124 |
| Move a Docker deployment into a cluster | `ankra migrate up ./app --cluster production` | v0.14.0 |
| Extend the CLI with plugins | `ankra plugins` | v0.14.0 |
| Register a backup vault | `ankra backup vaults create` | v0.14.0 |
| Encrypt a Secret's keys with SOPS | `ankra cluster encrypt manifest db-secret --key password` | v0.1.123 |
| Provision a Hetzner cluster | `ankra cluster hetzner create` | v0.1.124 |
| Mint a kubeconfig context | `ankra cluster kubeconfig add my-cluster --use` | v0.3.0 |
| Open your account's 2FA and passkey settings | `ankra profile auth open` | v0.9.0 |

`ankra migrate up` is the one that does the most in a single call: it converts a Docker Compose deployment into a stack, applies it to a cluster, and restores the deployment's PostgreSQL, MySQL and MariaDB data into it. Run it with `--plan` first to see what it found. See [Move a Docker deployment into a cluster](/guides/migrate-from-docker). The conversion is done by a module, and `docker` is only the built-in one: another source format is an executable named `ankra-module-<name>` that the CLI talks JSON to, installed with `ankra migrate modules install <url>` or placed on `PATH`, and [Write an ankra migrate module](/guides/migrate-modules) is the contract. The CLI is also extensible beyond migration, kubectl style: an unknown command runs an executable named `ankra-<command>` from `~/.ankra/plugins` or `PATH`, and `ankra plugins` lists what is installed.

## Agent Skills

The CLI carries Ankra's curated Agent Skills - `SKILL.md` files that teach your AI assistant
(Claude Code, the Claude app, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI and others) to
manage Kubernetes the Ankra way. `ankra skills install` detects the assistants on your machine
and installs into all of them. See the [Agent Skills guide](/integrations/agent-skills).

## Configuration

The CLI stores configuration in `~/.ankra.yaml`:

```yaml theme={null}
token: your-api-token
base-url: https://platform.ankra.app
token_id: token-uuid
token_name: ankra-cli-hostname-username
```

Token resolution priority (highest to lowest):

1. `--token` flag (explicit CLI argument)
2. Config file token (saved by `ankra login`)
3. `ANKRA_API_TOKEN` environment variable

The base URL can be overridden with `--base-url` or the `ANKRA_BASE_URL` environment variable.

## Troubleshooting

### Common Issues

**PATH issues:**

```bash theme={null}
which ankra  # verify installation location
echo $PATH   # check PATH includes ankra location
```

**Authentication errors:**

```bash theme={null}
ankra logout  # clear credentials
ankra login   # re-authenticate
```

**Check version:**

```bash theme={null}
ankra --version
```

**Get help:**

```bash theme={null}
ankra --help
ankra cluster --help
ankra chat --help
```

### Error Messages

* **"No active cluster selected"** Run `ankra cluster select` first
* **"Resource not found"** Verify the resource name and selected cluster
* **"Unauthorized"** Re-authenticate with `ankra login`

## Support & Resources

* **Slack:** [Join Ankra Community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA)
* **Email:** [hello@ankra.ai](mailto:hello@ankra.ai)
* **GitHub:** [ankraio/ankra-cli](https://github.com/ankraio/ankra-cli)

> For more advanced usage, see the full documentation or contact support.


# CLI Changelog
Source: https://docs.ankra.ai/integrations/ankra-cli-changelog

Release history for the Ankra CLI

**v0.52.3**

# Deprovision a Proxmox VE Cluster That Has Volumes

`ankra cluster deprovision` on a Proxmox VE cluster now names the persistent volumes it deletes, asks on a terminal, and sends `--accept-volume-data-loss`. The platform now deletes the disks the cluster's CSI driver provisioned and refuses with 409 until the loss is accepted, and the CLI did not pass the flag for Proxmox, so such a deprovision could never go through.

[Deleting a cluster deletes its volumes →](/guides/proxmox-persistent-volumes#deleting-a-cluster-deletes-its-volumes)

**v0.52.2**

# GitOps Status Names the Commit a Cluster Is in Step With

`ankra cluster gitops status` now prints `Applied Commit`, the commit the cluster is in step with and since when, and `Git Head Checked`, the head the platform last read and when, with a note on whether the two match. `Last Synced` only describes the last full sync.

A `diverged` status now lists its `Preserved Paths`: each file with when it was detected and whether it is decided. `-o json` carries the new fields.

[Cluster gitops status reference →](/reference/cli/cluster#ankra-cluster-gitops-status)

**v0.52.1**

# A Cluster Being Deprovisioned Says So

A command sent to a cluster that is being deprovisioned, such as deleting, patching or applying a resource, pod logs or a terminal, now prints the platform's reason: the cluster takes no new commands while its teardown is still running. It used to print "Cluster is offline. Check that the Ankra agent is running.", which sent people looking for an agent fault that was not there. Every other offline answer keeps the agent hint.

[Terminate a cluster →](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

**v0.52.0**

# Diagnose a Node over SSH, and See When an Answer Came from the Cache

`ankra cluster <provider> nodes diagnose <cluster> <node_id>` runs the read-only SSH diagnosis the Ankra assistant runs as `ssh_diagnose_node`. Over the platform's bastion lane it snapshots the node's Kubernetes service unit and journal, disk, memory, uptime, kernel log and firewall path to the API server, names the symptoms it finds and changes nothing on the node. It waits for the report (exit 5 when your `--timeout` runs out) and hands back the operation to poll when the job runs longer. It is offered on the providers with `nodes cloud-init-log` and needs the `clusters.operate` permission and a platform that serves the new route.

```bash theme={null}
ankra cluster hetzner nodes diagnose my-cluster "$NODE_ID"
```

`ankra cluster get`, `cluster events` and `cluster describe` now print one line on stderr when an answer came from the agent's cache, with its age and, when the platform knows, why the cluster did not answer live. Standard output is unchanged, and `cache_metadata` in `-o json|yaml` also carries `stale`, `reconcile_pending` and, from platforms that send it, `cache_age_seconds`. `ankra cluster info` takes a cluster id as well as a name.

[Hetzner nodes diagnose reference →](/reference/cli/cluster#ankra-cluster-hetzner-nodes-diagnose)

**v0.51.0**

# Merge Train Auto-Admit from the Terminal, and Who Replied Last

`ankra pipeline train enable --auto-admit off|shadow|on` switches the merge train's auto-admit from the terminal: with `on` the train adds green pull requests by itself, `shadow` only records which ones it would add, and leaving the flag out keeps the current mode. `ankra pipeline train list` shows the auto-admit mode and who set it, its latest decisions with the reason a pull request was left out, and a pull request stacked on another one as `(on #N)`; `-o json` carries the auto-admit and stacking fields it used to drop.

```bash theme={null}
ankra pipeline train enable --application my-app --auto-admit shadow
```

`ankra support list` gains `UPDATED` and `LAST REPLY` columns, `ankra support get` prints `Updated:` and `Last reply:` lines, and `-o json` carries `last_comment_at` and `last_comment_by`. `ankra credentials proxmox create` now waits up to five minutes for the platform to finish setting up Proxmox VE, where it gave up after 30 seconds and the credential was never saved.

[Pipeline train reference →](/reference/cli/pipeline#ankra-pipeline-train)

**v0.50.1**

# The Skills Explain Resizing a Single Control Plane

Only the bundled agent skills change. `ankra-cloud-clusters` now lists the `rolling`, `live_with_api_downtime` and `offline` ways a control plane's instance type changes, says the in-place single-controller resize is Hetzner only, and names the acceptance on each surface: `--accept-api-downtime` on the CLI, `accept_api_downtime` on the API and MCP, and **Resize with API downtime** in the portal. The assistant is told to get your go-ahead first. Run `ankra skills install --force` to refresh an installed copy.

[Change the control plane instance type →](/guides/operate-ankra-managed-clusters#change-the-control-plane-instance-type)

**v0.50.0**

# Grant a Role at Any Scope from the Terminal

`ankra org assign <member> --role <role> --scope organisation|cluster|cluster_group|project` grants a member a role at one scope. The member is named by email or user id, `--scope-id` names the cluster, cluster group or project (the global `--project` also works), and `--role` takes a built-in role or a custom role id. A grant the platform refuses, such as a duplicate or one above your own role, is shown with its reason.

```bash theme={null}
ankra org assign dev@example.com --role operator --scope cluster --scope-id prod-eu
```

`ankra org member role <member> --role <role>` changes a member's organisation role, including `--role project --project <ref>` to make them project-only; it needs a platform that accepts this change from an API token and exits 3 until then. `ankra cost summary --by provider|credential|project` shows only that breakdown, `credential` being new. Fixed: `ankra cluster kube-token`, and so `kubectl`, finds a cluster in another project of your organisation without a `--project` pin, `org invite`, `org remove` and `org member role` always act in the organisation they name, `ankra cluster select` remembers the cluster's project when the platform reports it, and the bundled skills no longer steer Hetzner clusters onto server types the location cannot provision.

[Org assign reference →](/reference/cli/org#ankra-org-assign)

**v0.49.0**

# Projects in the CLI, and a Preflight Before a Kubernetes Upgrade

`ankra project` manages projects (`list`, `current`, `switch`, `create`, `get`, `rename`, `delete`, `members`, `move`). The global `--project` flag or `ANKRA_PROJECT` runs one command in another project, `org invite --role project` invites a project-only member, `tokens create --project` pins a token, cost reads scope to the project (`--all-projects` for the whole organisation) and `org usage --group-by project` splits usage. Most of this release needs the matching platform API.

```bash theme={null}
ankra project switch payments
ankra cluster list --project payments
```

`ankra cluster upgrade preflight` checks whether a cluster is ready for a Kubernetes upgrade (exit 8 on a block), and `cluster upgrade` runs it first. `control-plane set-instance-type --accept-api-downtime` resizes a running cluster's only controller (Hetzner first), `cluster state-snapshots retention --days` sets etcd backup retention, `ankracloud cpu-pools` lists the CPU pools `node-group add --cpu-pool` pins a group to, `services get` shows each consumer's connection delivery, `application environments set --branches` sets per-environment branch rules and `application deploy --environment --follow-branches` sets one at first deploy. `registry robots create --project` becomes `--registry-project` and `skills --project` becomes `--dir`. Fixed: `cluster apply` (`--confirm-removal`, `--prune`), `stack-profiles rollout` (multi-stack needs `--yes`) and `migrate restore` stop removing or overwriting what you did not name, and a refused request exits 7, not 6.

[Projects in the CLI →](/integrations/ankra-cli#projects)

**v0.48.0**

# Preview and Approve the Exact Summary AI Destination

`ankra stack-profiles summary policy get` accepts paired `--openrouter-ingress` and `--openrouter-upstream` options to preview a proposed OpenRouter connection and provider without changing saved consent. Supply the same options and the inspected digest to `policy approve` to save them together; an unconfirmed preview is refused, and omitting both options keeps the saved routing. Europe requires regional access and applicable provider terms. This needs the matching platform API, and it does not enable generation or select a model.

```bash theme={null}
ankra stack-profiles summary policy get --openrouter-ingress europe --openrouter-upstream google-vertex/europe
```

The summary revision help now matches each operation: draft generation asks for the inspected draft revision, version generation for the published version, and consent revocation for an inspected positive policy revision.

[Stack-profiles summary policy get reference →](/reference/cli/stack-profiles#ankra-stack-profiles-summary-policy-get)

**v0.47.0**

# Ship Sets Up the Database an App Needs, and Data Migrations Roll Back

`ankra application ship --set-up-database` asks the platform to install PostgreSQL support on the cluster first, then deploys, for an application whose setup keeps a PostgreSQL database and so cannot start without the CloudNativePG operator. It needs `stacks.write` on the cluster; in an environment set to "Ankra runs it" the platform does this on its own. When a deploy is refused for a missing operator, ship now says to re-run with the flag, and it prints any warning the deploy returns.

```bash theme={null}
ankra application ship . --set-up-database
```

`ankra application data-migration list` and `get` follow the data migration of an application's Launch Plan step by step, and `rollback` puts the environment back as it was before the cutover and makes the vendor sources writable again, until the rollback window closes. `ankra stack-profiles summary` gains explicit generation controls (`status`, `draft-status`, `request-key`, `generate`, `generate-draft`, `cancel`, `policy get|approve|revoke`) and review commands (`get`, `evidence`, `generation`, `edit`, `review`, `withdraw`); they need the corresponding platform API and do not enable generation or select a model. An organisation administrator can move a merge-train entry to the front with `ankra pipeline train front`, and migrate modules now install when your home and temporary directories are on different volumes.

[Ship from your checkout →](/guides/deliver-your-app#ship-from-your-checkout)

**v0.46.0**

# Organisation Secrets Without the Value on a Command Line

`ankra secrets` manages an organisation's secrets without the value passing through a command line, a file you commit or a model's context. `create <name>` stores a value from `--generate` (Ankra creates it and nobody sees it), `--from-file` or stdin, and prints its `${SECRET_SLOT:<id>}` sentinel, which a stack, add-on or application references and Ankra resolves at deploy time; a value given as an argument is refused with exit 2. `list` never shows a value, `set` and `rotate` replace one in place so the sentinel stays valid, and `delete` refuses a secret deployed resources still reference.

```bash theme={null}
ankra secrets create db-password --generate
```

`ankra cluster ankracloud create` and `preflight` size and tier each server's root disk with `--bastion-disk-gib`, `--control-plane-disk-gib`, `--etcd-disk-gib`, `--worker-disk-gib` and the matching `--*-disk-tier` flags, and `ankra cluster node-group add` takes `--disk-gib` and `--disk-tier` for every server a node group creates. The agent skills now recommend `ankra secrets` for values that must not live in Git.

[Secrets reference →](/reference/cli/secrets#ankra-secrets)

**v0.45.1**

# Deleting a Cluster Fails Closed

`ankra delete cluster`, and `ankra cluster deprovision` with no argument, change nothing when they cannot read the cluster's kind; `delete` used to send the delete anyway. Both point a managed Kubernetes cluster or a playground at its own removal command (exit 2).

`ankra services packages collisions` checks that two services from a package could share a cluster, a cluster named exactly is found past the first 100 matches, and `services consumers unbind --revision` keeps a binding it failed to read.

[Delete cluster reference →](/reference/cli/delete#ankra-delete-cluster)

**v0.45.0**

# Check a Managed Service's Connection Before You Publish It

`ankra services packages propose --profile <id> --demo <workspace-id>` reads a running demo of the stack profile on the staging cluster and proposes the connection blocks the package could declare, from its Services' ports and its Secrets' key names, never their values; `-f package.json` writes the best complete proposal into the file `init` made. `probe ... --wait` runs the protocol's readiness canary against the demo with that connection and exits 0 only when it passed, 1 when it failed or is unknown, and 5 when it is still running at `--timeout`.

```bash theme={null}
ankra services packages propose --profile "$PROFILE_ID" --demo "$DEMO_ID" -f package.json
ankra services packages probe --profile "$PROFILE_ID" --demo "$DEMO_ID" -f package.json --wait
```

`ankra services packages init --addon` now has the platform build the chart's stack profile, and `--generate-secret <name>` with one `--generate-key` per key makes the profile generate the service's credentials in the cluster, where Ankra never sees a random value. `ankra cluster node-group`, `ssh-keys`, `scale` and `upgrade` on a cluster Ankra did not build, any `ankra cluster <provider>` command run against another provider's cluster, and `ankra delete cluster` on a cloud cluster now say so and exit 2, not 1.

[Services packages propose reference →](/reference/cli/services#ankra-services-packages-propose)

**v0.44.1**

# Set Any Cluster's Environment from the Terminal

Every `ankra cluster <provider> create`, managed clusters included, now takes `--environment` and `--criticality`, not only AWS, and `ankra cluster update <cluster> --environment <name>` changes an existing one.

```bash theme={null}
ankra cluster update my-cluster --environment production
```

`ankra services packages init --addon` makes a managed service from one Helm chart. `cluster apply` and `validate` warn that a file's `metadata.environment` and `metadata.criticality` are not read, and `packages init` flag mistakes and `ankracloud quota` on another kind of cluster exit 2.

[Cluster update reference →](/reference/cli/cluster#ankra-cluster-update)

**v0.44.0**

# Pin or Roll Back the Agent Version

`ankra cluster agent upgrade --version <release>` installs an exact agent release, and `--allow-downgrade` lets it be an older one: the rollback the platform's API already allowed. Without `--version` the command still never moves an agent backwards. A `--version` older than the running release without `--allow-downgrade`, or a release that is neither published nor running, is refused with the platform's reason and exit 2.

```bash theme={null}
ankra cluster agent upgrade --version 2.1.1247 --allow-downgrade
```

`ankra cluster agent auto-upgrade enable|disable --reason` records why the fleet rollout was fenced off. `ankra services packages init` and `publish` turn one of your stack profiles into a managed service, `ankra cluster ankracloud quota` shows how much of the Ankra Cloud account is left, `ankra org access-gateway zones|get|set` manages Cloud DNS proxy policies and `status` checks a Platform and Cloud relay deployment, and the CI skills explain where a converted job without `container:` runs. Fixed: `ankra cluster stacks deploy-draft` deploys the draft of a stack that is already running (on a platform that serves its stack-draft read) and, like `cluster apply --wait`, prints the platform's warnings, `ankra cluster draft` says why a stack was refused, and `--resource` names a custom resource's declared plural.

[Upgrading the Agent →](/concepts/cluster-agent#upgrading-the-agent)

**v0.43.1**

# Confirming a Chat Action Tells a Script the Truth

`ankra chat actions confirm -o json` now reports `success: true` exactly when the platform's status is `confirmed`; it printed `success: false` for an action that ran. A confirm the platform answers with any other status, such as `failed` when the action errored or the organisation's write limit refused it, exits 1 with the platform's reason instead of saying the action was confirmed. A reject still exits 0, and `-o yaml` now uses the same field names as `-o json`.

[Chat actions confirm reference →](/reference/cli/chat#ankra-chat-actions-confirm)

**v0.43.0**

# Propose a Change to the Kubernetes Access Policy

`ankra org access-policy set` proposes a change to the organisation's Kubernetes access policy, and an organisation owner or admin applies it, signed in: no token can change the policy itself. `set` takes only what should change (`--creator-role`, `--max-role`, `--elevated-max-ttl`, `--require-reason-from`) and a required `--reason`, then prints the policy before and after, the proposal id, its 7-day expiry and the link to apply it. Proposing needs the `kube_access.manage` permission (exit 7 without it).

```bash theme={null}
ankra org access-policy set --max-role edit --reason "No standing admin" --wait
```

`--wait` blocks until the proposal is decided and exits 0 when it was applied, 4 when it was dismissed, 1 when it expired or a newer one replaced it, and 5 when `--timeout` runs out. `ankra org access-policy proposals` and `proposal <id>` read proposals, and `get` names a pending one and its link.

[Org access-policy set reference →](/reference/cli/org#ankra-org-access-policy-set)

**v0.42.0**

# Signed Provenance Comes to the CLI

`ankra application provenance` and `ankra org provenance` show and change whether deploys verify the attestations a pipeline publishes. `get` and `set --mode off|warn|enforce` work per application or on the organisation default (`--clear` makes an application follow the organisation again), `verify <app> --image <ref>` is a dry-run that exits 1 when a deploy would be refused, and `ankra org provenance keys`, `rotate` and `revoke <key-id>` manage the organisation's signing keys. Under `enforce`, a version published before the application's first attested publish cannot be deployed or rolled back to. Changing a mode or a key needs `security.manage`.

```bash theme={null}
ankra application provenance set my-app --mode warn
```

An empty stack profile value is now a value: `ankra stack-profiles apply --set name=` binds the empty string, and an input whose default is `""` deploys with `""`, on the matching platform release.

[Verified Provenance at Deploy →](/security/deploy-provenance#set-the-mode)

**v0.41.0**

# Reach Cluster-Scoped Kinds, and Keep Secrets out of argv

`ankra cluster delete`, `patch` and `describe` reach CustomResourceDefinitions and other built-in cluster-scoped kinds such as APIService, PriorityClass and the webhook configurations without a namespace, so a leftover CRD that blocks a chart install can be cleared without kubectl. A cluster-scoped custom kind such as ClusterIssuer takes the new `--cluster-scoped` flag alongside `--group` and `--api-version`.

```bash theme={null}
ankra cluster delete crd kafkas.kafka.strimzi.io
```

`ankra org variables set --secret` stores a secret organisation variable that `list` and `get` never print, and `ankra org variables reveal <name>` prints one value, audited. `ankra helm credentials create` and `update` take `--password-stdin`, and `ankra ai endpoints create` and `ankra ai openrouter set` read the API key from stdin or a masked prompt, with `--api-key` deprecated. `ankra org ci-settings set` gains `--always-run-stage`, `--full-run-on-default-branch` and `--skip-markers`, `ankra org ai-environment set` sets where AI workspaces run and how long they live, `security dispositions update` and `revoke -o json|yaml` print the bare policy, and an invalid control-plane `set-count` exits 2. Fixed: commands run in the organisation `ankra org current` shows, a deleted resource reads as deleted and exits 3, `cluster apply --dry-run --cluster` no longer crashes, `stack-profiles drafts annotate --default ""` clears the default, and `application pipeline validate` takes `--no-local-graph`.

[Cluster delete reference →](/reference/cli/cluster#ankra-cluster-delete)

**v0.40.0**

# Faster CI You Can See and Preview

`ankra pipeline get` now shows how much CI time a run saved through path filters, the dependency graph and a promoted publish, with one line per skipped stage saying why and what the estimate is based on; a platform without the routes prints nothing extra. `ankra pipeline time-saved` totals it for the organisation, or one pipeline with `--application` or `--repository`, over the last 30 days (`--window 7d` for 7).

```bash theme={null}
ankra pipeline time-saved --window 7d
```

`ankra pipeline run --full` and `rerun --full`, also on `ankra application pipeline`, set the path filters aside for one run, and `pipeline get` prints a `Full run:` line saying why a run set its filters aside. `ankra pipeline validate` lists the definition's named path sets, and inside a git checkout `validate --changed-file` answers `affected:` stages from the dependency graph (`--no-local-graph` leaves them to the run; it needs `sh`, `git`, `awk` and `grep`, so not on Windows). `ankra ai memories list` and `clear` show and delete what the assistant remembers about you. `ankra skills install` ships all 25 skills reviewed against the current CLI, now naming seven golden paths and covering Terraform provider 0.3.0, `affected:` and `path_sets:`. Every `-o json` change is an added field.

[Time saved →](/guides/pipeline-reference#time-saved)

**v0.39.0**

# Force a Cancel Past a Run's Finally Stages

`ankra pipeline cancel --force` and `ankra application pipeline cancel --force` skip a cancelled run's `finally:` stages, which the platform now runs after a cancel before the run concludes cancelled. On a run that is already cancelling, `--force` stops the finally stages still running, and cancelling it again without `--force` is refused by the platform.

```bash theme={null}
ankra pipeline cancel "$RUN_ID" --application my-app --force
```

A cancelled run running its finally stages now reads "cancelling" in `pipeline list`, `pipeline get` and the cancel message, and every run in `-o json|yaml` gains a `cancelling` boolean, `false` from a platform too old to send it. The ankra-ship and ankra-cicd skills now say `finally` runs after a cancel, within a 15-minute budget; run `ankra skills install` to pick up the new text.

[Cancelling a run →](/guides/pipeline-reference#cancelling-a-run)

**v0.38.0**

# Manage Service Tokens from the Terminal

`ankra tokens list --service` and `ankra tokens create <account> --service --role <role>` manage the organisation's service tokens, where only `tokens rotate --service` existed before. The listing shows each token's service account, label, role, status and expiry; `create` mints a token for the named service account, creating the account with `--role` when there is none of that name, and shows the value once. Both need `members.manage` and exit 7 without it.

```bash theme={null}
ankra tokens create ci-deployer --service --role member
ankra tokens list --service
```

Fixed: revoking a grant that comes from an organisation role now says it was not revoked and exits 2, `cluster access list` and `security access` name a service account instead of a bare user id, kubectl's missing-grant hint points a service account at `ankra cluster access elevate`, and `cluster kubeconfig add --help` says whose access kubectl gets.

[Tokens create reference →](/reference/cli/tokens#ankra-tokens-create)

**v0.37.0**

# Cluster Access Refusals Exit with a Code That Says What to Do

`ankra cluster access grant`, `elevate`, `revoke` and `list` no longer exit 6, the code that says to run `ankra login`, for every refusal. A refusal by the organisation access policy (a role above the ceiling, a missing or too long `--expires`, a missing `--reason`) now exits 2, because changing the flags is the fix, and so does a flag the CLI cannot read, such as an unknown `--role`. A role without the permission exits 7, and only rejected credentials exit 6. `ankra cluster access --help` lists the codes.

`ankra cluster access list` now shows where each grant came from (manual, creator, role or elevated) and whether the policy would refuse it today, reading unknown when the platform cannot tell, and says to change the member's role for a grant the role sync re-creates after a revoke. `elevate` shows the grant's status and says to retry kubectl until the binding is applied, within about 30 to 60 seconds, and `ankra org access-policy get` says whether the organisation has set a policy and uses the API's key names with `-o yaml`.

[Cluster access reference →](/reference/cli/cluster#ankra-cluster-access)

**v0.36.0**

# Hold a Remote Go Build to Your GOMEMLIMIT

`ankra exec` and the `ankra dev` shims now forward `GOMEMLIMIT`, so a Go build that CI holds to a soft memory ceiling is held to the same one in the Ankra Workspace. Unset, the workspace's own default applies: five eighths of a run slot, 5GiB in a workspace of 8 GiB or more. A platform that predates the change refuses the variable with "This environment variable cannot be forwarded"; unset it for that one command.

```bash theme={null}
GOMEMLIMIT=5GiB ankra exec -- go build ./...
```

A node-group write submitted without `--wait` now names `ankra cluster operations list --failed --cluster <id>`, where a provider's late refusal, such as a server type out of stock, is recorded as a failed operation. `ankra org usage` says why a closed month's vCPU line has no amount, for example "no invoice for this month, so unknown", instead of printing `unpriced (<basis>)`.

[Exec reference →](/reference/cli/exec#ankra-exec)

**v0.35.0**

# Sign In from GitHub Actions Without a Stored Token, and Rotate Tokens

`ankra login --github-oidc` signs a GitHub Actions job in to Ankra with no stored token. Inside a job with `permissions: id-token: write`, it exchanges the job's OIDC ID token for an Ankra token that lasts 15 minutes by default and keeps it for the rest of the job, masking both in the log. An organisation admin first creates a trust policy with `ankra org oidc-trust create`, naming one repository exactly and optionally a ref, an environment and a workflow; pull request runs are refused unless the policy opts in. It needs the organisation id, from `--organisation-id` or `ANKRA_ORG`.

```bash theme={null}
ankra login --github-oidc --organisation-id <organisation-id>
```

`ankra tokens rotate <token_id>` issues a new token with the same name and scopes and keeps the old one working for an overlap window (`--overlap-hours`, default 24), so every place that uses it can be updated first. `--service` rotates an organisation service token, and rotating needs a platform that serves the rotate endpoints. `ankra org oidc-trust list|delete` manage the trust policies, and the token expiry warning now points at `ankra tokens rotate <id>`.

[Login reference →](/reference/cli/login#ankra-login)

**v0.34.0**

# Quarantine a Flaky Test, and a Warning Before Your Token Expires

`ankra pipeline tests quarantine` keeps a known-flaky test from failing your runs while someone fixes it. `settings --enable` turns it on per repository, `candidates` lists qualifying tests, and `release` or 10 straight passes end a quarantine. The test still runs; only a step whose sole failures are quarantined passes.

```bash theme={null}
ankra pipeline tests quarantine add <test key> --reason "known flaky"
```

The CLI warns once per run when its token expires within seven days, and `tokens list` flags `Expiring` tokens. New: `credentials ssh-key create|list` without a provider, key fingerprints on `credentials get`, `AAAA` records in `org dns add`, `cluster ankracloud create --network-mode ipv6_only`, `cluster agent ci set --build-apparmor-profile`, `cluster control-plane-heal`, `cluster agent resources`, `canvas publish|list|unpublish`, a security upgrade line on `cluster agent status` and reservations on `pipeline get`. `ankra services` names consumers by application, says when a service runs and why setup failed, and picks a package's newest version; `cluster ssh-keys get` names attached keys, `pipeline rerun --help` says a re-run repeats its original event and that `--failed-only` re-checks skipped steps, and `ankra chat` explains a billing pause. Fixed: `application ship` checks its `Live:` URL routes to the workload and ships only the requested branch, and `cluster apply` applies a stack's `applications:`.

[Quarantining a flaky test →](/guides/ankra-pipelines#quarantining-a-flaky-test)

**v0.33.1**

# Rotate a Value That Is Already Sealed

`ankra cluster encrypt manifest --set` can now set a new value on a key that is already sealed, such as a registry robot's `.dockerconfigjson`. It used to fail with `encryption failed: Failed to encrypt content`, so rotating a secret meant decrypting it into Git first. The CLI now unseals the manifest in memory, applies the edits and seals it again, keeping every previously sealed key sealed. The plaintext never reaches Git.

[Cluster encrypt manifest reference →](/reference/cli/cluster#ankra-cluster-encrypt-manifest)

**v0.33.0**

# Connect a Repository for Ankra Workspaces Alone

`ankra pipeline repositories connect --workspaces-only` connects a repository for Ankra Workspaces alone: `ankra exec` and `ankra workspace` work on it as usual, but its committed `.ankra/pipeline.yaml` is not read, nothing starts a run, and no commit status or check run is posted. Use it for a repository whose pipeline already runs somewhere else, so its pull requests do not get a second check. A platform too old to know the mode would connect an ordinary pipeline repository instead, so the CLI disconnects it again at once and says so.

```bash theme={null}
ankra pipeline repositories connect --provider github --owner my-org --name my-repo --workspaces-only
```

`ankra pipeline repositories set-mode <id> workspaces-only|pipelines` switches a repository that is already connected, and `list` and `get` show each repository's mode. `ankra exec` now says when a command ran the workspace out of memory, with the workspace's limit and the profile field to raise (`resources.memory`), instead of a bare "ended without a recorded exit code".

[Connect a repository for Workspaces →](/guides/ankra-workspaces#connect-a-repository-for-workspaces)

**v0.32.0**

# See Who Can Reach Each Cluster's Kubernetes API, and What to Fix

`ankra security clusters` gains an Access column that counts each cluster's live kube gateway grants, standing grants above `view`, grants the organisation access policy would refuse today, and grants whose identity the cluster verified can impersonate, for example `3 grants, 1 standing elevated, 2 over policy, impersonate unknown (1 of 3 verified)`. `ankra security access --cluster <cluster>` lists every failed check most severe first, with its grant id, grantee, role, scope and the revoke or grant command that fixes it, then every check that could not be evaluated.

```bash theme={null}
ankra security access --cluster my-cluster
```

A count the platform could not establish reads `unknown`, never 0, `no grants` appears only when every count is a known 0, and a platform that predates the access posture reads `not reported` in the column. When the platform's answer leaves the summary, the findings or the unknowns out, that part reads `not reported` and `security access` exits 1, since an incomplete answer is never a pass.

[Security access reference →](/reference/cli/security#ankra-security-access)

**v0.31.0**

# Restrict Bastion SSH to Your Addresses, and See What a Run's Tests Did

`ankra cluster <provider> create --bastion-allowed-ips` opens a Hetzner, OVHcloud, UpCloud or DigitalOcean bastion's SSH port only to the IPv4 sources you list, and `ankra cluster <provider> bastion allowed-ips <cluster> <ip-or-cidr ...>` replaces the list on a running cluster (`--clear` removes it). The platform's own egress and private network sources always stay allowed; IPv6 entries and `0.0.0.0/0` are refused. It needs a platform that serves the allowed-ips route: an older one answers 404 or 405 and ignores the create flag.

```bash theme={null}
ankra cluster hetzner bastion allowed-ips my-cluster 203.0.113.7 198.51.100.0/24
```

`ankra pipeline tests <run>` shows the test reports a run declared and what became of each, its counts by outcome, and its failed, flaky and slowest tests; `tests history <test key>` follows one test across a branch's newest runs, and `tests timings --stage <stage>` prints the mean durations a sharding script balances by. `ankra services setup` no longer needs a placement policy on the cluster; it needs a platform that makes the policy optional, and an older one still refuses the setup. `ankra pipeline train` now answers in a connected repository with no application, and `ankra exec` and `workspace up --wait` say what a provisioning workspace is waiting on.

[Hetzner bastion allowed-ips reference →](/reference/cli/cluster#ankra-cluster-hetzner-bastion-allowed-ips)

**v0.30.0**

# Send Heavy Commands to Your Ankra Workspace Automatically

`ankra dev install` puts small shims named `go`, `gofmt`, `golangci-lint`, `pnpm`, `npm` and `npx` in `~/.ankra/dev/shims` and links them into `~/.local/bin`, so coding agents, git hooks and your own shell send heavy, read-only runs such as `go test`, `golangci-lint run` and `pnpm typecheck` to your Ankra Workspace with the same output and exit code. Writers such as `gofmt -w` and `go mod tidy` run there too, and their changes are applied to your worktree. Everything else, and any command in a checkout without a workspace or while the platform is out of reach, runs on this machine as before.

```bash theme={null}
ankra dev install
ANKRA_EXEC_EXPLAIN=1 go test ./...   # prints where it would run
```

`ankra dev status` shows which tools resolve to a shim first on PATH, `ankra dev mode auto|remote|local` sets the default, and `ANKRA_EXEC=local` turns routing off for one command. No shell profile is edited (the PATH line to add is printed), `--uninstall` removes only what the install created, and `--replace-legacy` takes over the links of the older remote-exec shims.

[Route commands automatically →](/guides/ankra-workspaces#route-commands-automatically)

**v0.29.0**

# Run Heavy Commands in Your Ankra Workspace

`ankra exec -- <command>` runs a heavy command for your checkout in its Ankra Workspace and streams the output back. It snapshots the worktree as it is, including untracked files git does not ignore, without touching your branch or index, runs the command in the same directory there and exits with its exit code; Ctrl-C stops it. `--apply` brings back the changes a writer such as `gofmt -w` made, `--fetch test-results` copies result directories back, `--kind` picks the workspace profile, and `--check` says whether the checkout can use a workspace at all. It needs the `workspaces.use` permission and a repository connected to Ankra Pipelines.

```bash theme={null}
ankra exec -- go test ./...
```

`ankra workspace up|status|down` manages that workspace, reading the repository off a GitHub, GitLab or Bitbucket origin. `ankra application remove <application> --cluster <cluster>` takes an application off one cluster, with that deployment's data, and leaves it running everywhere else; it asks first and runs in the background, shown as `removing` in `ankra application installations`. Fixed: kubectl through the Ankra gateway no longer trips the token rate limit, because `ankra cluster kube-token` now caches its token on disk.

[Run your first command →](/guides/ankra-workspaces#run-your-first-command)

**v0.28.0**

# Break-glass Access You Give Yourself, and CI Spread over a Pool of Clusters

`ankra cluster access elevate` gives the identity the CLI runs as, you or a service account's token, time-boxed access to a cluster within the organisation access policy: `--expires` and `--reason` are required, and the role never goes above the policy's ceiling. It needs only the `kube_access.elevate` permission, so automation can hold it without granting anyone else. End it early with `ankra cluster access revoke <id>`; every elevation is audited.

```bash theme={null}
ankra cluster access elevate --cluster prod --role edit --expires 4h --reason "restart the stuck rollout"
```

`cluster access grant` takes `--expires` and `--reason`, `cluster access list` shows each grant's expiry and reason, and `org access-policy get` shows the limits grants are held to. `org ci-settings pool list|add|remove` spreads runs over several clusters, `pipeline repositories set-cluster` moves one repository's runs, and `org ci-settings get` names what blocks a scale-up. `cluster agent ci set` gains `--image-prepull on|off` and `--run-reservation off|shadow|on`, and `pipeline get` shows each step's resource use against its request and how long its pod sat Pending; all need platform and agent support. List and info views carry a `portal_url`, `security dispositions` shows what each policy is pinned to, and the installed skills teach time-boxed access and the `ankra` CLI over `kubectl`.

[Break-glass elevation →](/guides/cluster-access#break-glass-elevation)

**v0.27.0**

# See What Your Organisation Used, and Buy Registry Storage Yourself

`ankra org usage` shows what the organisation used of Ankra, per meter and period: worker vCPU-hours, playground time, managed service time and storage, hosted logs and metrics, and AI requests and tokens. The window defaults to this month so far; `--period last-month` or `--from` and `--to` pick another, `--granularity day` splits it by day and `--group-by cluster|application|instance` by what used it. A period nobody measured reads `not measured`, never 0. It needs the `billing.read` permission and a platform that serves the usage read.

```bash theme={null}
ankra org usage --period last-month --group-by application
```

`ankra registry storage buy --blocks <n>` buys registry storage in 50 GiB blocks at EUR 5 a month each on a platform with paid storage, showing the limit and price before and after and asking first. `ankra cluster agent ci set --node-group <name>` runs every pipeline pod on that node group, tainted or not, with `--node-selector`, `--toleration` and `--placement preferred` beside it and no agent restart, and `ankra cluster node-group add --labels --taints` labels and taints a group from its first node. `ankra services list --application <name-or-id>` lists the managed services an application uses.

[Read your usage with the CLI →](/platform/usage#with-the-cli)

**v0.26.0**

# Choose the Control Plane of an Ankra Cloud Managed Cluster

`ankra cluster managed create --provider ankracloud_k8s --control-plane development|production` chooses the control plane tier. `development` runs one replica and carries no control plane fee, so you pay for the nodes only, but an upgrade or the failure of its machine interrupts the Kubernetes API, so it is not for production. `production` runs three replicas and is the default. The tier stays for the life of the cluster, is refused with `--dev-cluster` and with every other provider, and needs a platform that offers control plane tiers.

```bash theme={null}
ankra cluster managed create --provider ankracloud_k8s --name my-test-cluster --location de-fsn1 --node-pool-size <plan> --control-plane development
```

`ankra registry storage retention` shows how many of the registry's 15 retention rule slots per project are used, suggests reusing existing keep values near the limit, and says plainly past it that the newest retention is not applied until rules are reduced.

[Choosing a control plane →](/guides/ankra-cloud-kubernetes#choosing-a-control-plane)

**v0.25.1**

# Retention Changes No Longer Overwrite Each Other

`ankra registry storage retention set`, `rule add` and `rule remove` now write the retention back with the version they read. When someone changed it in between, the command reads it again and applies the same change once, so a rule added in the portal while you remove another from the CLI is no longer lost; a second clash stops with exit code 1 and nothing written. `-o json` now includes the retention's `version`.

[Registry storage retention reference →](/reference/cli/registry#ankra-registry-storage-retention)

**v0.25.0**

# Robot Accounts on a Harbor You Run Yourself

`ankra registry robots create <name> --registry <entry> --admin-credential <credential> --project <project>` creates a robot account on a Harbor your organisation runs itself, not only on the Ankra registry. Name the OCI registry entry the Harbor is connected as, a registry credential of yours that may manage robot accounts there, and the one project the robot reaches. Ankra acts on the registry only with your credential, and `rotate`, `get` and `delete` work the same afterwards.

```bash theme={null}
ankra registry projects list --registry my-harbor --admin-credential harbor-robot-admin
ankra registry robots create collector-ci --registry my-harbor --admin-credential harbor-robot-admin --project collectorcharts
```

`ankra registry projects list --registry <entry> --admin-credential <credential>` lists the projects that registry actually holds. With `--admin-credential`, `ankra application registry set` now has the platform check that the declared project exists and create a missing one, private unless `--project-public` is given, instead of letting every later build fail at the push.

[Robots on a Harbor you run yourself →](/guides/harbor-registry#robots-on-a-harbor-you-run-yourself)

**v0.24.0**

# Registry Storage, GitOps Conflicts and Hosted Logs from the Terminal

`ankra registry storage` shows how full the organisation's registry is against its limit, 50 GiB per project by default, before a full one refuses every image push; from 80% it points at the ways out. `registry storage repositories` lists what takes the space, largest first, `retention` shows the image retention policy, `retention set`, `retention rule add|remove|list` and `retention run` change and apply it, asking first when fewer images are kept, and `registry storage request --size <GiB> --reason "..."` asks Ankra for a bigger limit.

```bash theme={null}
ankra registry storage
ankra registry storage repositories
```

`ankra cluster gitops conflicts list|resolve` ends a GitOps merge-conflict pause from the CLI; `resolve <resource-key> --keep git|cluster` records which side wins, never assuming one, and needs a platform that serves the conflict routes to API tokens. `ankra cluster logs-ship status|enable|disable` turns shipping a cluster's logs to Ankra's hosted store on and off, off by default; `enable` needs `clusters.write`. `custom-dns-zones add --cloudflare-credential <name>` serves a Cloudflare zone through Cloudflare's own provider, `org cloudflare credentials` flags a credential that lost its token as `needs-reconnect`, `org limits request --kind registry-storage` asks for storage too, and `cluster stacks data list` shows data in the stack's namespaces it does not own.

[Registry storage reference →](/reference/cli/registry#ankra-registry-storage)

**v0.23.0**

# Follow a Background Cluster Apply to Its Outcome

`ankra cluster apply` without `--wait` used to leave nothing recorded once the platform accepted the definition, so one it then refused read exactly like one it applied. The platform now records each background apply on an operation, the CLI prints `Follow it with: ankra cluster operations list <id>`, and the operation fails with the platform's reason when the apply is refused. `-o json` carries it as `operation_id`, and a fleet rollout names one for each target.

```bash theme={null}
ankra cluster operations list <operation-id>
```

`ankra cluster operations list <id>` reads one operation by its id alone, without `--cluster` or `ankra cluster select`. `ankra services setup` adds a Capacity line with the platform's verdict on whether the cluster has room for the service, and the `ankra-cicd` skill documents `build.component` and where each component's image and release bundle publish.

[Cluster operations list reference →](/reference/cli/cluster#ankra-cluster-operations-list)

**v0.22.0**

# Managed Services from the Terminal

`ankra services` sets up, inspects and retires managed services such as PostgreSQL, Valkey and OpenSearch, which could only be set up in the portal before. `packages list|get` browses the catalogue, `policy get|set` declares where a cluster is, and `consumers bind|list|get` names the namespace a service is for. `setup` prepares the platform's review and confirms the plan after a yes or `--yes`, `list` and `get` show state, health, readiness and the connection without any credential value, and `delete --acknowledge-data-loss` shows what a retirement removes and keeps before it confirms. `reviews` and `retirements` list and confirm your open reviews.

```bash theme={null}
ankra services setup orders-db --package postgresql --cluster prod --consumer <consumer-id>
```

`ankra registry projects create|list|delete` adds up to five extra registry projects, and `registry robots create --project <project>` binds a robot to one, so it reaches only part of what you publish. `ankra cluster helm get --reveal` reads a release's credential values in plaintext with the `kubernetes.secrets_reveal` permission, each reveal audited. `ankra org ci-settings get` adds a Capacity block on how full the pipeline cluster is, `pipeline get` says how long each step waited for a CI slot, and `cluster agent ci set` no longer claims an agent restart that did not happen.

[Set up a managed service →](/guides/set-up-a-managed-service#set-up-the-service)

**v0.21.2**

# Ship a New Application Without Pushing First

`ankra application ship` now takes a new Ankra Pipelines application to a running URL even when nothing was pushed since it was registered. It asks Ankra for the run a push to the tracked branch would have started, which publishes the image. Starting that run needs the `applications.deploy` permission.

```bash theme={null}
ankra application ship .
```

`ankra cluster hetzner create` prints the server type each role got, now that Ankra picks one the location has in stock for every role you leave without one. `ankra cluster addons list` shows `ok (stale)` and says when the advisory data was last read once it is over a day old, and `ankra cluster addons list <name>` exits 3 on a cluster with no addons. `ankra registry robots create --permission` works with a token that may create robots but not read them, and its help names the `credentials.reveal` permission that grants past pull and push need. `ankra targets register` no longer mentions an API token when it refuses a plain `http://` `--release-url`.

[Ship from your checkout →](/guides/deliver-your-app#the-first-build-with-nothing-pushed-yet)

**v0.21.1**

# Read One Secret's Values from the Terminal

Secret values now reach the CLI as `sha256:` digests, and `ankra cluster get secrets` says so instead of printing them as if they were values. `--reveal` reads the values of one named Secret. It needs the `kubernetes.secrets_reveal` permission, every reveal is written to the audit log, and it exits 7 when your role lacks the permission.

```bash theme={null}
ankra cluster get secrets db-credentials -n default --reveal -o yaml
```

`ankra org ai-review repos list|set|unset` turns the AI code review on or off for one repository without the portal. `ankra targets register` now says which agent release is missing and what to pass instead of failing with a bare 404, checks `--label` the way the host agent does before installing anything, and restarts the service when run again. `ankra cluster addons list <name>` prints an upgrade command that names the cluster, and `ankra registry robots create` refuses an empty `--permission`.

[Kubernetes Resources →](/platform/kubernetes-insights#configs)

**v0.21.0**

# Parse the AI's Answer in CI, and Ship Follows Ankra Pipelines

`ankra chat "<question>" -o json` (or `-o yaml`) prints one document when the turn ends: the answer, the tools the AI ran and how each ended, any change it proposed that has not run, and `error` when the turn failed, with a non-zero exit. A one-shot question no longer hangs after the AI proposes a write.

```bash theme={null}
ankra chat --mode ask -o json "is anything degraded?" | jq -r '.answer'
```

`ankra application ship` now follows the Ankra pipeline run that builds the application instead of waiting for a GitHub Actions run. Cluster creates leave machine sizes to the platform's defaults, `ankra cluster ankracloud` creates Ankra Cloud clusters (Closed Beta), `--force-drain` removes a worker whose drain a disruption budget refuses, `ankra cluster gitops status` shows when GitOps is paused on a merge conflict, and `ankra openclaw skill` writes a skill OpenClaw loads.

[Use the ankra CLI in CI →](/guides/pipeline-agents#parse-the-answer-as-json)

**v0.20.0**

# Run One Command in a Pod

`ankra cluster exec <pod> -n <namespace> -- <command> [args...]` runs one command in a pod through the platform, passed to the container exactly as given, with its output streamed and its own exit code returned, so scripts and CI can branch on it. `--stdin` forwards input, `-o json` returns one `{exit_code, stdout, stderr}` document, and every run needs the `kubernetes.exec` permission and is recorded in the audit log like a terminal session. It needs a cluster agent at 2.1.1166 or newer; an older one is refused and nothing runs.

```bash theme={null}
ankra cluster exec my-pod -n default -- cat /etc/os-release
```

Beside it, `ankra pipeline get` names who cancelled a run, why and when, and `ankra cost savings` says whether each saving is measured, billed or estimated, counting only the first two in its total.

[Pod Terminal →](/platform/pod-terminal)

**v0.19.0**

# Consent Before a Teardown Deletes Data, and the Cost Centre in the Terminal

`ankra cluster deprovision` (and each provider's `deprovision`) now names the persistent volumes a deprovision deletes on Hetzner, OVH, UpCloud, DigitalOcean, Scaleway and AWS, and deletes them only once you accept it - at the `[y/N]` prompt or with `--accept-volume-data-loss`. `--yes` and `--force` no longer stand in for that consent. Upgrade before the platform starts requiring it: an older CLI's deprovision of a cluster with volumes will then be refused. `power-schedules create|update --stop-mode scale_to_zero` asks the same way before data on worker disks is lost (`--accept-node-local-data-loss`).

```bash theme={null}
ankra cluster deprovision my-cluster                            # names the volumes and asks
ankra cluster deprovision my-cluster --accept-volume-data-loss  # for scripts
```

The cost commands grow from `cost savings` into `cost trend`, `cost events`, `cost ledger`, `cost budgets`, `cost autopilot`, `cost decisions`, `cost namespaces`, `cost object` and `cost reconcile`. Also new: `stack-profiles deprecate|undeprecate` withdraws a published version without deleting it, `cluster agent auto-upgrade enable|disable` keeps one cluster's agent out of the fleet rollout, and `application demo config set --protected` puts an application's demos behind a password.

[Terminate a cluster →](/guides/operate-ankra-managed-clusters#terminate-a-cluster)

**v0.18.0**

# Stopping a Cluster Keeps Its State

On Hetzner, OVHcloud, UpCloud, DigitalOcean, Proxmox VE and HPE Morpheus the platform captures an encrypted etcd snapshot before a stop removes the VMs, and the next start restores it: Secrets, ConfigMaps, custom resources and persistent volume claims come back and StatefulSets reattach their disks. `--preserve-state` and `--restore-state` steer it, `--mode pause` powers the servers off and keeps them instead, and power schedules carry the same choices with `--stop-mode` and `--preserve-state`.

The backups commands grow `cluster backups status`, `backup vaults contents`, `application backups|protect|backup` and `cluster stacks clone --with-data`; `cluster stacks deploy-draft` deploys a draft from the terminal; `ankra ai remediation policy` reads the auto-remediation policy; `pipeline validate --ref` dry-runs a branch before it is merged; and managed node pools can be handed to a provider autoscaler with `--externally-managed`.

[Stop cluster →](/platform/cluster-settings#stop-cluster)

**v0.17.1**

# Fixes

A retried backup vault upload in `ankra migrate up`, `migrate restore` and `migrate data` now re-reads the file instead of failing on its own body, and reports the error underneath. `--force` now reaches the Proxmox deprovision, so a cluster whose host is gone can still be torn down.

**v0.17.0**

# Self-managed AWS Clusters, Backups, and Where Each Branch Stands

`ankra cluster aws` creates and operates self-managed k3s or kubeadm clusters on EC2 (closed beta), with a bastion, `preflight` and `deprovision --force`. The first backups commands arrive: a `backup:` block on a stack in the cluster file, `stacks protect`, and restore points with `create|restore` and the runs that do them.

For pipelines, `ankra pipeline branches` and `pipeline list --latest-per-branch` answer where each branch stands, a superseded run reads as superseded rather than cancelled, `pipeline get` names what a queued run is waiting for, and `application pipeline convert` moves a workflow-built application onto Ankra Pipelines in one call. Also in this release: `registry robots`, `bucket create|list|get|delete`, `stack-profiles adopt`, `cluster mesh up`, `ankra upgrade` refreshing the installed agent skills, and the `ankra-ship` skill.

[AWS Clusters →](/guides/aws-clusters)

**v0.16.1**

# Choose the Model Each AI Function Runs On

`ankra ai lanes` is the terminal side of per-function AI model settings: `list` shows what deploy analysis, troubleshooting, CI/CD generation, stack READMEs and AI code review each run on, `set <lane> <model>` takes a catalog key or an exact OpenRouter model id, and `clear <lane>` returns a function to its default tier. Changing one needs organisation admin. `ankra application add` now says which registry an application will publish to when you did not declare one.

[Models per function →](/platform/ai-provider#models-per-function)

**v0.16.0**

# Wait on a Pipeline Run You Did Not Start

`ankra pipeline get` gains `--wait`, `--watch` and `--exit-code`, and they work on the push and pull request runs a webhook creates. A run can also be addressed by the commit a CI job knows, rather than by a run id it cannot know in advance.

Also in this release: stack profiles across a fleet (`apply --cluster`, a `deployments` table, a decoded `diff`, `rollout`), `cluster operations list --attention`, `cluster apply --cluster` targeting the cluster you name instead of the file's `metadata.name`, and every cluster-scoped command accepting a cluster's name where it previously accepted only its id.

[Ankra Pipelines →](/guides/ankra-pipelines)

**v0.15.2**

# Claude Design Import, and Internal Operations on Request

`ankra application import claude-design <path>` turns a Claude Design export into a static site in a new GitHub repository and registers it as an application, so the setup pull request, build and deploy follow as for any other application (closed beta). `ankra cluster operations list --include-internal` lists the platform's own maintenance executions, such as the GitOps snapshot push behind a repository commit.

Fixed: `ankra cluster deprovision` now works on a Scaleway cluster, and `ankra support attach` accepts PNG, JPEG, GIF and WebP images again.

[From Claude Design to a live application →](/guides/claude-design-to-ankra)

**v0.15.1**

# Fix

`ankra cluster apply` no longer drops a manifest's `force` and `auto_remediate` flags. A key that is absent or null means false, and a value that is not a boolean is refused with an error naming the key.

**v0.15.0**

# Ankra Pipelines and the Whole Security Center in the Terminal

`ankra pipeline` covers the whole pipeline lifecycle: repositories, definitions and their approval gate, runs, `validate` with the egress tier each step needs, findings, artifacts, and logs that follow a step before it starts or replay what a running one printed. The Security Center is complete in the terminal too: `security sbom` with licence-risk grading and SBOM export, `security stacks`, `pod` and `namespaces`, and `security history` and `report-schedule`.

Around those: `ankra application ship` takes a checkout to a running application in one command, `ankra cluster patch` corrects one field on a live object without kubectl, `ankra chat` shows what its tools are doing, and `stack-profiles import --as-draft`, `cluster manifests create`, `org ci-settings` and `alerts ingest-credentials` are new.

[Ankra Pipelines →](/guides/ankra-pipelines)

**v0.14.0**

# Backup Vaults and Migrating a Docker Deployment

`ankra backup vaults` registers an S3-compatible bucket you run, or has Ankra provision one from a provider credential, and `ankra migrate up` moves a Docker deployment into a cluster in one command: plan, convert, deploy, dump every database and restore it through a vault, rehearse, then cut over with `--stop-source`. The steps are also separate commands, and conversion modules install like plugins.

```bash theme={null}
ankra migrate up ./app --cluster production --plan
ankra migrate up ./app --cluster production
```

Around it: a shell in any pod with `ankra cluster terminal`, debug pods that impersonate a workload, kubectl-style plugins, `ankra cluster mesh` for Cilium ClusterMesh, Scaleway's full command set, UpCloud multi-zone clusters, kubeadm as the default distribution, the Security Center from the terminal with `ankra security` (CISA KEV and EPSS ordering, per-CVE advisories), the Cost centre as `ankra cost`, and `ankra cluster move --organisation`.

[Migrate from Docker →](/guides/migrate-from-docker)

**v0.13.0**

# The AI Board in the Terminal, Registry Robots, and Kubernetes Debugging Without a Kubeconfig

The release that makes the terminal a first-class seat at the platform: debug a cluster without fetching a kubeconfig, work the AI board and answer the decision an agent is blocked on, and run the whole application lane - including the robot account your builds push with.

## Work the AI board, and answer what an agent is waiting for

`ankra tickets` brings the board to the terminal. `list` shows what needs a person, telling "your decision" apart from a plain block; `get` prints the agent's question with every option it offered, its summary and the one it recommends; `decide` answers it - either an offered option or something else in your own words - and the agent resumes from your answer without re-asking.

```bash theme={null}
ankra tickets list --needs-human
ankra tickets get T-8
ankra tickets decide T-8 --option a
ankra tickets decide T-8 --answer "Publish to both for a week, then decide."
```

`events`, `comment` and `transition` complete the lane. A ticket is named by number (`8`, `T-8`) or UUID, and every command takes `-o json|yaml`.

[Answering a choice →](/platform/ai-board#answering-a-choice)

## Registry robots, and registries whose layout is not Ankra's

`ankra application registry robot get|ensure|rotate|revoke` manages the push robot Ankra mints per application - on your organisation's Ankra registry, and on a Harbor you operate once you name a project-administrator credential with `--admin-credential`. Where your registry addresses images differently, `--flat-repositories` and `--component-repository <component>=<repository>` describe what your pipeline already pushes, and `ankra application credential get|set` moves an application onto another GitHub credential instead of deleting and recreating it.

```bash theme={null}
ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce-images \
  --credential example-harbor-pull \
  --admin-credential example-harbor-admin
ankra application registry robot ensure <application-id>
ankra application registry robot rotate <application-id>
```

[Harbor as your application registry →](/guides/harbor-registry)

## Propose and review stack profile changes

The drafts family grew the cross-organisation review lane. `ankra stack-profiles drafts create --profile` on a profile another organisation owns opens a suggestion draft; `drafts submit-suggestion` sends it to the owner for review, and `ankra stack-profiles suggestions list | get | approve | reject | withdraw` works the queue - approving publishes the proposal as the profile's next version. `drafts rebase` moves a stale draft of your own profile onto its latest published version, keeping or discarding your edits.

```bash theme={null}
ankra stack-profiles drafts create --profile <profile-id>
ankra stack-profiles drafts submit-suggestion <draft-id> --title "Raise the default replica count"
ankra stack-profiles suggestions approve <profile-id> <suggestion-id>
```

[Stack Profile Suggestions →](/guides/stack-profile-suggestions)

## Debug a cluster without a kubeconfig

`ankra cluster logs` reads the log a crash-looping container left behind (`--previous`), follows or does not (`--follow=false`), and selects with `-l` and `--all-containers`. `ankra cluster describe <kind> <name>` answers "why is this not ready?", `ankra cluster events --for pod/my-pod` scopes an event listing to one object, and `ankra cluster top pods|nodes` shows live CPU and memory.

```bash theme={null}
ankra cluster logs my-pod -n default --previous
ankra cluster describe pod my-pod -n default
ankra cluster events --for pod/my-pod -n default
ankra cluster top pods -A --sort-by memory
```

## DNS and domains, end to end

`ankra org custom-dns-zones` serves a zone you own from every cluster in the organisation - the ones running now and every one created afterwards - while `ankra cluster custom-dns-zones` does the same for a single cluster. `ankra org domain get|set` reads and writes the organisation's own Ankra root domain, `ankra org dns zones` lists every cluster domain, and `ankra cluster domain` now reports the **public domain** hostnames actually publish under when that differs from the generated zone.

[Serving a zone in your own DNS account →](/concepts/applications#serving-a-zone-in-your-own-dns-account-from-every-cluster)

## Also in this release

* `ankra org mcp-servers` registers, enables and grants the MCP tool servers agent runs may call.
* `ankra cluster encrypt --key 'glob:<pattern>'` encrypts every key matching a pattern, now and on every later platform re-encrypt.
* `ankra application env-secrets`, `auto-deploy`, `settings`, `ai-config`, `publish-addon` and `manifest-addon` complete the application lane.
* `ankra cluster playground destroy` tears down the organisation's playground.
* `--sort` and `--order` on the main list commands.
* Every per-application command now accepts the application's name where it used to demand its UUID.

**v0.12.0**

# Cloud-init, Visible

Closes the loop on node-group cloud-init: `ankra cluster node-group add --user-data-file` attaches the document, and `ankra cluster <provider> nodes cloud-init-log` reads the first-boot output back, so a provisioning script is no longer debugged blind. `ankra cluster <provider> bastion status|diagnose` report the bastion's health, `ankra demo deploy` selects and tunes individual components, `ankra cluster reconcile` reports the operations it triggered, and `ankra application add` declares the image registry at create time - which is the moment that matters, because the build workflow is generated from it.

**v0.11.0**

# Alerting as Code, and Operations That Explain Themselves

`ankra alerts destinations` and `ankra alerts routes` bring alerting as code to the terminal: webhook and chat-channel receivers, a test fire that exits non-zero when the receiver rejects it, and routes deciding which notifications reach which destination by kind, severity, cluster and source.

`ankra cluster operations steps --results` shows what each step actually did - the resources a teardown deleted, skipped or failed to reclaim - instead of a status and a truncated excerpt. `ankra cluster logs --follow=false` prints the backlog and exits, so piping into `grep` no longer hangs. `ankra stack-profiles drafts` edits and publishes profile versions from the terminal, and `--force` on cloud deprovision and stop reclaims leaked cloud resources on every provider that lets it.

**v0.10.1**

# Fix

The OVH availability-zone flags render their type in `--help` again.

**v0.10.0**

# Playgrounds, Power Schedules, and OVH Zones

`ankra cluster playground` creates a throwaway cluster for an organisation, `ankra cluster power-schedules` starts and stops clusters on a timetable, and OVH clusters can be placed by availability zone. Demo inspection and repair arrive alongside `--allow-repoint` on `cluster apply` and `ankra ai openrouter set-key`.

Earlier in the same line: `ankra cluster gitops status` shows which GitOps repository a cluster actually syncs from, `ankra charts template` and `charts values` render a chart's manifests and defaults server-side, `ankra cluster encrypt` encrypts several keys in one run, and paginated listings gained `--all` so they no longer truncate silently.

**v0.9.0**

# Proxmox and Morpheus, AI Agent Runs, and Writes That Ask First

Two new self-managed cluster families, terminal control over what your AI agents are doing, confirmation prompts for the writes agent-mode chat proposes, and a long list of commands that finally show the data the API was sending all along.

## Proxmox VE and HPE Morpheus clusters

`ankra cluster proxmox` and `ankra cluster morpheus` bring both platforms to the terminal: create and deprovision, stop and start, worker and node-group scaling, labels and taints, autoscaling, control-plane changes, node inspection, SSH keys, and Kubernetes upgrades. Each family also discovers what the platform offers - Proxmox nodes, storages, bridges, and templates; Morpheus groups, clouds, plans, layouts, and networks - and manages its own credentials.

```bash theme={null}
ankra credentials proxmox create --help
ankra cluster proxmox nodes list <cluster_id>
ankra cluster morpheus node-group list <cluster_id>
```

Proxmox nodes restart with `ankra cluster proxmox nodes restart`. Morpheus has no restart lane on the platform, so the CLI does not pretend to offer one.

[Proxmox clusters →](/guides/proxmox-clusters) | [Morpheus clusters →](/guides/morpheus-clusters)

## Managed Kubernetes reaches parity

`ankra cluster managed stop | start` drives provider-native stop and start where the provider supports it (AKS today). The new `ankra cluster managed node-pool update` changes node counts and autoscaling settings in place, node pools accept autoscaling bounds at create and add time (`--autoscaling`, `--autoscaling-min`, `--autoscaling-max`), and Scaleway Kapsule joins the provider list as `--provider kapsule`.

[Managed Kubernetes →](/guides/managed-kubernetes)

## See and stop what your AI agents are doing

The new `ankra agents` family lists the organisation's dispatched agent runs, shows one run in full, reads the session transcript of what the agent actually said and did, and cancels a live run - the platform interrupts the in-flight turn within seconds without pausing the agent itself. Cancelling requires organisation admin rights, and all four commands support `-o json|yaml`.

```bash theme={null}
ankra agents runs --status running
ankra agents transcript <run_id>
ankra agents cancel <run_id>
```

[agents reference →](/reference/cli/agents)

## Agent-mode chat asks before it writes

In agent mode every mutating tool halts the turn and proposes the write, and the write only runs once the proposal is confirmed. The CLI used to drop that proposal silently, so `ankra chat --mode agent "restart node worker-1"` appeared to do nothing. The stream now renders each proposal - tool, description, risk, whether it is reversible, parameters, expiry, and the action id - an interactive session prompts to run or discard it, and `ankra chat actions confirm | reject | list` drives the same decision from a script.

If the cluster drifted since the proposal, confirming reports the drift instead of applying it, and prints the ready-to-run `--force` invocation. A superseded action is not offered a force, because forcing it cannot work.

[chat actions reference →](/reference/cli/chat)

## Scaleway lifecycle and node commands

`ankra cluster scaleway stop | start` releases and re-provisions compute while preserving the cluster definition, and `ankra cluster scaleway nodes list | get | restart` closes the last gap in provider node coverage - a Scaleway node could already be restarted from the portal and from AI chat, but not from the terminal.

## Node restarts and bastion resize across the provisioned providers

For Hetzner, OVH, UpCloud, and DigitalOcean, `ankra cluster <provider> nodes restart` reboots any provisioned node - a control plane node, a worker, or the bastion/gateway - as a tracked operation, and the new `bastion resize` command changes the bastion instance type with the same submit-or-`--wait` contract as node-group upgrades. `nodes list` gained a `PROVIDER_STATUS` column carrying the cloud provider's live power state, so an externally-stopped VM is visible before you act on it.

## Applications from the terminal

`ankra application add .` detects a local GitHub checkout and starts application setup, and the subcommands cover lifecycle, deployment, workflow, repository, security, publishing, and demo operations.

[application reference →](/reference/cli/application)

## Set a secret and encrypt it in one commit

`ankra cluster encrypt manifest` accepts repeatable `--set` edits that are applied in memory before encryption, so the new value and its SOPS encryption land in a single commit - the plaintext never reaches git history. The previously documented flow of `manifests upgrade --set` followed by `encrypt manifest` committed the plaintext first, leaving it recoverable from the repository history.

```bash theme={null}
ankra cluster encrypt manifest db-secret --key password \
  --set 'data.password=bmV3LXNlY3JldA==' --cluster prod
```

`ankra cluster manifests upgrade --from-file` also accepts SOPS-encrypted files now, detecting `ENC[...]` keys and recording them as `encrypted_paths` automatically, with `--encrypted-path` to declare keys explicitly.

## Commands that were quietly returning nothing

A batch of listings and readers were decoding JSON keys the API never sends, and showed empty results rather than an error. `cluster manifests list` always printed "No manifests found", `org members` always printed "No members found", `chat health` printed an empty status scored 0, and `cluster stacks history` rendered blank rows. All of them now decode the response the API actually returns.

Alongside that: `ankra cluster addons uninstall` resolves the addon's resource id through the stack history instead of sending an empty id and failing with a 404; `cluster stacks` and `cluster addons list` walk every page instead of stopping at the first 25; every `ankra cluster managed` subcommand now calls a path the backend serves, instead of failing with "not found"; `ankra cluster kubeconfig add my-cluster` accepts the cluster as a positional argument; and `ankra helm registries create` explains the expected file shape up front rather than letting the API answer with an unexplained error.

## Your cluster YAML keeps its fields and comments

`ankra cluster encrypt -f` and `ankra cluster clone` used to rewrite the file by re-serialising an internal struct, silently dropping anything the struct did not model - `deploy_wave` on stacks and `spec.prometheus_metrics` were lost outright, and comments, anchors, and key ordering were destroyed. Both now edit the parsed YAML document in place, touching only the nodes they change.

## Deprecated

`ankra cluster deprovision --auto-delete` is deprecated: the backend parses and discards it, so it never deleted anything. The flag is hidden, prints a warning pointing at `ankra delete cluster`, and is scheduled for removal in v0.10.0. `--force` is only honoured by the Hetzner deprovision endpoint, and now says so on stderr for every other cluster type instead of implying a forced teardown.

**v0.8.0**

# Real Agent Tokens and Drift Field Paths

A small release fixing two agent commands that reported the wrong thing, plus drift detail in operations.

## `agent token` prints the real token

`ankra cluster agent token` rendered an empty string: it decoded a `token`/`expires_at` shape the platform no longer returns. It now decodes every returned field, extracts the `ank_cai_…` token from the install command when that is all the platform sends, and prints the token together with the full install/update command. Structured output carries `token`, `cluster_id`, and `command`; the never-populated `expires_at` is gone.

## `agent status` no longer calls a stale agent connected

Status was derived from `checked_in_at` merely being present, so an agent offline for days still displayed `Status: connected`. The CLI now uses the platform's `is_online` verdict when present - the same 30-second threshold that flips clusters offline - and otherwise falls back to a two-minute recency test, rendering a stale check-in as `not connected (stale check-in)`.

## Operations show which fields drifted

`ankra cluster operations list <id>` and `operations steps <id>` now render each drifting resource with its drift type and the exact field paths the agent compared, for example `/spec/template/spec/hostNetwork`, instead of only step metadata and timings. Enrichment is best-effort: on platforms without the execution result endpoint the commands work as before.

**v0.7.0**

# Browser Login Without a Local Port, Managed Kubernetes, and Homebrew

**This release is required to log in.** The platform has dropped support for the old localhost-callback login flow and answers pre-v0.7.0 CLIs with `426 Upgrade Required`.

## Login no longer opens a local network port

`ankra login` used to start a localhost callback server and have the browser redirect the OAuth code to it. The CLI now starts a platform login ticket, drives the whole flow in the browser including sign-in approval and any MFA challenge, and polls for the parked token with a PKCE code verifier that never leaves your machine.

## Install with Homebrew

```bash theme={null}
brew install ankraio/tap/ankra
```

The formula lives in the [ankraio/homebrew-tap](https://github.com/ankraio/homebrew-tap) vendor tap and is bumped automatically on every stable release. A Homebrew-managed binary refuses `ankra upgrade` and defers to `brew upgrade ankra`, so brew stays the single owner of the file.

## Managed Kubernetes for all six providers

`ankra cluster managed` previously accepted only `doks` and `uks` even though the platform already managed the rest. `create`, `delete`, `node-pool add | scale | delete`, and `upgrade` now accept `doks`, `uks`, `gke`, `ovh_mks`, `aks`, and `eks`.

**v0.6.0**

# Cluster Groups, Scoped Roles, Deploy Waves, and Agent Guardrails

Organisation-level RBAC building blocks, ordered stack deployment, node-group autoscaling, and the agent rules that make Ankra the default Kubernetes workflow in your editor.

## Cluster groups and scoped role assignments

`ankra org cluster-groups list | create | add-cluster | set-selector | preview` manages named sets of clusters, either static or resolved from a label selector, for use as role-assignment scopes. `ankra org assign <member-email>` then grants a role at organisation, cluster, or cluster-group scope, with `ankra org assignments` and `ankra org unassign` to inspect and revoke. `ankra org roles create` defines custom roles that can bundle Kubernetes access levels provisioned across the assignment's scope.

## Ankra becomes your agent's default Kubernetes workflow

`ankra skills install` now also writes an always-applied rule telling Cursor or Claude Code that clusters here are Ankra-managed: route changes through the GitOps repo or `ankra cluster apply`, inspect freely, never mutate with raw kubectl or helm. Add `--with-hooks` and cluster-mutating kubectl/helm commands pause for confirmation with a redirect to the Ankra workflow, while read-only inspection and `--dry-run` pass through untouched. The guard fails open and merges into existing hook configuration without disturbing other entries; `--no-rules` skips it and `ankra skills uninstall` cleans everything up.

## Stack deploy waves

Stacks in a cluster YAML accept an optional `deploy_wave` (an integer of 0 or more): stacks in wave N deploy only after every stack in a lower wave finished, and teardown unwinds in reverse. Stacks without a wave keep the existing unordered behaviour. The wave is validated by `ankra cluster apply`, preserved by partial patches, and shown as a Wave column in `ankra cluster stacks list`.

## Node-group autoscaling

`ankra cluster node-group autoscaling get | set` reads and writes a node group's Cluster Autoscaler settings on Hetzner, OVH, and UpCloud. `set --enabled --min <n> --max <n>` keeps the group within those bounds based on pod demand, installing the autoscaler on first enable.

## Scoped tokens and a distinct RBAC exit code

`ankra tokens create --scopes` pins an API token to a permission allowlist. When the platform denies a request because your role lacks a permission, the CLI now names the missing permission, points at an organisation admin, and exits **7** - distinct from exit 6, which means re-authenticate.

**v0.5.1**

# DigitalOcean and Managed Kubernetes

## DigitalOcean clusters

`ankra cluster digitalocean` (alias `ankra cluster do`) covers create, deprovision, stop and start, scale, upgrade, node groups, regions and sizes discovery, with credentials in `ankra credentials digitalocean`. The provider-agnostic commands - `scale`, `upgrade`, `node-group`, `ssh-keys`, `deprovision` - detect DigitalOcean clusters automatically.

## Managed Kubernetes

`ankra cluster managed` arrives with create, deprovision, upgrade, and node-pool operations for DigitalOcean Kubernetes (`doks`) and UpCloud Managed Kubernetes (`uks`).

## Long stack writes no longer time out

`addons upgrade`, `manifests upgrade`, `encrypt … --cluster`, and `stacks variables set | delete` end in a partial-stack PATCH the backend serves synchronously, including a full GitOps commit and push when the cluster has a linked repository. On large clusters that legitimately exceeded the old 60-second command context; the deadline is now five minutes.

**v0.5.0**

# kubeadm Upgrades, etcd Topology, and the Generated Reference

## kubeadm cluster upgrades

The provider-agnostic `ankra cluster upgrade` now covers kubeadm clusters alongside k3s. Nodes upgrade one at a time, control plane first: each is cordoned, drained respecting PodDisruptionBudgets, upgraded, and gated on being Ready at the target version, with an etcd snapshot taken before the control plane. `--force` proceeds when a drain is blocked by a PodDisruptionBudget, where the default aborts safely. `ankra cluster kubeadm-versions` lists the versions available, as a sibling of `ankra cluster k3s-versions`.

## etcd topology at create time

`ankra cluster hetzner | ovh | upcloud create` gained `--etcd-topology` (`stacked` on the control planes, or `external` on dedicated VMs), `--etcd-node-count` (3 or 5), and `--etcd-server-type` for sizing dedicated etcd nodes.

## The generated CLI reference

The full command tree is now rendered as documentation pages straight from the CLI source, and a release-tag workflow opens a sync pull request against these docs - so [the reference](/reference/cli/index) can never drift from the shipped binary.

## Kubeconfig entries pin the owning organisation

Entries written by `ankra cluster kubeconfig add` embed `--org <organisation-id>` in the `kube-token` exec arguments, so `kubectl` keeps working after you switch your selected organisation. Previously the token mint failed with "Cluster not found" whenever the selection differed from the cluster's owner.

**v0.4.0**

# Cluster Access (RBAC) and Provider-Agnostic Cloud Verbs

Per-user cluster access management, cloud-agnostic lifecycle verbs that auto-detect the provider, and the deprecation of the provider-specific equivalents.

## Cluster access (RBAC)

`ankra cluster access list | grant | revoke` manages who can reach a cluster's Kubernetes API through the Ankra kube gateway (the access used by `cluster kubeconfig` and `cluster kube-token`). A grant maps an organisation member (by email) to a Kubernetes role - `view`, `edit`, `admin`, or `cluster-admin` - cluster-wide or limited to one namespace with `--namespace`. `list` shows each grant's RBAC reconcile status; `revoke` accepts a grant ID or an email (revoking every grant that member has on the cluster). Managing access requires organisation admin rights.

```bash theme={null}
ankra cluster access grant user@example.com --cluster prod --role edit --namespace staging
ankra cluster access list --cluster prod
ankra cluster access revoke user@example.com --cluster prod
```

## Provider-agnostic cloud cluster verbs

New cloud-agnostic verbs detect the provider (Hetzner, OVH, UpCloud) automatically from the cluster, so you no longer pick a provider namespace:

* `ankra cluster upgrade <cluster_id> <target_version>` - upgrade the Kubernetes (k3s) version.
* `ankra cluster scale <cluster_id> <worker_count>` - scale the default worker pool.
* `ankra cluster node-group <list|add|scale|upgrade|delete>` - manage node groups.
* `ankra cluster k3s-versions` - list the k3s versions available for `cluster upgrade`, with the stable channel highlighted.

`ankra cluster deprovision` now accepts a cluster ID **or** name (previously name-only) and routes cloud clusters to the provider-specific teardown so cloud resources are released.

## Agent Skills for Claude Code

`ankra skills install | list | uninstall` gained an `--editor` flag so the curated Agent Skills can target Claude Code as well as Cursor. It defaults to `cursor` (`.cursor/skills`, unchanged); pass `--editor claude-code` to install into `.claude/skills`, for both the personal (`~/…`) and `--project` scopes.

```bash theme={null}
ankra skills install                        # ~/.cursor/skills (default)
ankra skills install --editor claude-code   # ~/.claude/skills
```

## Support review before submit

`ankra support create` now shows the AI review before submitting: the reasons a request was flagged, clarifying questions that would speed up triage, and any existing ticket that may already track the same problem. When the review flags the request or finds a possible duplicate you're asked to confirm; `--force` skips the prompt, and `-o json|yaml` callers get a `--force`-guidance error instead of a prompt.

## Isolated `--config` state

`--config <file>` now fully isolates per-invocation state: a config file with an unfamiliar or missing extension is parsed as YAML (instead of reading empty and dropping the saved token), and the active-cluster selection is keyed to the explicit `--config` path rather than `$HOME`, so parallel runs against different config files no longer clobber each other. If you previously ran with `--config` and relied on the `$HOME`-keyed selection, re-run `ankra cluster select` once.

## Deprecated

The provider-specific `ankra cluster {hetzner,ovh,upcloud} upgrade | scale | node-group | deprovision` commands are deprecated in favour of the cloud-agnostic verbs above. They still work and now print a runtime warning pointing at the replacement; they are scheduled for removal in v0.5.0. OVH's `node-group labels` / `node-group taints` remain - they have no provider-agnostic equivalent yet.

**v0.3.0**

# kubectl, Metrics, Support, Stack Profiles, and Cluster Validation

The first stable v0.3.0 release rounds out end-to-end terminal control of an Ankra cluster: connect kubectl directly, query metrics, file support tickets, manage reusable stack profiles, validate and stage cluster YAML, and self-update the CLI.

## Connect kubectl directly

`ankra cluster kubeconfig add | remove | list` and `ankra cluster kube-token` wire kubectl straight to an Ankra cluster through the kube gateway. `kube-token` prints a short-lived Kubernetes `ExecCredential` for use as a credential plugin; `kubeconfig add` writes an `ankra-*` context (exec-based by default, or `--embed-token`) with atomic `0600` writes that leave foreign entries untouched and use collision-safe context naming.

```bash theme={null}
ankra cluster kubeconfig add --cluster prod --use
kubectl get pods
```

## Cluster metrics

`ankra cluster metrics query | query-range` proxies a PromQL query (instant or range) to the cluster's Prometheus metrics source, with `table | json | yaml` output for ad-hoc inspection and CI.

```bash theme={null}
ankra cluster metrics query 'up'
ankra cluster metrics query-range 'rate(node_cpu_seconds_total[5m])' --range 6h --step 5m
```

## Support requests

`ankra support create | list | get | comment | attach | close` opens and tracks Ankra support requests from the CLI, including image/screenshot attachments. Each request goes through a mandatory AI review; use `--force` to submit a request the reviewer flags.

## Stack profiles

`ankra stack-profiles list | export-iac | import` manages reusable, organisation-level stack profiles as `ClusterInfrastructureAsCode` YAML (export a profile version, import one from a file). The family has since grown much further - drafts, suggestions, sharing, demos - see the [current reference](/reference/cli/stack-profiles).

## Validate and stage cluster YAML

* `ankra cluster validate -f cluster.yaml` runs the offline `apply --dry-run` checks plus server-side chart-existence, plaintext-secret, and parent-reference validation, with CI-friendly exit codes and `--strict-secrets`.
* `ankra cluster draft -f cluster.yaml` stages every stack as a reviewable draft instead of applying it - nothing is deployed by the command.
* `ankra cluster apply` gained offline dependency-tree and referenced-file validation, and `--dry-run` for `apply` / `delete cluster` is fully offline (no token), so it drops into pre-merge CI.

## Self-update and beta channel

`ankra upgrade` downloads, SHA-256-verifies, and atomically swaps the binary, with `--version` pinning for upgrade, downgrade, and rollback (`--allow-unverified` for releases that predate published checksums). `ankra config beta enable|disable|status` opts into pre-release builds with semver-aware precedence (a stable release outranks its release candidates).

## Cloud create parity and OVH commands

* `cluster ovh | upcloud | hetzner create` gained `--external-cloud-provider` (per-cloud CCM + CSI) and `--include-networking` (Traefik + cert-manager), installed by default and reconciled directly, and committed to Git when `--gitops-credential-name` / `--gitops-repository` / `--gitops-branch` are set.
* OVH reached web-UI parity: `ovh regions`, `ovh stop` / `ovh start`, `ovh access-info`, `ovh ssh-keys get|set`, `ovh node-group labels|taints`, and `ovh control-plane` / `ovh nodes`.

## Operations and machine-readable output

`ankra cluster operations list` gained `--watch` / `-w` (with a configurable `--interval`), and both `operations list` and `operations steps` gained `-o json|yaml`. A shared `-o json|yaml` flag now spans the commands that read or return data.

## Security

`ankra cluster encrypt manifest | addon` no longer produces files that only look encrypted: a dotted `--key` (e.g. `data.password`) is normalised to its last segment, and after every encryption the CLI verifies the target value is real `ENC[...]` ciphertext - hard-failing before any write or stack PATCH when SOPS encrypted nothing.

**v0.2.5**

# Variables, Live-Cluster SOPS, Dependency Parents, and Multi-Org

Rounds out stack CRUD from the CLI: template variables at every scope, SOPS encryption against live clusters, dependency-parent editing, read/delete commands, a global organisation override, and offline-installable Agent Skills.

## Variables (org / cluster / stack scopes)

Full CRUD for the template variables substituted into stack manifests and addon values at deploy time, at three scopes:

* `ankra org variables list|get|set|delete` - organisation-wide, available to every cluster.
* `ankra cluster variables list|get|set|delete [--cluster <name|id>]` - per cluster; shadows org variables on that cluster.
* `ankra cluster stacks variables list|get|set|delete <stack>` - per stack; the most specific scope.

`set` is an upsert (create or update). Values can be read from stdin with `-` for piping secrets, `list` / `get` support `-o json|yaml`, and `delete` prompts for confirmation (`--yes` to skip). Resolution at deploy time is **stack > cluster > organisation** - a more specific scope shadows less specific ones for the same name.

## SOPS encrypt/decrypt against live clusters

`ankra cluster encrypt` and `ankra cluster decrypt` now operate directly on a live cluster, with no local `cluster.yaml` required.

* `ankra cluster encrypt manifest <name> --key <key> [--cluster <name|id>]`
* `ankra cluster encrypt addon --name <addon> --key <key> [--cluster <name|id>] [--stack <stack>]`
* `ankra cluster decrypt manifest <name> [--cluster <name|id>]`
* `ankra cluster decrypt addon --name <addon> [--cluster <name|id>] [--stack <stack>]`

Cluster mode fetches the current content, runs it through the SOPS API, and (for encrypt) pushes the result back via the partial-stack PATCH with `encrypted_paths` updated. The `-f cluster.yaml` file mode is unchanged for GitOps workflows; the two modes are mutually exclusive and cluster mode is the default. `decrypt addon` is new, bringing the addon variant to parity with manifests.

## Dependency parents on upgrade

`ankra cluster addons upgrade` and `ankra cluster manifests upgrade` now edit the dependency parents that control deployment ordering inside a stack, without re-applying the whole `cluster.yaml`:

* `--add-parent name=<n>,kind=<manifest|addon>` - repeatable; `kind` defaults to `manifest`.
* `--remove-parent name=<n>,kind=<manifest|addon>` - repeatable; removing the last parent clears the link.
* `--set-parent name=<n>,kind=<manifest|addon>` - replaces ALL parents; mutually exclusive with `--add-parent` / `--remove-parent`.

## Read and delete

* `ankra cluster addons values <name>` - print an addon's current Helm values (decoded; `-o raw` for the base64 form).
* `ankra cluster manifests get <name>` - print a manifest's current YAML (decoded; `-o raw` for the base64 form).
* `ankra cluster manifests delete <name>` - disconnect a manifest from its stack and remove its resources; the owning stack is resolved automatically and a confirmation prompt protects the operation (`--yes` to skip, `--dry-run` to preview).

## Run a command against another organisation

A global `--org <name|id>` flag (or the `ANKRA_ORG` environment variable) runs a single command against any organisation you belong to, without changing your selected organisation:

```bash theme={null}
ankra --org "Acme Corp" cluster list
export ANKRA_ORG="Acme Corp"   # scope a whole shell session
```

The override is per request and never changes the `ankra org switch` selection. You must be an active member of the target organisation.

## Install Ankra Agent Skills

`ankra skills` installs the curated Ankra Agent Skills into a Cursor/Claude skills directory. The skills are embedded in the binary, so installation works offline and is versioned with the release.

```bash theme={null}
ankra skills list                  # list available skills (marks installed ones)
ankra skills install               # install all into ~/.cursor/skills (personal)
ankra skills install --project .   # install into ./.cursor/skills (project)
ankra skills install ankra-gitops  # install only named skills
ankra skills uninstall             # remove all Ankra skills
```

Use `--force` to overwrite existing skills and `--source <dir>` to install from a local directory instead of the embedded copy. This is separate from `ankra openclaw skill`, which generates a per-cluster SKILL.md.

**v0.2.4**

# Surgical Addon and Manifest Upgrades

Two new subcommands for in-place updates that go through the same partial-stack endpoint as the UI. Atomic, locked, single git commit per invocation.

## Addon Upgrade

* `ankra cluster addons upgrade <addon> --chart-version <version>` - bump the chart version.
* `ankra cluster addons upgrade <addon> --set <key>=<value>` - mutate a single Helm values field (helm-style; supports dotted paths, `[idx]` indexing, and `[key=value]` list selectors such as `env[name=LOG_LEVEL].value`).
* `ankra cluster addons upgrade <addon> --values-from-file <path>` - replace the entire values document.
* `ankra cluster addons upgrade <addon> --registry-name`, `--registry-url`, `--registry-credential-name` - atomically retag the addon's registry.
* `ankra cluster addons upgrade <addon> --namespace <new>` - destructive Helm reinstall in a new namespace; requires `--yes` or an interactive confirmation.

`--set` and `--values-from-file` are mutually exclusive: `--set*` MUTATES the existing values document, `--values-from-file` REPLACES it. Use `--set-string` to force a value to remain a string, and `--set-file key=path` to load a value from a file.

## Manifest Upgrade

* `ankra cluster manifests upgrade <manifest> --from-file <path>` - replace the manifest content.
* `ankra cluster manifests upgrade <manifest> --manifest -` - read manifest YAML from stdin.
* `ankra cluster manifests upgrade <manifest> --set <key>=<value>` - mutate a single path in the manifest YAML (helm-style; supports dotted paths, `[idx]` indexing, and `[key=value]` list selectors such as `containers[name=app].image`).
* `ankra cluster manifests upgrade <manifest> --target-kind <kind> --target-name <name>` - with `--set`, pick which document to edit when the manifest holds multiple Kubernetes resources.
* `ankra cluster manifests upgrade <manifest> --namespace <new>` - change the manifest's namespace.

`--set*` MUTATE the existing manifest and are mutually exclusive with `--from-file` / `--manifest -`, which REPLACE it. Use `--set-string` to force a value to remain a string, and `--set-file key=path` to load a value from a file.

## Addon and manifest field selectors

Both `addons upgrade` and `manifests upgrade` `--set` paths can address a list item by a stable field instead of a numeric index - for example `env[name=LOG_LEVEL].value=debug` or `spec.template.spec.containers[name=app].image=nginx:1.27`. A selector that matches nothing fails with a clear error rather than guessing.

## Common Options

* `--cluster <name|id>` - defaults to the active selection.
* `--stack <name>` - addons only, required when the same addon name exists in multiple stacks. Manifest names are globally unique on a cluster, so `manifests upgrade` has no `--stack` flag.
* `--dry-run` - print before/after without writing.
* `-o json|yaml` - machine-readable output (the `--dry-run` envelope is `{before, after, notices}`).

## Example: bump `image.tag` for the website addon

```bash theme={null}
ankra cluster addons upgrade website \
  --set image.tag=1.0.146 \
  --cluster website-demo
```

## Example: bump a Deployment image tag in a manifest

```bash theme={null}
ankra cluster manifests upgrade web \
  --set 'spec.template.spec.containers[name=app].image=nginx:1.27' \
  --cluster website-demo
```

**v0.2.0**

# Helm, Kubernetes Resources & Security Hardening

Helm management, Kubernetes resource access, direct cluster selection, and client hardening.

## Helm Release Commands

Commands for managing Helm releases in the active cluster:

* `ankra cluster helm releases` - List Helm releases (`--namespace`, `--all-namespaces`, `--output json`)
* `ankra cluster helm uninstall <release> --namespace <ns>` - Uninstall a Helm release

## Helm Registry Commands

* `ankra helm registries list` - List Helm registries
* `ankra helm registries get <name>` - Get registry details
* `ankra helm registries create --name <name> --url <url>` - Create a registry
* `ankra helm registries delete <name>` - Delete a registry

## Helm Credential Commands

* `ankra helm credentials list` - List registry credentials
* `ankra helm credentials create --name <name>` - Create a credential with secure prompts
* `ankra helm credentials delete <name>` - Delete a credential

## Kubernetes Resource Commands

Commands for accessing Kubernetes resources in the active cluster:

* `ankra cluster pods` - List pods (`--namespace`, `--all-namespaces`, `--output json`)
* `ankra cluster resources <kind>` - Get resources by kind (`--namespace`, `--name`, `--output json`)
* `ankra cluster logs <pod>` - Stream pod logs (`--namespace`, `--container`, `--follow`, `--tail`, `--previous`)

## Cluster Selection & Info

* `ankra cluster select <name>` - Select a cluster directly by name without the interactive picker
* `ankra cluster info [name]` - Show cluster details (defaults to selected cluster; replaces `cluster get`)

## Security & Reliability

* HTTP client timeouts and response body size limits
* URL encoding for all API path and query parameters
* Config file permissions restricted to owner-only (0600)
* Machine ID hashed with SHA-256
* Browser URL validation before opening

**v0.1.129**

# Node Groups, UpCloud & OVH

Node group management commands and new UpCloud/OVH commands for cluster and credential management.

## Node Group Commands

Available for all three providers (`hetzner`, `ovh`, `upcloud`):

* `ankra cluster <provider> node-group list <cluster_id>` - List node groups
* `ankra cluster <provider> node-group add <cluster_id> --name <name> --instance-type <type> --count <n>` - Add a group
* `ankra cluster <provider> node-group scale <cluster_id> <group_name> <count>` - Scale a group
* `ankra cluster <provider> node-group upgrade <cluster_id> <group_name> <instance_type>` - Upgrade instance type
* `ankra cluster <provider> node-group delete <cluster_id> <group_name>` - Delete a group

## UpCloud Commands

**Credentials**:

* `ankra credentials upcloud list` - List UpCloud API credentials
* `ankra credentials upcloud create --name <name>` - Create credential with secure token prompt
* `ankra credentials upcloud ssh-key list` - List SSH key credentials
* `ankra credentials upcloud ssh-key create --name <name> --generate` - Create SSH key

**Clusters**:

* `ankra cluster upcloud create` - Create an UpCloud cluster
* `ankra cluster upcloud deprovision <cluster_id>` - Deprovision a cluster
* `ankra cluster upcloud workers <cluster_id>` - Get worker count
* `ankra cluster upcloud scale <cluster_id> <count>` - Scale workers
* `ankra cluster upcloud k8s-version <cluster_id>` - Get Kubernetes version
* `ankra cluster upcloud upgrade <cluster_id> <version>` - Upgrade Kubernetes version

## OVH Commands

**Credentials**:

* `ankra credentials ovh list` - List OVH API credentials
* `ankra credentials ovh create --name <name> --project-id <id>` - Create credential with secure prompts
* `ankra credentials ovh ssh-key list` - List SSH key credentials
* `ankra credentials ovh ssh-key create --name <name> --generate` - Create SSH key

**Clusters**:

* `ankra cluster ovh create` - Create an OVH cluster
* `ankra cluster ovh deprovision <cluster_id>` - Deprovision a cluster
* `ankra cluster ovh workers <cluster_id>` - Get worker count
* `ankra cluster ovh scale <cluster_id> <count>` - Scale workers
* `ankra cluster ovh k8s-version <cluster_id>` - Get Kubernetes version
* `ankra cluster ovh upgrade <cluster_id> <version>` - Upgrade Kubernetes version

**v0.1.127**

# OVH Cloud Support

OVH Cloud commands for cluster and credential management.

## OVH Credential Commands

* `ankra credentials ovh list` - List OVH API credentials
* `ankra credentials ovh create --name <name> --project-id <id>` - Create credential with secure prompts
* `ankra credentials ovh ssh-key list` - List SSH key credentials
* `ankra credentials ovh ssh-key create --name <name> --generate` - Create SSH key

## OVH Cluster Commands

* `ankra cluster ovh create` - Create an OVH cluster with configurable control planes, workers, networking, and gateway
* `ankra cluster ovh deprovision <cluster_id>` - Deprovision a cluster
* `ankra cluster ovh workers <cluster_id>` - Get worker count
* `ankra cluster ovh scale <cluster_id> <count>` - Scale workers
* `ankra cluster ovh k8s-version <cluster_id>` - Get Kubernetes version
* `ankra cluster ovh upgrade <cluster_id> <version>` - Upgrade Kubernetes version

**v0.1.125**

# SOPS Encryption & API Tokens

New SOPS encryption commands and API token management.

## SOPS Encryption

* `ankra cluster sops-config` - Display the SOPS encryption configuration
* `ankra cluster encrypt manifest <name> --key <key> -f <file>` - Encrypt a manifest key
* `ankra cluster encrypt addon --name <addon> --key <key> -f <file>` - Encrypt an addon key
* `ankra cluster decrypt manifest <name> -f <file>` - Decrypt a manifest

## API Tokens

* `ankra tokens list` - List API tokens
* `ankra tokens create <name>` - Create a token
* `ankra tokens revoke <id>` - Revoke a token
* `ankra tokens delete <id>` - Delete a revoked token


# Bitbucket Cloud Integration
Source: https://docs.ankra.ai/integrations/bitbucket-cloud

Connect Bitbucket Cloud workspaces for GitOps configuration management, Ankra Pipelines, and AI code review on pull requests

Your code and cluster configuration live in Bitbucket Cloud, and you want Ankra to sync clusters from it, run pipelines on it, and review its pull requests. Ankra connects to a Bitbucket Cloud workspace over OAuth, and registers the webhooks it needs itself.

A Bitbucket Cloud connection powers:

* **Cluster [GitOps](/concepts/gitops)** - Ankra stores each cluster's configuration in a repository and syncs your pushes back to the cluster.
* **[Ankra Pipelines](/guides/ankra-pipelines)** - runs on pushes, tags and pull requests.
* **[AI code review](/platform/ai-code-review)** - reviews on pull requests and replies to `@ankraai` mentions - see [Ankra AI on pull requests](#ankra-ai-on-pull-requests).

Applications, PR previews and merge when green are GitHub only. [Git Providers](/integrations/git-providers) compares the three providers feature by feature.

***

## Prerequisites

You need:

* A Bitbucket Cloud workspace you own or are an admin of.
* Permission to authorise OAuth consumers for that workspace.
* The `credentials.write` permission in Ankra to connect or reconnect an organisation credential. Connecting your own personal account needs no extra permission.

Ankra requests the following OAuth scopes:

* `account` - read your account and list the workspaces it belongs to.
* `repository` - read the repositories your account can see, their files and their branches.
* `repository:write` - push the commits that store stack configuration.
* `repository:admin` - add webhooks to a repository, which Bitbucket requires alongside `webhook`.
* `pullrequest` - read pull requests and comment on them for AI code review and mention replies, and subscribe webhooks to pull request events.
* `webhook` - register, update and remove the repository webhooks that deliver pushes and pull request events to Ankra.

### Granting the pull request permission

Bitbucket gives a token the permissions of the OAuth consumer it was issued through, not the scopes the authorisation request lists. The Ankra OAuth consumer therefore needs Bitbucket's **Pull requests: Read** permission, and a credential connected before the consumer carried it gains the `pullrequest` scope only when it is reconnected.

Until a credential is reconnected, the webhooks it registers subscribe `repo:push` alone. GitOps sync, push pipelines and tag pipelines keep working, while AI review, `@ankraai` mention replies and pull request pipelines receive nothing from its repositories.

To grant it, press **Reconnect** on the organisation credential's page, next to **Sync Repositories**. A personal connection shows **Reconnect** under **Profile → General → Bitbucket Cloud Connection** only while it is broken; one that still works is renewed by **Disconnect** followed by **Connect Bitbucket**. Ankra then re-subscribes the credential's webhooks to the pull request events on their next check - within five minutes for a repository a cluster syncs from, within an hour for one hooked only for AI review or pipelines. No webhook needs editing by hand.

> [!NOTE]
>
> If Bitbucket's consent screen lists no access to pull requests, the consumer does not carry the permission yet and a reconnect grants nothing new. [Contact support](/platform/support).

***

## Connecting Bitbucket Cloud

**1. Open the Credentials page**

In Ankra, navigate to **Organisation → Credentials → Add credential**.

**2. Pick Bitbucket Cloud**

Select **Bitbucket Cloud** from the source-control providers and click **Continue to Bitbucket**.

**3. Authorise the Ankra OAuth consumer**

Bitbucket will redirect you to the consent screen. Review the requested access and click **Grant access**. Finish in the same browser, signed in to Ankra as the user who started the connection: Ankra refuses a connection completed by anyone else, or in a browser with no Ankra session, with `state_session_mismatch`.

**4. Verify the credential**

You land on the new credential's page, with a banner confirming the connection. The repository sync starts straight away: it lists every workspace your Bitbucket account belongs to, and **Workspaces & Repositories** fills within a minute. **Sync Repositories** runs it again.

**Connect workspace** on the Bitbucket card under **AI → Settings → Connections → Source control & AI review** starts the same flow.

### Connecting your personal account

Each member can also link their own Bitbucket Cloud account for traceable commits, under **Profile → General → Bitbucket Cloud Connection → Connect Bitbucket**. A personal credential gets its own repository sync and appears in the GitOps credential picker beside the organisation's credentials, marked as personal.

An organisation credential and a personal credential connected by the same Bitbucket account share a name. A cluster records its credential by name and the organisation credential takes precedence, so the picker shows such a personal credential as **Uses the organisation credential** and does not let you select it.

***

## Connecting a repository to a cluster

**1. Open the cluster's GitOps settings**

Navigate to the cluster, click **Settings → GitOps**.

**2. Select the credential**

The credential picker lists the organisation's GitHub and Bitbucket Cloud credentials together, each with its provider icon and scope. Pick the Bitbucket Cloud credential.

**3. Choose the repository and branch**

Choose the repository, then the branch from the repository's own branch list. Picking a repository selects its default branch.

**4. Connect**

Click **Connect Repository**. Ankra writes a `clusters/{cluster-name}-{cluster-short-id}/` folder to the repository on the next sync and registers the repository's webhook - there is no manual webhook setup.

A Stack's **Connect repository** dialog, shown when you create a Stack on a cluster with no repository, offers the same Bitbucket Cloud credentials, repositories and branches, and so does the GitOps step of the cloud cluster create wizards. The cluster's **View source** links open its folder on bitbucket.org at the connected branch.

A branch whose name contains a slash, such as `release/2026-10`, works too. The agent reads add-on values files at that branch's commit, and a branch that no longer exists fails the deploy with the branch named rather than deploying the chart's defaults.

***

## Webhooks

Ankra registers the webhooks itself, one per repository and credential. A repository gets one when:

* a cluster's GitOps connection uses it;
* it is connected to [Ankra Pipelines](/guides/ankra-pipelines#connect-a-repository-push-see-the-run) with the credential, unless the organisation already has a webhook on it;
* AI review or mention replies are switched on for it - on the credential's **All repositories** row, which covers every repository the credential can see, or on a repository rule.

Under an **All repositories** row, a repository the credential's repository sync discovers later gets its webhook on the credential's next check, which runs every five minutes. Webhooks are only ever added: switching a capability off or disconnecting a repository leaves the webhook in place, because it may still serve GitOps or pipelines, and Ankra declines the deliveries nothing asked for.

* Per-credential URL: `{platform-base-url}/webhooks/bitbucket-cloud/{credential-id}`.
* Events: `repo:push`, plus `pullrequest:created`, `pullrequest:updated`, `pullrequest:comment_created`, `pullrequest:fulfilled` and `pullrequest:rejected` when the credential grants the `pullrequest` scope. Without that scope the webhook subscribes `repo:push` alone - see [Granting the pull request permission](#granting-the-pull-request-permission).
* When several of the organisation's credentials have a webhook on the same repository, only one of them subscribes the pull request events, so a pull request is reviewed and a mention answered once.
* Every delivery is checked against the webhook's secret. A tag push starts tag pipelines and syncs no cluster.

Ankra does not show individual deliveries. Bitbucket keeps each webhook's request history under the repository's **Repository settings → Webhooks**.

***

## Ankra AI on pull requests

Ankra AI can review Bitbucket Cloud pull requests automatically and answer when someone mentions `@ankraai` in a pull request comment, with the change as context.

Both are off until an organisation admin switches them on, under **AI** → **Settings** → **Connections** → **Source control & AI review** → **Bitbucket**, on the workspace's **All repositories** row or on a rule for an individual repository. [AI code review](/platform/ai-code-review) covers every switch, the review model, the review instructions, and what the review posts.

Both need the pull request events, so the credential must grant the `pullrequest` scope - see [Granting the pull request permission](#granting-the-pull-request-permission). On Bitbucket Cloud:

* **Review drafts** applies: a draft pull request is skipped until it is marked ready, and marking it ready starts the review.
* A mention reply is posted as a reply to the comment that asked.
* Bitbucket has no comment reactions, so no 👀 acknowledges a mention. The reply is the first sign Ankra picked it up.
* In **Agent** mode, Ankra cannot open a pull request on Bitbucket, so a reply proposes the fix with a branch name and a commit message instead of offering one.

PR previews cannot be switched on for Bitbucket Cloud repositories: the Bitbucket rows carry no preview switch.

***

## Disconnecting

* **An organisation credential** is deleted from its card under **Organisation → Credentials**. Ankra first removes the webhooks it registered from each repository, while it still holds the token, then deletes the stored token and the credential. Connect any cluster that syncs through the credential to another credential first: a cluster records its credential by name and cannot sync without it.
* **A personal credential** is disconnected with **Disconnect** under **Profile → General → Bitbucket Cloud Connection**, which removes its webhooks and token the same way.

If Bitbucket refuses a webhook's removal, because access was already revoked for example, Ankra deletes its own record and leaves the webhook on the repository. Remove it under the repository's **Repository settings → Webhooks**.

***

## Limitations

* Only HTTPS is supported. SSH keys are not used for Bitbucket Cloud; Ankra authenticates with the credential's OAuth access token and refreshes it before it expires.
* When someone else pushes to the branch while Ankra is writing configuration, Ankra retries against the new branch head a few times before it reports a conflict.
* PR previews and merge when green are not available on Bitbucket Cloud - see [Git Providers](/integrations/git-providers).

***

## Troubleshooting

A connection's outcome comes back as `?bitbucket_connected=<credential-name>` or `?bitbucket_error=<code>` and is shown as a banner: on the credential's page or **Organisation → Credentials** for an organisation credential, and on **Profile → General**, or the page a personal reconnect started from, for a personal one.

* **`access_denied`** - the connection was declined on Bitbucket's consent screen. Start it again and grant access.
* **`state_session_mismatch`** - the connection was finished by a different Ankra user than the one who started it, or in a browser with no Ankra session, for example a consent link forwarded to someone else. Nothing was connected. Start again from Ankra while signed in, and approve in the same browser.
* **`credential_create_failed`** - Bitbucket authorised the connection, but Ankra could not store the credential. Try again.
* Any other code is Bitbucket's own OAuth error, shown as it arrived.

Other symptoms:

* **Pushes sync, but AI review, mention replies and pull request pipelines never start** - the credential lacks the `pullrequest` scope. Reconnect it, as in [Granting the pull request permission](#granting-the-pull-request-permission). If they still do not start, check the switches under [Ankra AI on pull requests](#ankra-ai-on-pull-requests).
* **The credential shows `Down`** - Bitbucket refused the credential's refresh token, typically because access was revoked. Reconnect the credential to mint a fresh one.
* **A push fails with "Bitbucket authentication failed. Your token may have expired - reconnect your Bitbucket account in settings."** - reconnect the credential the cluster uses. The cluster's GitOps page and a failed Stack deploy offer **Reconnect Bitbucket**, which starts the flow for that credential, organisation or personal.
* **A push fails with "Bitbucket rate limit hit while pushing."** - Bitbucket limits API requests per user and hour. Wait a minute and try again.
* **Reconnect is disabled** - reconnecting an organisation credential needs `credentials.write`, and the button's tooltip says who can. You can still reconnect your own personal credential.
* **No repositories visible** - press **Sync Repositories** on the credential's page. A workspace whose listing Bitbucket refuses, such as one behind an IP allowlist, is skipped while the others still sync. If nothing appears, the OAuth user may lack `repository` scope on the workspace: reconnect the credential.


# Git Providers
Source: https://docs.ankra.ai/integrations/git-providers

What Ankra supports on GitHub, GitLab and Bitbucket Cloud - cluster GitOps, Applications, Ankra Pipelines triggers, PR previews, AI code review and merge when green - in one table.

Before you connect a repository, you need to know whether the features you want work on the Git host you use. Ankra connects to GitHub, GitLab and Bitbucket Cloud, and they do not all support the same things. This table is the single place that says which.

## What works where

| | GitHub | GitLab | Bitbucket Cloud |
| - | - | - | - |
| How you connect | The Ankra GitHub App | An access token, for GitLab.com or a self-managed instance | OAuth, per workspace |
| Webhooks | Delivered by the App - nothing to register | You add a webhook per project or group | Ankra registers them for you |
| Cluster [GitOps](/concepts/gitops) repository | Yes | No | Yes |
| [Applications](/concepts/applications) | Yes | No | No |
| [Ankra Pipelines](/guides/ankra-pipelines) triggers | Push, tag, pull request | Push, tag, merge request | Push, tag, pull request |
| [PR previews](/guides/pr-preview-environments) | Yes, for Applications | No | No |
| [AI code review](/platform/ai-code-review) | Yes | Yes | Yes |
| `@ankraai` mention replies | Yes | Yes | Yes |
| Agent-mode reply offers to open the fix as a pull request | Yes | No - it proposes a branch name and commit message | No - it proposes a branch name and commit message |
| [Merge when green](/guides/ankra-pipelines#what-a-pull-request-gets) | Yes | No | No |
| Related repositories for AI review | Yes | No | No |

Every AI capability is off on a new connection until an organisation admin switches it on. See [AI code review](/platform/ai-code-review).

## Events Ankra reads

| Provider | Events | What they drive |
| - | - | - |
| GitHub | `push`, `pull_request`, `issue_comment`, `pull_request_review_comment`, `workflow_run`, `repository` | GitOps sync, pipeline runs, AI review and mention replies, application builds |
| GitLab | Push, Tag push, Merge request, Comments | Pipeline runs, AI review and mention replies |
| Bitbucket Cloud | `repo:push`, `pullrequest:created`, `pullrequest:updated`, `pullrequest:comment_created`, `pullrequest:fulfilled`, `pullrequest:rejected` | GitOps sync, pipeline runs, AI review and mention replies |

On Bitbucket Cloud the pull request events need the credential to grant the `pullrequest` scope. See [Granting the pull request permission](/integrations/bitbucket-cloud#granting-the-pull-request-permission).

## Not supported

* **Bitbucket Data Center** and other self-hosted Bitbucket servers. A cluster spec naming `bitbucket_dc` is refused.
* **GitLab as a cluster's GitOps repository.** Keep cluster configuration on GitHub or Bitbucket Cloud. GitLab repositories can still run Ankra Pipelines and get AI review.

## Connect a provider

> [card] [GitHub](/integrations/github)
>
> Install the Ankra GitHub App.

> [card] [GitLab](/integrations/gitlab)
>
> Connect a token and register the webhook.

> [card] [Bitbucket Cloud](/integrations/bitbucket-cloud)
>
> Authorise a workspace over OAuth.


# GitHub Integration
Source: https://docs.ankra.ai/integrations/github

Install the Ankra GitHub App to keep cluster configuration in a GitHub repository, build Applications, run Ankra Pipelines, and have Ankra AI review and answer on pull requests.

You want your cluster configuration in a GitHub repository you can review and roll back, and you want Ankra to work where your team already works: on pull requests. Ankra connects to GitHub through the **Ankra GitHub App**. One installation covers the repositories you grant it, and every feature below uses it.

GitHub has the widest support of the three Git providers. [Git Providers](/integrations/git-providers) compares it with GitLab and Bitbucket Cloud feature by feature.

## What the GitHub App powers

* **Cluster [GitOps](/concepts/gitops)** - Ankra writes each cluster's Stacks, add-on values and manifests to a folder in your repository and syncs changes you push back to the cluster. How the folder is laid out and how sync works is on the GitOps page.
* **[Applications](/concepts/applications)** - Ankra opens a setup pull request with a Dockerfile, chart and pipeline, builds on push, and deploys.
* **[Ankra Pipelines](/guides/ankra-pipelines)** - runs on pushes, tags and pull requests.
* **[AI code review](/platform/ai-code-review)**, `@ankraai` mention replies, PR previews and merge when green - see [Ankra AI on pull requests](#ankra-ai-on-pull-requests).

***

## Connect a repository to a cluster

**1. Open the cluster's GitOps settings**

Go to your cluster and click **Settings** → **GitOps**.

**2. Select the credential**

Pick the GitHub credential for the App installation that can reach your repository. If you have not installed the Ankra GitHub App yet, Ankra offers **Install GitHub App**; GitHub then asks which repositories the App may access.

**3. Choose the repository and branch**

Choose the repository, then the branch from the repository's own branch list.

**4. Connect**

Click **Connect Repository**. Ankra writes the cluster's folder to the repository and keeps it in sync from then on. GitHub delivers the App's webhooks, so there is nothing to register by hand.

To see what changed, open the cluster's **GitOps** page for the sync status and recent commits, or the repository's own history on GitHub. [GitOps](/concepts/gitops) explains the sync in both directions, conflicts, and how to monitor it.

***

## Ankra AI on Pull Requests

The Ankra GitHub App can also take part in the pull requests of every repository it is installed on. The capabilities are switched on per installation under **AI** → **Settings** → **Connections** → **Source control & AI review** → **GitHub**, and each can be overridden for an individual repository with a repository rule.

[AI code review](/platform/ai-code-review) is the canonical guide to those switches: what each one does, how repository rules layer over the installation-wide defaults, which model a review runs on, what the review posts, and when one is skipped. This page covers what is specific to GitHub.

| Switch | GitHub specifics |
| - | - |
| **AI review** | For a repository connected to [Ankra Pipelines](/guides/ankra-pipelines), the review resolves the newest pipeline run of the reviewed commit before it falls back to a GitHub check run, and cites the run's own facts - failing step, findings, gate verdict, build digest - see [What a pull request gets](/guides/ankra-pipelines#what-a-pull-request-gets). |
| **Mention replies** | Answers when someone mentions `@ankraai` in a pull request comment, with the change as context. See [Ask Ankra in a comment](#ask-ankra-in-a-comment) below. |
| **PR previews** | GitHub only. Deploys a throwaway preview of an application's pull request build - see [PR preview environments](/guides/pr-preview-environments). |

### Turning It On

**1. Open the GitHub integration**

Go to **AI** → **Settings** → **Connections** → **Source control & AI review** and find the GitHub installation. Each installation has its own switches and AI mode.

**2. Choose the installation-wide switches**

On the **All repositories** row, turn on **AI review**, **Mention replies** and **PR previews** as needed. They apply to every repository the installation covers. **Merge when green** sits in the row's header next to **AI mode**, because it needs **Agent** mode to act; it has no per-repository rule.

**3. Add repository rules for exceptions**

Add a rule for a repository to give it its own switches. A rule replaces the installation-wide switches for that repository; remove the rule and the repository follows them again.

**Related repositories** sits at the bottom of each installation's panel and is GitHub-only, because the cross-repository search runs on GitHub code search. Use it to tell a review that two repositories belong together when nothing in your deploy already says so - a client and the API it calls, or a shared library and the service that consumes it. See [Relating two repositories directly](/platform/ai-code-review-cross-repo#relating-two-repositories-directly).

### Ask Ankra in a Comment

Mention **`@ankraai`** anywhere in a pull request comment or review comment, and Ankra AI replies on the pull request with the diff and the pull request's metadata as its context:

```text theme={null}
@ankraai why does this change bump the Prometheus retention?
@ankraai review this
@ankraai is the failing pipeline on this PR caused by the values change?
```

Ankra reacts to your comment with 👀 as soon as it picks the mention up, and the answer arrives as a new comment posted by `ankra-platform[bot]`. A mention always gets an answer while **Mention replies** is on: it is not subject to the draft, target-branch, and daily-budget rules that gate automatic reviews.

How far the answer goes depends on the integration's **AI mode**:

* **Ask** (the default) - the reply is read-only. Ankra explains, reviews, and points out problems in the diff, but changes nothing.
* **Agent** - when the fix is clear, the reply can propose the exact file changes and offer to open the fix as a pull request. Ankra still does not run code or execute platform actions from the comment thread.

Only comments written by people trigger a reply. Comments from bots and comments on plain issues are ignored.

### Merge when green

Mention **`@ankraai merge when green`** on a pull request and Ankra squash-merges it once its newest [Ankra Pipelines](/guides/ankra-pipelines) run has passed and nothing blocks it. The request expires after 24 hours, and a new push invalidates it.

It is off by default. An organisation admin turns it on with the **Merge when green** switch on the installation's row under **Settings** → **Connections** → **Source control & AI review**, and the installation's **AI mode** must be **Agent**. It works on GitHub only. The full list of conditions a merge checks is in [A human can say "merge when green"](/guides/ankra-pipelines#a-human-can-say-merge-when-green).

### A Mention Gets No Reply

* **Mention replies** is off for the installation, or a repository rule for that repository has it off. A rule overrides the installation-wide switch, so check both.
* The comment does not contain `@ankraai`. Mentioning the app's own login, `@ankra-platform`, is not enough.
* The comment was posted by a bot, or on an issue rather than a pull request.
* Ankra reacted with 👀 but never answered: the reply failed on Ankra's side. Nothing is posted in that case; mention `@ankraai` again to retry.
* No 👀 appeared at all: the mention never reached Ankra, so check the switches and the wording above before retrying.

***

## GitHub App Permissions

GitHub lists every permission the Ankra GitHub App requests on the install screen. The ones the features on this page depend on:

| Permission | What Ankra uses it for |
| - | - |
| **Contents** (read and write) | Read and write cluster configuration, and commit the files of an application's setup pull request |
| **Metadata** (read) | Read repository information |
| **Pull requests** (read and write) | Open setup pull requests, read pull requests for AI review, post reviews and mention replies, and merge when green. The [PR shepherd](/concepts/applications#the-pr-shepherd) merges a pull request Ankra opened only when merging is opted in |
| **Workflows** (read and write) | Commit a generated GitHub Actions workflow (`.github/workflows/*`). Only needed when a setup pull request carries one: a new application commits `.ankra/pipeline.yaml` by default instead |
| **Secrets** (read and write) | Install the private Ankra registry login (`ANKRA_REGISTRY_USERNAME`, `ANKRA_REGISTRY_PASSWORD`) that an application's GitHub Actions workflow publishes with |
| **Actions** (read and write) | Read an application's workflow runs and their logs |
| **Checks** (read and write) | Read the check runs on a commit when the AI review looks at its CI state, and publish the **Ankra PR shepherd** check on the pull requests Ankra opened |

The App also requests read access to issues, commit statuses, packages, security events, vulnerability alerts and artifact metadata, and write access to Actions variables, Pages and repository hooks.

The App subscribes to these webhook events: `push`, `pull_request`, `issue_comment`, `pull_request_review_comment`, `workflow_run` and `repository`.

> [!TIP]
>
> If the App was installed before a permission was added to it, GitHub shows a **review updated permissions** prompt on the installation. New permissions are not granted to an existing installation until an owner approves them - see [Permission Errors](#permission-errors).

***

## Revoking Access

To revoke the GitHub App, go to GitHub **Settings** → **Applications** → **Installed GitHub Apps**, find Ankra, click **Configure**, then **Uninstall** (or change which repositories it can access).

***

## Troubleshooting

### Sync Failures

If sync fails, check that the Ankra App still has access to the repository, that the configured branch exists, and that the files are valid YAML. [Monitoring sync status](/concepts/gitops#monitoring-sync-status) shows the last commit Ankra synced and any error.

### Permission Errors

1. Go to GitHub **Settings** → **Applications** → **Installed GitHub Apps** (or **Organization settings** → **GitHub Apps** for an organisation).
2. Find Ankra and click **Configure**.
3. Make sure the repository is in the **Selected repositories** list. A repository created after the App was installed is not covered unless the installation was granted all repositories.
4. If GitHub shows a **review updated permissions** prompt, approve it.

`HTTP 403 - Resource not accessible by integration` on the first write of an application setup means the installation cannot write to that repository at all: the repository is not granted, **Contents** or **Pull requests** is missing, or updated permissions are still awaiting approval. Fix it with the steps above, then re-run setup.

A missing **Workflows** permission reads differently: GitHub answers `refusing to allow a GitHub App to create or update workflow … without 'workflows' permission`, and Ankra's message names Workflows. It only happens when the setup pull request commits a `.github/workflows` file.

***

## Next Steps

* [Git Providers](/integrations/git-providers) - what works on GitHub, GitLab and Bitbucket Cloud
* [GitOps](/concepts/gitops) - the repository layout and how sync works
* [AI code review](/platform/ai-code-review) - every review switch and what a review posts
* [Ankra Pipelines](/guides/ankra-pipelines) - pipelines that run on your pushes and pull requests


# GitLab Integration
Source: https://docs.ankra.ai/integrations/gitlab

Connect a GitLab instance so Ankra AI can review merge requests and answer mentions, and so Ankra Pipelines run on pushes, tags and merge requests

> [!NOTE]
>
> GitLab connects with an access token rather than an app: you paste a token, Ankra shows you a webhook URL and secret, and you register the hook in GitLab yourself. GitLab.com and self-managed instances work the same way.

## What a GitLab connection powers

* **[AI code review](/platform/ai-code-review)** on merge requests, and replies when somebody mentions `@ankraai` in a merge request comment.
* **[Ankra Pipelines](/guides/ankra-pipelines)** runs on pushes, tags and merge requests. Cluster [GitOps](/concepts/gitops) sync supports GitHub and Bitbucket Cloud only, so a cluster's repository cannot live on GitLab.

Both ride the same credential and the same webhook. Every AI capability is off until an organisation admin turns it on. [Git Providers](/integrations/git-providers) compares what GitLab supports with GitHub and Bitbucket Cloud.

***

## Prerequisites

You need:

* A GitLab access token. A personal, group, or project access token all work.
* Permission to add a webhook to each project Ankra should watch, or to the group containing them.

### Token scopes

| Scope | Why |
| - | - |
| `read_api` | The minimum Ankra validates the token against, and enough to read merge requests and diffs. |
| `read_repository` | Read file contents when a review needs more than the diff. |
| `api` | Required for Ankra to **post** anything: the review comment and mention replies are writes, and `read_api` cannot make them. |

> [!WARNING]
>
> `read_api` is read-only. A token carrying only `read_api` and `read_repository` connects successfully and reads your merge requests, but every attempt to post a review comment fails. Use `api` unless you deliberately want a read-only connection.

A group access token scoped to the group that owns your projects is usually the least fiddly choice: one token, one webhook per project, and it survives people leaving.

***

## Connect GitLab

**1. Open the source-control connections**

In Ankra, go to **AI** → **Settings** → **Connections** and find **Source control & AI review** → **GitLab**.

**2. Fill in the credential**

* **Credential name** - optional, and worth setting when you connect more than one instance.
* **Instance URL** - leave empty for `https://gitlab.com`, or give the base URL of your self-managed instance, for example `https://gitlab.my-company.com`.
* **Access token** - the token from above.

Press **Connect**. Ankra validates the token against the instance before storing it, so a rejected token fails here rather than silently later.

**3. Copy the webhook URL and secret**

The credential now shows a webhook URL of the form `https://platform.ankra.app/webhooks/gitlab/<credential-id>` and a secret.

> [!WARNING]
>
> The secret is shown **once**, when the credential is created or its secret is regenerated. Copy it before you leave the page. If you lose it, regenerate it - you cannot read it back.

**4. Register the webhook in GitLab**

In the GitLab project, go to **Settings** → **Webhooks** → **Add new webhook**:

* **URL** - the webhook URL you copied.
* **Secret token** - the secret you copied.
* **Trigger** - tick **Merge request events**, **Comments**, **Push events**, and **Tag push events**.

Save, then press **Test** → **Merge request events**. A `200` means Ankra accepted the delivery.

Repeat per project, or add the hook once at group level under **Settings** → **Webhooks** to cover every project in the group.

**5. Turn on what you want**

A fresh connection does nothing. Switch on **AI review** and **Mention replies** on the credential's row, or on a rule for individual projects. See [AI code review](/platform/ai-code-review) for what each switch does.

***

## Which events do what

| GitLab event | What Ankra does with it |
| - | - |
| **Merge request events** | Runs the AI review when a merge request is opened or updated, and starts merge-request-triggered [Ankra Pipelines](/guides/ankra-pipelines) runs. |
| **Comments** | Answers a comment that mentions `@ankraai`. |
| **Push events** | Starts push-triggered [Ankra Pipelines](/guides/ankra-pipelines) runs. |
| **Tag push events** | Starts tag-triggered [Ankra Pipelines](/guides/ankra-pipelines) runs. A tag syncs no cluster. |

Every delivery is authenticated by comparing the `X-Gitlab-Token` header against the credential's stored secret. A delivery with the wrong secret is rejected with `401`; an event kind Ankra does not use is answered `200` so GitLab keeps the hook enabled.

***

## Rotate the webhook secret

**Regenerate secret** on the credential mints a new one and shows it once.

> [!WARNING]
>
> The old secret stops working immediately. GitLab keeps delivering with it until you update the hook, and those deliveries are rejected, so update the webhook in GitLab straight away.

***

## Repository paths and subgroups

Repository rules key on the project's full path, lowercased, including every subgroup - `my-group/my-subgroup/my-project`. Up to 20 levels of nesting are supported. The path is what appears in the project's URL after the instance host.

***

## Disconnect

**Disconnect** on the credential's row removes it. AI reviews, mention replies, and pipeline triggers through that credential all stop, and the webhook deliveries start being rejected. Remove the hook in GitLab too, so it stops retrying.

***

## Troubleshooting

| Symptom | What to check |
| - | - |
| **GitLab rejected the access token** on connect | The token is expired, revoked, or lacks `read_api`. For a self-managed instance, check the instance URL is the base URL with no path. |
| Webhook test returns `401` | The secret in GitLab does not match the credential's. Regenerate it in Ankra and paste the new one into the hook. |
| Webhook test returns `200` but no review appears | The delivery arrived and the capability is off. Turn **AI review** on for the credential or for that project, and check the [skip reasons](/platform/ai-code-review#when-a-review-does-not-run). |
| Reviews stopped after rotating the secret | The hook in GitLab still carries the old secret. Update it. |
| The review runs but nothing is posted | The token has `read_api` but not `api`, so Ankra can read the merge request and not comment on it. Replace the token with one carrying `api`. |
| Mentions go unanswered | **Mention replies** is a separate switch from **AI review**, the **Comments** trigger must be ticked on the webhook, and the comment must spell `@ankraai`. |
| Self-managed instance unreachable | Ankra calls your instance outbound over HTTPS. An instance behind a private network or an allow-list has to permit it. |

***

## Related

* [Git Providers](/integrations/git-providers) - what works on GitHub, GitLab and Bitbucket Cloud
* [AI code review](/platform/ai-code-review) - the switches, the review, and the mention lane
* [GitOps](/concepts/gitops) - how cluster configuration is stored and synced (GitHub and Bitbucket Cloud)
* [Git credentials](/platform/credentials/git) - where connected source-control credentials are listed
* [GitLab CI/CD pipeline](/guides/gitlab-cicd-pipeline) - building and publishing an application from GitLab CI


# Helm Registries
Source: https://docs.ankra.ai/integrations/helm-registries

Connect HTTP and OCI Helm registries to Ankra for chart deployment.

Ankra integrates with external Helm chart registries, allowing you to deploy charts from any HTTP or OCI-compatible repository. This integration enables your team to use both public charts and private internal charts through the Ankra platform.

***

## Supported Registry Types

> [card] HTTP Registries
>
> Traditional Helm repositories that serve an `index.yaml` file over HTTP/HTTPS.

> [card] OCI Registries
>
> Container registries that support Helm charts stored as OCI artifacts.

***

## HTTP Registry Integration

HTTP registries are traditional Helm repositories that serve charts via HTTP. They use an `index.yaml` file to list available charts and versions.

### How It Works

1. **Index Sync**: Ankra fetches the `index.yaml` from your registry URL
2. **ETag Optimization**: Uses HTTP headers to skip syncs when the index hasn't changed
3. **Chart Download**: New chart versions are downloaded and cached
4. **Metadata Extraction**: README, values.yaml, and JSON schema are extracted for the UI

### Supported Providers

| Provider | URL Format | Notes |
| - | - | - |
| ChartMuseum | `https://charts.example.com` | Self-hosted chart repository |
| Harbor before 2.8 (ChartMuseum) | `https://harbor.example.com/chartrepo/PROJECT` | Harbor 2.8 and later serve charts over OCI only - add them as an OCI registry, `oci://harbor.example.com/PROJECT` |
| Nexus | `https://nexus.example.com/repository/helm-hosted/` | Hosted repository type |
| JFrog Artifactory | `https://artifactory.example.com/artifactory/helm-local` | Local or virtual repo |
| AWS S3 | `https://bucket.s3.amazonaws.com/charts` | With static website hosting |

### Adding an HTTP Registry

**1. Navigate to Repositories**

Go to **Add-ons** → **Manage registries** and click **Add**.

**2. Enter Registry URL**

Enter your registry URL, e.g., `https://charts.example.com`

**3. Select Credential**

If authentication is required, select a credential from the dropdown.

**4. Save**

Click **Add** to connect the registry.

***

## OCI Registry Integration

OCI registries store Helm charts as container images using the OCI specification. This is the modern approach supported by Helm 3.8+.

### How It Works

1. **Manifest Fetch**: Ankra reads the OCI manifest to discover chart tags
2. **Layer Download**: Chart layers are downloaded from the registry
3. **Artifact Extraction**: The Helm chart is extracted from OCI layers
4. **Version Tracking**: Each tag is tracked as a chart version

### Supported Providers

| Provider | URL Format | Authentication |
| - | - | - |
| GitHub Container Registry | `oci://ghcr.io/ORG/charts` | Personal Access Token |
| Google Artifact Registry | `oci://REGION-docker.pkg.dev/PROJECT/REPO` | Service Account JSON |
| Amazon ECR | `oci://ACCOUNT.dkr.ecr.REGION.amazonaws.com` | AWS credentials |
| Azure Container Registry | `oci://REGISTRY.azurecr.io/charts` | Service Principal |
| Docker Hub | `oci://registry-1.docker.io/ORG` | Access Token |
| Harbor | `oci://harbor.example.com/PROJECT` | Username/Password |

### Adding an OCI Registry

**1. Navigate to Repositories**

Go to **Add-ons** → **Manage registries** and click **Add**.

**2. Enter OCI Registry URL**

Enter your registry URL with the `oci://` prefix, e.g., `oci://ghcr.io/your-org/charts`

**3. Select Credential**

If authentication is required, select a credential from the dropdown.

**4. Save**

Click **Add** to connect the registry.

> [!NOTE]
>
> OCI URLs must start with `oci://`. Ankra automatically detects the registry type based on the URL prefix.

***

## Sync Configuration

### Default Sync Interval

Registries sync automatically every **2 minutes** by default.

### Custom Sync Intervals

You can configure sync intervals per registry:

* **Minimum**: 60 seconds
* **Maximum**: 24 hours (86400 seconds)
* **Disabled**: Set to 0 to disable automatic sync

### Sync Behavior

**1. Check for Updates**

Ankra checks if the registry index has changed using ETag or Last-Modified headers.

**2. Detect New Versions**

New chart versions are identified by comparing against previously synced versions.

**3. Download Charts**

New versions are downloaded and stored. Metadata is extracted for browsing.

**4. Retry on Failure**

Failed downloads are automatically retried with exponential backoff.

***

## Authentication

Most registries require authentication. See [Credentials Integration](/platform/credentials) for setting up:

* Username/password authentication
* Token-based authentication
* Service account credentials

***

## Troubleshooting

### HTTP Registry Issues

| Issue | Cause | Solution |
| - | - | - |
| 404 Not Found | Wrong URL path | Verify the URL points to the repository root |
| 401 Unauthorized | Missing credentials | Add registry credential |
| Timeout | Network/firewall | Check connectivity to the registry |
| Empty chart list | Invalid index.yaml | Verify the registry is properly configured |

### OCI Registry Issues

| Issue | Cause | Solution |
| - | - | - |
| Invalid reference | Missing `oci://` prefix | Add `oci://` to the URL |
| Manifest unknown | Chart doesn't exist | Check the repository path |
| Unauthorized | Token expired | Refresh or recreate credentials |
| Tag not found | Version doesn't exist | Verify chart versions in the registry |

***

## API Integration

Use the Ankra API to manage registries programmatically:

```bash theme={null}
# List registries
curl -H "Authorization: Bearer $TOKEN" \
  https://platform.ankra.app/api/v1/org/helm/registries

# Add an HTTP registry: the body is a resource specification, and the
# key under spec (helm_http_registry or helm_oci_registry) says which kind
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"helm_http_registry": {"name": "my-charts", "url": "https://charts.example.com"}}}' \
  https://platform.ankra.app/api/v1/org/helm/registries

# Add an OCI registry
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spec": {"helm_oci_registry": {"name": "ghcr-charts", "url": "oci://ghcr.io/org/charts"}}}' \
  https://platform.ankra.app/api/v1/org/helm/registries
```

A private registry adds `"credential_name"` next to `url`, naming a registry credential created beforehand.

See the [API Reference](/api-reference/introduction) for complete documentation.


# Log Sources
Source: https://docs.ankra.ai/integrations/log-sources

Connect Grafana Loki, Elasticsearch or OpenSearch so Ankra can search historical logs and power log-aware AI troubleshooting

> [!NOTE]
>
> Log sources let Ankra query your aggregated log store through the cluster agent. This powers the **Search** tab on the cluster Logs page and the AI Assistant's `query_logs` / `get_log_labels` tools.

> [!TIP]
>
> No log store to connect? [Ankra hosted logs](/guides/hosted-logs) keeps a cluster's container logs for 7 days with nothing to install. A log source you connect takes precedence: while one is connected, log history searches it instead.

## Why Connect a Log Source?

When you connect a log source to Ankra:

* **Historical log search** - Query logs across pods and namespaces without leaving the cluster view
* **AI-powered troubleshooting** - Ankra AI can search Loki, Elasticsearch or OpenSearch during incident analysis
* **Complements live streaming** - Use **Live stream** for tailing current pod output; use **Search** for time-ranged queries over your log store
* **Agent-mediated access** - Queries run from inside your cluster, so in-cluster Loki/Elastic endpoints and external SaaS endpoints both work when the agent can reach them

***

## Supported Providers

| Provider | Typical in-cluster endpoint | Auth |
| - | - | - |
| Grafana Loki | `http://loki-gateway.monitoring.svc:80` | Bearer token; optional `X-Scope-OrgID` for multi-tenant Loki / Grafana Cloud |
| Elasticsearch | `https://elasticsearch.logging.svc:9200` | API key (recommended) or basic auth |
| OpenSearch | `https://opensearch.logging.svc:9200` | Bearer token or basic auth |

> [!WARNING]
>
> Use **index-scoped** credentials for Elasticsearch/OpenSearch. Ankra health checks call `{index}/_count`, not `/_cluster/health`, so least-privilege API keys work without false "degraded" status.

***

## Connecting a Log Source

**1. Open Integrations**

Navigate to your cluster → **Settings** → **Integrations**.

**2. Select Log Source**

Choose **Log Source** under **Logs** in the sidebar.

**3. Pick a provider**

Select **Grafana Loki**, **Elasticsearch**, or **OpenSearch**.

**4. Enter the endpoint**

Provide the HTTP endpoint reachable from the Ankra agent inside the cluster.

Examples:

```
http://loki-gateway.monitoring.svc:80
https://elasticsearch.logging.svc:9200
```

For Grafana Cloud Loki, use the tenant query URL from your Grafana Cloud stack.

**5. Configure provider options**

* **Loki** - Optional tenant ID (`X-Scope-OrgID`) for multi-tenant deployments
* **Elasticsearch / OpenSearch** - Index pattern (default `*`) and optional field mappings if your shipper uses non-standard field names
* **Verify TLS certificate** - Enable when the endpoint presents a publicly trusted or cluster-trusted certificate; leave off for self-signed in-cluster endpoints

**6. Add credentials (if required)**

Choose the auth type that matches your deployment:

* **API Token** - Bearer token (Loki, OpenSearch, Grafana Cloud)
* **API Key** - Elasticsearch `Authorization: ApiKey …` header
* **User Account** - HTTP basic auth

**7. Test and save**

Click **Test connection**, then **Save**. The sidebar status dot turns green when the background health probe succeeds.

***

## Field mappings (Elasticsearch / OpenSearch)

If you ship logs with Fluent Bit's kubernetes filter, the defaults usually work:

| Logical field | Default path |
| - | - |
| Timestamp | `@timestamp` |
| Message | `message` |
| Namespace | `kubernetes.namespace_name` |
| Pod | `kubernetes.pod_name` |
| Container | `kubernetes.container_name` |

Override these in the **Advanced field mappings** section when your index template uses different names.

For **Loki**, structured filters use label names (defaults: `namespace`, `pod`, `container` for Promtail/Alloy).

***

## Managing the log source in Git

If the cluster is connected to a [GitOps repository](/concepts/gitops), the log source is part of the cluster document at `clusters/<cluster-name>-<cluster-id>/<cluster-name>.yaml`. Adding or editing the `spec.log_source` block connects and updates the source on the next sync, exactly as the settings page does:

```yaml theme={null}
spec:
  log_source:
    provider: loki
    endpoint: http://loki-gateway.monitoring.svc:80
    credential_name: loki-read
    tenant_id: my-tenant
```

Accepted fields are `provider`, `endpoint`, `credential_name`, `tenant_id`, `index_pattern`, `field_mappings` and `verify_ssl` - see the [ImportCluster schema](/reference/importcluster#spec-log-source) for what each one means. Any other top-level field is refused with an error naming it, rather than ignored, and `provider` must be `loki`, `elasticsearch` or `opensearch`.

> [!WARNING]
>
> **Credentials never go in Git.** A `username`, `password`, `token` or `auth_scheme` inside the block is refused by name: silently ignoring it would leave a live secret in your repository while you believe it is in effect. Create the credential in the platform and reference it with `credential_name`.
>
> **Removing the block does not disconnect the log source.** Git can create and update the source, never disconnect it - the source survives the sync and the block reappears the next time Ankra regenerates the file. Disconnect from **Settings** → **Integrations** instead.

***

## Searching logs in the portal

1. Open **Logs** in the cluster sidebar
2. Switch to the **Search** tab (visible when the log source feature is enabled)
3. Pick a time range and optional namespace/pod/container filters
4. Enter a text search or toggle **Raw query** for LogQL (Loki) or JSON query-DSL (Elasticsearch/OpenSearch)
5. Use **Load older** to page backward in time

From a pod's **Logs** tab, **Search history** deep-links into Search with that pod pre-filtered.

***

## AI Assistant

With a configured log source, Ankra AI can:

* `query_logs` - Run structured or raw queries over the connected store
* `get_log_labels` - Discover filterable labels/fields before querying

The assistant uses the same agent relay as the portal - credentials never leave the platform secret store.

> [!TIP]
>
> Ask Ankra AI to call `get_log_labels` first when filters return no rows; your shipper may use different label or field names than the defaults.

***

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| Status dot grey | No log source saved yet |
| Status dot amber (degraded) | Credential rejected (401/403) or probe returned an error |
| Search says cluster offline | Agent not connected - live pod logs will also fail |
| Query timeout | Narrow the time range or add namespace/pod filters |
| Empty search results | Wrong index pattern or field mappings; try `get_log_labels` via AI or verify labels in Grafana/Kibana |


# OpenClaw
Source: https://docs.ankra.ai/integrations/openclaw

Give an OpenClaw assistant the Ankra CLI and Ankra's Agent Skills, so your team can ask about and work with Ankra clusters from Slack, Discord, Telegram or another chat app.

Your team already talks in Slack, Discord or Telegram, and you want to ask "which clusters have failing pods?" there rather than opening the portal. [OpenClaw](https://docs.openclaw.ai) is an open-source gateway you host yourself that connects chat apps to an AI agent. Ankra does not ship or run OpenClaw. What Ankra provides is what the agent needs to work with Ankra: the `ankra` CLI and Ankra's [Agent Skills](/integrations/agent-skills), installed where OpenClaw looks for skills.

The agent runs `ankra` commands on the machine where the OpenClaw gateway runs, with the token you give that machine. It can do exactly what that token's role allows, for anyone who can message it.

> [!NOTE]
>
> **Looking for Hermes?** An earlier version of this page used that name for this integration. Nous Research's Hermes Agent is a separate open-source agent, available in the add-on catalogue as **Hermes Agent**.

## Prerequisites

* OpenClaw installed and running, with at least one chat channel connected. Follow the [OpenClaw documentation](https://docs.openclaw.ai) for both.
* The [Ankra CLI](/integrations/ankra-cli#installation), v0.13.0 or later, installed on the machine that runs the OpenClaw gateway and on its `PATH`.
* A [service token](/guides/service-tokens) for the assistant. Pick its role for what the assistant should be allowed to do: `viewer` gives read-only access plus ask-mode AI, and Ankra refuses anything that would change a cluster. See [Roles & Access](/guides/roles-and-access).

## Connect OpenClaw to Ankra

**1. Give the gateway the token**

Add the token to OpenClaw's global environment file, `~/.openclaw/.env`, on the gateway machine:

```bash theme={null}
ANKRA_API_TOKEN=<your-service-token>
```

The CLI reads `ANKRA_API_TOKEN` when there is no saved login. See [OpenClaw's environment variables](https://docs.openclaw.ai/help/environment) for the other places OpenClaw reads variables from, and their order.

**2. Check the CLI works with that token**

On the gateway machine, run a read with the same token:

```bash theme={null}
ANKRA_API_TOKEN=<your-service-token> ankra cluster list
```

You should see the organisation's clusters. If you see someone else's view, or a different organisation, a saved `ankra login` on this machine is taking precedence - see [Troubleshooting](#troubleshooting).

**3. Install the Ankra skills for OpenClaw**

```bash theme={null}
ankra skills install --client openclaw
```

This copies the Ankra skills into `~/.openclaw/skills`, one folder per skill, where OpenClaw discovers them itself. The skills ship inside the CLI binary, so they match the CLI version you installed. `ankra skills list` shows what is installed.

**4. Restart OpenClaw**

Restart the gateway so it loads the new skills.

## Verify

From a chat channel connected to OpenClaw, ask something that needs Ankra, for example:

```text theme={null}
Use ankra-platform-principles. Which of our Ankra clusters are online?
```

The agent should run `ankra` commands on the gateway machine and answer from their output.

## Add a skill for one cluster (optional)

`ankra openclaw skill` writes a skill that names one cluster - its name, ID and portal link - and tells the agent to route changes to that cluster through Ankra rather than running them locally. It writes `~/.openclaw/skills/ankra-<cluster>/SKILL.md`, the folder layout OpenClaw loads skills from:

```bash theme={null}
ankra openclaw skill --cluster my-cluster
```

Restart OpenClaw after writing it. `--output <path>` writes the file somewhere else. A cluster whose skill would take the name of a bundled Ankra skill (a cluster named `cli` would become `ankra-cli`) is refused; use `--output` for it. If an earlier CLI left a `~/.openclaw/skills/ankra-<cluster>.md` file, delete it: OpenClaw never loaded it.

## Update and remove

The skills are versioned with the CLI. After upgrading the CLI, reinstall them:

```bash theme={null}
ankra upgrade
ankra skills install --client openclaw --force
```

To remove them:

```bash theme={null}
ankra skills uninstall --client openclaw
```

To cut the assistant off from Ankra completely, revoke its token under **Organisation** → **Service tokens**.

## Troubleshooting

| Symptom | What to check |
| - | - |
| The agent says it has no `ankra` command | The CLI is not on the `PATH` of the process running the gateway. Install it system-wide, or start the gateway from a shell where `ankra --version` works. |
| Commands fail with `not logged in` | `ANKRA_API_TOKEN` did not reach the gateway. Check `~/.openclaw/.env` and restart the gateway. |
| Commands act as a person, not the service account | A saved login from `ankra login` takes precedence over `ANKRA_API_TOKEN`. On the gateway machine, run `ankra logout --local-only` to clear it without revoking the token. |
| The agent never uses the Ankra skills | OpenClaw was not restarted after the install, or the skills went to another client. Run `ankra skills clients` and check that `openclaw` shows `[installed]`. |
| A request to change something is refused | The token's role does not allow it. That is expected with `viewer`. Give the service account a broader role only if the assistant should make changes. |

## Related

* [Agent Skills](/integrations/agent-skills) - the skills, the other supported assistants, and what an install writes
* [Service Tokens](/guides/service-tokens) - organisation-owned tokens and how to rotate them
* [`ankra openclaw` reference](/reference/cli/openclaw) and [`ankra skills` reference](/reference/cli/skills) - every flag


# Prometheus
Source: https://docs.ankra.ai/integrations/prometheus

Connect Prometheus as a metrics data source for real-time cluster insights

> [!NOTE]
>
> Connect your Prometheus instance to Ankra to view metrics directly in the platform. This powers resource graphs, the AI Assistant's metrics awareness, and cluster health indicators.

## Why Connect Prometheus?

When you connect Prometheus to Ankra:

* **Resource Metrics** - View CPU, memory, and network graphs on pods, deployments, and nodes
* **AI-Powered Analysis** - The AI Assistant can query your metrics to diagnose issues
* **Cluster Overview** - See aggregate metrics on the cluster dashboard
* **Troubleshooting** - Correlate metrics with logs and events in one place

***

## Supported Endpoints

Ankra connects to any Prometheus-compatible endpoint:

| Provider | Example Endpoint |
| - | - |
| Self-hosted Prometheus | `http://prometheus.monitoring.svc.cluster.local:9090` |
| Grafana Cloud | `https://prometheus-prod-xx-xxx.grafana.net` |
| Thanos Query | `http://thanos-query.monitoring.svc.cluster.local:9090` |
| Victoria Metrics | `http://victoria-metrics.monitoring.svc.cluster.local:8428` |

Amazon Managed Prometheus, Google Cloud Managed Prometheus and Azure Monitor appear in the connection dialog but cannot be selected yet.

***

## Connecting Prometheus

**1. Open Integrations**

Navigate to your cluster → **Settings** → **Integrations**.

**2. Select Metrics**

Choose **Metrics** in the sidebar.

**3. Pick a provider**

Under **Provider**, select **Prometheus** for a self-hosted instance, or **Grafana Cloud / Mimir** or **VictoriaMetrics** for a hosted Prometheus-compatible endpoint. The managed cloud providers (AWS, Google, Azure) are marked **Coming soon**.

**4. Enter the endpoint**

Click **Connect Existing** and enter your Prometheus endpoint URL. For a self-hosted Prometheus, Ankra also scans the cluster for Prometheus services and offers the ones it finds.

For in-cluster Prometheus, use the internal service URL:

```
http://prometheus-server.monitoring.svc.cluster.local:9090
```

For kube-prometheus-stack:

```
http://prometheus-operated.monitoring.svc.cluster.local:9090
```

**5. Add credentials (if required)**

If your Prometheus requires authentication, expand **Authentication**, enter a **Credential Name**, and pick the **Authentication Method**:

* **API Token** - For bearer token authentication
* **User Account** - For basic auth (username/password)

**6. Test and save**

Click **Test Connection** to verify Ankra can reach your Prometheus instance, then **Submit** to store the configuration.

***

## Authentication Options

> [tab] No Authentication
>
> For Prometheus instances without authentication (common for in-cluster deployments):
> Simply enter the endpoint URL and save. No credentials needed.

> [tab] API Token
>
> For Prometheus instances using bearer token authentication:
>
> 1. Expand **Authentication** in the metrics form and enter a **Credential Name**
> 2. Choose the **API Token** method
> 3. Enter your token value
>
> Ankra sends the token as: `Authorization: Bearer <token>`

> [tab] Basic Auth
>
> For Prometheus instances using username/password:
>
> 1. Expand **Authentication** in the metrics form and enter a **Credential Name**
> 2. Choose the **User Account** method
> 3. Enter the username and password

***

## In-Cluster vs External Prometheus

### In-Cluster Prometheus

If Prometheus runs inside the same cluster:

1. Use the internal Kubernetes service URL
2. No authentication is typically needed
3. The Ankra agent forwards requests through the cluster network

**Common service URLs:**

```
# Standard Prometheus
http://prometheus-server.monitoring.svc.cluster.local:9090

# kube-prometheus-stack
http://prometheus-operated.monitoring.svc.cluster.local:9090

# Prometheus Operator
http://prometheus-k8s.monitoring.svc.cluster.local:9090
```

### External Prometheus

If Prometheus runs outside the cluster (cloud managed, separate infrastructure):

1. Use the external URL (must be reachable from your cluster)
2. Configure authentication as required by your provider
3. Ensure network connectivity and firewall rules allow access

***

## Credentials

In the portal, the credential is created with the metrics source, in the **Authentication** section of the form:

* **Credential Name** - A descriptive name like `prometheus-prod`
* **Authentication Method** - **API Token** for bearer token auth, **User Account** for basic auth

Ankra keeps its own copy of the secret and sends it with every query and with the health probe that runs every five minutes. It never reads the credential from the cluster - not from a Kubernetes Secret, not from the Prometheus configuration - so rotating the password on the Prometheus side does not update Ankra, and updating Ankra does not change Prometheus.

> [!NOTE]
>
> A saved credential cannot be edited in place. To rotate a token or password, delete the credential from **Settings** → **Integrations** → **Metrics** and create a new one.
>
> To keep the gap short, rotate Prometheus first, then Ankra: once the new secret is live on the Prometheus side, open **Edit** on the metrics source, type the new credentials into the **Authentication** section and click **Test Connection**. The test uses what you typed without saving it, so a green result proves the new secret opens the door before you replace the saved credential. Queries fail with a 401 for the time between Prometheus dropping the old secret and Ankra receiving the new one.

### Rotating by API

To rotate from a script, send the cluster's import request with only the new credential. The call replaces the saved metrics credential and leaves everything else on the cluster as it is - as long as the body carries no `stacks`, because a stack in the body replaces the saved stack of that name.

```bash theme={null}
curl -sS -X POST "https://platform.ankra.app/api/v1/clusters/import?wait=true" \
  -H "Authorization: Bearer $ANKRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<cluster-name>",
    "spec": {
      "prometheus_credential": {
        "name": "<credential-name>",
        "username": "<username>",
        "password": "<new-password>"
      }
    }
  }'
```

* **Use a REST token** - a [personal access token](/reference/tokens) created without `--scopes`, or a [service token](/guides/service-tokens) with no MCP scope, whose role can change the cluster. A token with `mcp:read` or `mcp:write` is refused with `403`.
* **Send the whole block.** `name`, `username` and `password` for basic auth, or `name` and `token` for bearer auth. An omitted `username` is saved as empty and basic auth stops working.
* **Keep the name** the **Metrics** panel shows, so the old secret is overwritten rather than left behind.
* **Use `wait=true`**, so the call answers with the outcome - check its `errors` list - instead of `202` before the work is done.
* **If the call answers `422 Failed to push changes to Git repository`**, the credential is already saved: Ankra has not yet synced your latest commit to the cluster's repository. Do not retry; check with the query below.

This call is the only scripted way to change the secret: `ankra cluster apply` and the Git sync both ignore a `prometheus_credential` block. To check the whole path afterwards - the saved credential, the agent and Prometheus - run `ankra cluster metrics query 'up'` against the cluster. Results are cached for ten seconds.

***

## Managing the Connection in Git

If the cluster is connected to a [GitOps repository](/concepts/gitops), the metrics data source is part of the cluster document at `clusters/<cluster-name>-<cluster-id>/<cluster-name>.yaml`. Adding or editing the `spec.prometheus_metrics` block connects and updates the source on the next sync, exactly as the settings page does:

```yaml theme={null}
spec:
  prometheus_metrics:
    endpoint: http://prometheus-operated.monitoring.svc.cluster.local:9090
    flavor: self_hosted
    credential_name: prometheus-prod
```

Accepted fields are `endpoint`, `credential_name`, `flavor` and `verify_ssl` - see the [ImportCluster schema](/reference/importcluster#spec-prometheus-metrics) for what each one means. Any other top-level field is refused with an error naming it, rather than ignored. A block without `credential_name` keeps using the credential already saved on the cluster, if there is one; the **Metrics** panel under **Settings** → **Integrations** shows which.

> [!WARNING]
>
> **Credentials never go in Git.** A `username`, `password`, `token` or `auth_scheme` inside the block is refused by name: silently ignoring it would leave a live secret in your repository while you believe it is in effect. Create the credential in the platform and reference it with `credential_name`.
>
> **Removing the block does not disconnect Prometheus.** Git can create and update the source, never disconnect it - the source survives the sync and the block reappears the next time Ankra regenerates the file. Disconnect from **Settings** → **Integrations** instead.

***

## Verifying the Connection

After connecting Prometheus:

1. **Check Integrations** - The **Metrics** entry in the sidebar shows a green dot, and the panel shows the last health check
2. **View Resource Metrics** - Go to any pod or deployment and check for metric graphs
3. **Ask the AI** - Press `⌘+J` and ask "What's the CPU usage of this pod?"

If metrics aren't showing:

* Verify the endpoint URL is correct
* Check that Prometheus has data for your cluster
* Re-test the connection from **Settings** → **Integrations** → **Metrics** → **Edit**
* Check network connectivity between your cluster and Prometheus

***

## Troubleshooting

> [accordion] Connection Test Fails
>
> 1. Verify the URL is correct and includes the port
> 2. For in-cluster Prometheus, ensure the service exists:
>    ```bash theme={null}
>    kubectl get svc -n monitoring
>    ```
> 3. Check if Prometheus is running:
>    ```bash theme={null}
>    kubectl get pods -n monitoring -l app=prometheus
>    ```
> 4. Test connectivity from within the cluster:
>    ```bash theme={null}
>    kubectl run curl --rm -it --image=curlimages/curl -- curl http://prometheus-server.monitoring:9090/api/v1/query?query=up
>    ```

> [accordion] Authentication Errors
>
> 1. Verify the credential is correctly configured
> 2. For API tokens, ensure the token hasn't expired
> 3. For basic auth, verify the username and password are correct
> 4. Check Prometheus logs for authentication failures

> [accordion] Metrics Not Appearing
>
> 1. Prometheus may not have metrics for the resource yet (wait for scrape interval)
> 2. Verify Prometheus is scraping the correct targets
> 3. Check the Prometheus UI targets page for scrape errors
> 4. Ensure the metric names match what Ankra expects (standard Kubernetes metrics)

> [accordion] Slow Queries
>
> 1. Large time ranges can be slow. Try narrower ranges.
> 2. Consider using recording rules for frequently-queried metrics
> 3. Check Prometheus resource usage (may need more CPU/memory)

***

## What Metrics Does Ankra Use?

Ankra queries standard Kubernetes and node metrics:

| Metric | Source | Used For |
| - | - | - |
| `container_cpu_usage_seconds_total` | cAdvisor | Pod/container CPU graphs |
| `container_memory_working_set_bytes` | cAdvisor | Pod/container memory graphs |
| `node_cpu_seconds_total` | node-exporter | Node CPU usage |
| `node_memory_MemAvailable_bytes` | node-exporter | Node memory usage |
| `kube_pod_status_phase` | kube-state-metrics | Pod status indicators |
| `kube_deployment_status_replicas` | kube-state-metrics | Deployment health |

If you're using kube-prometheus-stack, all these metrics are included by default.

***

## Next Steps

> [card] [Build a Monitoring Stack](/guides/monitoring-stack)
>
> Deploy Prometheus and Grafana with one Stack.

> [card] [AI Assistant](/platform/ai-assistant)
>
> Use the AI to query and analyze your metrics.

> [card] [Kubernetes Insights](/platform/kubernetes-insights)
>
> Explore built-in cluster dashboards.

> [card] [Credentials](/platform/credentials)
>
> Manage authentication for all integrations.


# Ankra Terraform Provider
Source: https://docs.ankra.ai/integrations/terraform

Manage Ankra from Terraform with the ankraio/ankra provider - clusters on every cloud, managed Kubernetes, node groups, credentials, Helm registries, variables, cluster settings, alerts and DNS, applications and pipelines, stack profiles, backups, members and tokens, plus projects, import, readiness waits, known limits and upgrading.

You manage your infrastructure with Terraform and want Ankra in the same plan. The Ankra Terraform provider, `ankraio/ankra` on the [Terraform Registry](https://registry.terraform.io/providers/ankraio/ankra), manages what the [Ankra CLI](/integrations/ankra-cli) can create, change or delete: clusters on your cloud, managed Kubernetes, node groups, credentials, Helm registries, variables, alerts, DNS, applications, pipelines, stack profiles, backups, members, tokens and organisation settings. The Registry carries the generated reference for every resource and attribute.

> [!NOTE]
>
> This page describes provider **0.3.0**, which brings the provider to parity with the CLI: 97 resources and 42 data sources. On **0.2.x** only the six cluster resources and the `ankra_clusters` data source exist. Check the version you can install on the Registry before you use a resource from [What you can manage](#what-you-can-manage), and read [Upgrade from 0.2.x](#upgrade-from-0-2-x) before you upgrade.

## Configure the provider

The provider needs Terraform 1.0 or newer (it is tested with 1.6 to 1.12).

```hcl theme={null}
terraform {
  required_providers {
    ankra = {
      source  = "ankraio/ankra"
      version = "~> 0.3.0"
    }
  }
}

provider "ankra" {
  project_id = var.ankra_project_id
}

variable "ankra_project_id" {
  type = string
}
```

| Argument | Environment variable | Notes |
| - | - | - |
| `token` | `ANKRA_TOKEN` | An Ankra [API token](/reference/tokens). Prefer the environment variable so the token stays out of your configuration. |
| `base_url` | `ANKRA_BASE_URL` | Defaults to `https://platform.ankra.app`. |
| `organisation_id` | `ANKRA_ORG` | Act in another organisation your user belongs to, like the CLI's `--org` flag, which reads the same variable. Takes the organisation's ID, not its name. Defaults to the organisation the token belongs to. |
| `project_id` | `ANKRA_PROJECT_ID` | The project to act in, for organisations that group their clusters and resources into projects. Takes the project's ID. **Required in an organisation with more than one project.** |

If no token reaches a resource, from the provider or the deprecated per-resource `ankra_token`, Terraform stops with `Missing API token` and sends no request.

### Projects and organisations

Without `project_id`, Ankra scopes every request to the project your user last selected in the UI, so switching project there would change what Terraform sees. The resources added in 0.3.0 therefore refuse to run in an organisation with more than one project until the provider sets `project_id`, and they send nothing until it does.

When `organisation_id` or `project_id` changes, an object Terraform created in the old scope is reported as not visible in the provider's current scope. It is not planned for recreation, and `terraform destroy` does not report it destroyed while it still exists. Point the provider back at the old scope to manage it, or run `terraform state rm` to stop managing it.

If `organisation_id` or `project_id` is only known after apply (for example, it comes from another resource), the provider sends no request until it is known instead of acting in your default organisation or project.

## What you can manage

Each name links to its reference on the Registry through the provider's documentation index.

| Area | Resources | Data sources |
| - | - | - |
| Clusters Ankra builds | `ankra_hetzner_cluster`, `ankra_digitalocean_cluster`, `ankra_ovh_cluster`, `ankra_upcloud_cluster`, `ankra_scaleway_cluster` (Closed Beta), `ankra_aws_cluster`, `ankra_proxmox_cluster`, `ankra_morpheus_cluster`, `ankra_ankracloud_cluster`, `ankra_playground` | `ankra_clusters`, `ankra_cluster`, `ankra_kubernetes_versions`, `ankra_playground_plans` |
| [Managed Kubernetes](/guides/managed-kubernetes) | `ankra_managed_cluster`, `ankra_managed_node_pool` | |
| Node groups | `ankra_node_group` | `ankra_node_groups` |
| Clusters you run | `ankra_cluster` | |
| [Credentials](/platform/credentials) | `ankra_hetzner_credential`, `ankra_digitalocean_credential`, `ankra_upcloud_credential`, `ankra_ovh_credential`, `ankra_scaleway_credential`, `ankra_azure_credential`, `ankra_ankracloud_credential`, `ankra_morpheus_credential`, `ankra_proxmox_credential`, `ankra_aws_role_credential`, `ankra_aws_keys_credential`, `ankra_ssh_key_credential` | `ankra_credentials`, `ankra_credential` |
| [Helm registries](/integrations/helm-registries) and variables | `ankra_helm_registry`, `ankra_helm_registry_credential`, `ankra_organisation_variable`, `ankra_cluster_variable` | `ankra_helm_registries`, `ankra_helm_registry_credentials`, `ankra_helm_chart`, `ankra_organisation_variables`, `ankra_cluster_variables` |
| Cluster settings | `ankra_cluster_access_grant`, `ankra_cluster_ssh_keys`, `ankra_cluster_custom_dns_zone`, `ankra_cluster_power_schedule`, `ankra_cluster_agent_auto_upgrade`, `ankra_cluster_agent_ci_settings`, `ankra_cluster_log_shipping`, `ankra_cluster_mesh`, `ankra_cluster_mesh_member` | `ankra_cluster_access_grants`, `ankra_cluster_custom_dns_zones`, `ankra_cluster_power_schedules`, `ankra_cluster_meshes` |
| Alerts and DNS | `ankra_alert_destination`, `ankra_alert_route`, `ankra_organisation_dns_record`, `ankra_organisation_custom_dns_zone`, `ankra_organisation_domain`, `ankra_dns_credential`, `ankra_cloudflare_credential`, `ankra_cloudflare_dns_record` | `ankra_alert_destinations`, `ankra_alert_routes`, `ankra_organisation_dns_zone`, `ankra_organisation_dns_records`, `ankra_organisation_custom_dns_zones`, `ankra_dns_credentials`, `ankra_cloudflare_credentials`, `ankra_cloudflare_domains` |
| Applications and [pipelines](/guides/pipeline-reference) | `ankra_application`, `ankra_application_settings`, `ankra_application_auto_deploy`, `ankra_application_ai_config`, `ankra_application_demo_config`, `ankra_application_env_secret`, `ankra_application_deployment`, `ankra_pipeline_repository`, `ankra_pipeline_definition`, `ankra_pipeline_schedule`, `ankra_pipeline_merge_train` | `ankra_applications`, `ankra_application`, `ankra_pipeline_repositories` |
| Stack profiles, backups and the image registry | `ankra_stack_profile`, `ankra_stack_profile_version`, `ankra_stack_profile_share`, `ankra_stack_profile_logo`, `ankra_backup_vault`, `ankra_object_storage_bucket`, `ankra_registry_project`, `ankra_registry_robot`, `ankra_registry_retention` | `ankra_stack_profiles`, `ankra_backup_vaults`, `ankra_object_storage_buckets`, `ankra_registry_projects`, `ankra_registry_robots` |
| Organisation and access | `ankra_organisation`, `ankra_organisation_member`, `ankra_api_token`, `ankra_service_token`, `ankra_mcp_server`, `ankra_mcp_tool_grant`, `ankra_ci_settings`, `ankra_ci_pool_member`, `ankra_ai_review_repository`, `ankra_ai_review_related_repository`, `ankra_ai_spend_cap`, `ankra_ai_environment` | `ankra_organisation`, `ankra_organisations`, `ankra_mcp_servers` |
| AI, cost, security, services and hosts | `ankra_ai_provider`, `ankra_ai_anthropic_key`, `ankra_ai_openrouter_key`, `ankra_ai_openai_compatible`, `ankra_ai_endpoint`, `ankra_ai_model`, `ankra_ai_lane_model`, `ankra_ai_board_identity`, `ankra_cost_budget`, `ankra_cost_autopilot`, `ankra_cost_autopilot_override`, `ankra_cost_settings`, `ankra_security_disposition`, `ankra_security_compliance_framework`, `ankra_security_report_schedule`, `ankra_service_placement_policy`, `ankra_service_consumer`, `ankra_host_join_token` | `ankra_ai_models`, `ankra_ai_endpoints`, `ankra_ai_lanes`, `ankra_cost_budgets`, `ankra_security_compliance_frameworks`, `ankra_host_targets`, `ankra_deploy_environments` |

Operational commands stay in the CLI: logs, `exec`, metrics, pipeline runs and reruns, `cluster scale`, `cluster upgrade`, chat and the AI board. Stack variables, managed services, stack profile drafts, restore points and migrations have no Terraform resource either.

## Create a cluster on your cloud

The cloud cluster resources share most arguments and each keeps its cloud's own words for size and place.

```hcl theme={null}
resource "ankra_hetzner_credential" "main" {
  name      = "hetzner-main"
  api_token = var.hcloud_token
}

resource "ankra_ssh_key_credential" "main" {
  name           = "laptop"
  ssh_public_key = file(pathexpand("~/.ssh/id_ed25519.pub"))
}

resource "ankra_hetzner_cluster" "dev" {
  name          = "my-cluster"
  credential_id = ankra_hetzner_credential.main.id
  location      = "fsn1"

  ssh_key_credential_id = ankra_ssh_key_credential.main.id

  control_plane_count       = 1
  control_plane_server_type = "cpx22"
  worker_count              = 2
  worker_server_type        = "cpx22"
  bastion_server_type       = "cpx12"

  gitops_repository      = "my-org/my-repo"
  gitops_branch          = "main"
  gitops_credential_name = "my-github-credential"

  timeouts {
    create = "60m"
  }
}

variable "hcloud_token" {
  type      = string
  sensitive = true
}
```

Required arguments:

| Resource | Required |
| - | - |
| `ankra_hetzner_cluster` | `name`, `credential_id`, `location` |
| `ankra_digitalocean_cluster` | `name`, `credential_id`, `ssh_key_credential_id`, `region` |
| `ankra_ovh_cluster` | `name`, `credential_id`, `ssh_key_credential_id`, `region` |
| `ankra_upcloud_cluster` | `name`, `credential_id`, `ssh_key_credential_id`, `zone` |
| `ankra_scaleway_cluster` | `name`, `credential_id`, `ssh_key_credential_id`, `region`, `zone` |

AWS, Proxmox, Morpheus and Ankra Cloud follow the same pattern; their Registry pages list each one's required arguments.

Optional arguments every cloud resource takes:

| Argument | Notes |
| - | - |
| `ssh_key_credential_id` | Optional on Hetzner: Ankra generates its own key pair for every Hetzner cluster, so one can be created without this argument. Required on DigitalOcean, OVHcloud, UpCloud and Scaleway (the table above). The ID of an [SSH key credential](/platform/credentials/ssh-key), for example `ankra_ssh_key_credential.<name>.id`. |
| `distribution`, `cni` | `kubeadm` and `cilium` by default. For k3s set `distribution = "k3s"` and `cni` to `flannel` or `calico`. |
| `kubernetes_version` | Defaults to the platform's stable version. `data.ankra_kubernetes_versions` lists the others. |
| `control_plane_count`, `worker_count`, and the per-role size arguments | Node counts and machine sizes: `server_type` on Hetzner, `size` on DigitalOcean, `flavor_id` on OVHcloud, `plan` on UpCloud, `type` on Scaleway. |
| `etcd_topology`, `etcd_node_count` | `stacked` or `external` etcd on kubeadm clusters. |
| `include_networking` | Install Traefik and cert-manager. |
| `external_cloud_provider` | Install the cloud controller manager and CSI driver. |
| `gitops_repository`, `gitops_branch`, `gitops_credential_name` | Commit the generated Stack to your GitOps repository. |
| `wait_for_ready`, `timeouts` | See [Readiness and timeouts](#readiness-and-timeouts). |
| `force_destroy` | See below. |

A cluster's own provisioning arguments force replacement: change `worker_count` or a size on the cluster resource and the plan destroys and recreates the cluster. To add capacity, add or change an [`ankra_node_group`](#node-groups), or scale with the CLI or the UI. Read every plan before you apply it.

`terraform destroy` asks Ankra to deprovision the cluster and remove what it created in your cloud account, and on AWS, Proxmox, Morpheus and Ankra Cloud it waits until the cluster is gone. `force_destroy` skips the platform's usual guards: it is `true` by default on Hetzner, DigitalOcean, OVHcloud, UpCloud and Scaleway and `false` on the others. On AWS and Ankra Cloud, Ankra refuses to delete a cluster that still holds persistent volumes unless you set `accept_volume_data_loss = true`.

> [!WARNING]
>
> **Closed beta.** Scaleway as a cluster provider is in closed beta, and `ankra_scaleway_cluster` only works for organisations that have it turned on. Until it is, the Scaleway endpoints are not served and the create fails. [Contact support](/platform/support) to have it turned on for your organisation.

To use credentials you already created, find their IDs with the CLI. The ID column of `ankra credentials list` holds `credential_id`, and the provider's `ssh-key list` holds `ssh_key_credential_id`:

```bash theme={null}
ankra credentials list
ankra credentials hetzner ssh-key list
```

### Node groups

`ankra_node_group` adds a group of workers to a cluster Ankra built. `node_count`, `instance_type`, `labels`, `taints` and `autoscaling` change in place. An `instance_type` change drains and power-cycles each node, and the apply waits until every node is back on the new type.

```hcl theme={null}
resource "ankra_node_group" "gpu" {
  cluster_id    = ankra_hetzner_cluster.dev.cluster_id
  name          = "gpu"
  instance_type = "cpx42"
  node_count    = 2

  labels = {
    accelerator = "gpu"
  }

  timeouts {
    create = "30m"
    update = "30m"
  }
}
```

## Managed Kubernetes

`ankra_managed_cluster` creates a cluster on DigitalOcean (DOKS), UpCloud (UKS), Google (GKE), Azure (AKS), AWS (EKS), OVHcloud (MKS), Scaleway (Kapsule) or Ankra Cloud Kubernetes and connects it to Ankra. Options specific to one provider go in `provider_options`.

```hcl theme={null}
resource "ankra_managed_cluster" "aks" {
  provider_name = "aks"
  name          = "aks-prod"
  credential_id = var.azure_credential_id
  location      = "westeurope"

  provider_options = jsonencode({
    resource_group = "rg-ankra"
  })

  node_pools = {
    system = {
      size       = "Standard_D4s_v5"
      node_count = 3
    }
  }
}

variable "azure_credential_id" {
  type = string
}
```

`node_pools` is a map keyed by pool name. `node_count` and `autoscaling` change in place, adding a key adds a pool and removing one deletes it. To change a pool's size, give it a new key: the new pool is added, and the old one is deleted only after the new pool's nodes are ready. Ankra cannot check pool readiness on UKS and OVHcloud MKS, so there both pools are kept and the apply stops with an explanation. Other changes to an existing pool are refused at plan time. `ankra_managed_node_pool` manages a pool outside the cluster resource.

`destroy_mode` decides what `terraform destroy` does: `delete_provider_cluster` deletes the cluster at the provider, `disconnect` only removes it from Ankra. Clusters this resource created default to deleting, imported ones to disconnecting. `wait_for_agent = true` waits until the Ankra agent is online.

## Register a cluster you already run

`ankra_cluster` registers a cluster you operate yourself, the same way an [ImportCluster file](/reference/importcluster) does, and keeps its Stacks in Terraform.

```hcl theme={null}
resource "ankra_helm_registry" "traefik" {
  name = "traefik"
  url  = "https://traefik.github.io/charts"
}

resource "ankra_cluster" "prod" {
  cluster_name           = "my-cluster"
  github_credential_name = "my-github-credential"
  github_repository      = "my-org/my-repo"
  github_branch          = "main"

  stacks {
    name        = "ingress"
    description = "Traefik ingress controller"

    manifests {
      name = "traefik-namespace"
      manifest_base64 = base64encode(<<-YAML
        apiVersion: v1
        kind: Namespace
        metadata:
          name: traefik
        YAML
      )
    }

    addons {
      name          = "traefik"
      chart_name    = "traefik"
      chart_version = "37.1.1"
      registry_name = ankra_helm_registry.traefik.name
      registry_url  = ankra_helm_registry.traefik.url
      namespace     = "traefik"
      parents       = ["manifest:traefik-namespace"]

      configuration = <<-YAML
        deployment:
          replicas: 2
        YAML

      job_configuration = jsonencode({
        create_job_timeout = 600
      })
    }
  }
}
```

| Argument | Notes |
| - | - |
| `cluster_name` | Required. Changing it replaces the cluster. |
| `github_credential_name`, `github_repository`, `github_branch` | Required. The cluster's GitOps repository. See [Known limits](#known-limits) before changing them. |
| `stacks` | `name`, `description`, `manifests` and `addons`. |
| `manifests` | `name` and either `manifest_base64` (the manifest, base64-encoded) or `from_file`; optional `namespace` and `parents`. |
| `addons` | `name`, `chart_name`, `chart_version`, `namespace`, and `registry_url` (or its deprecated alias `repository_url`); optional `registry_name`, `registry_credential_name`, `configuration`, `job_configuration` and `parents`. |
| `wait_for_online` | `false` by default. See [Readiness and timeouts](#readiness-and-timeouts). |

How the Stack fields work:

* **`parents`** orders deployment. Write each entry as `"manifest:<name>"` or `"addon:<name>"`. A bare `"<name>"` works when exactly one manifest or add-on of that name is declared in the resource. Leaving `parents` out keeps the order already stored in Ankra; an empty list removes it.
* **`registry_url`** is the Helm repository that serves the chart (`https://...` or `oci://...`). **`registry_name`** is the name of that [Helm registry](/integrations/helm-registries) in your organisation, which `ankra_helm_registry` can create. If you leave it out, the provider derives a name from the URL, which Ankra accepts when a registry with that URL is already connected. Set `registry_credential_name` (an `ankra_helm_registry_credential`) for a private registry. `data.ankra_helm_chart` gives the `latest_version` of a chart if you want to pin to it.
* **`configuration`** holds the Helm values, as YAML or base64-encoded YAML.
* **`job_configuration`** is a JSON object of timeouts in seconds: `create_job_timeout`, `read_job_timeout`, `update_job_timeout` and `delete_job_timeout`. Build it with `jsonencode`.
* Stack variables you set in the UI or the CLI are kept when the resource applies the Stack.

The provider checks `parents` and `job_configuration` at plan time. If Ankra refuses the Stack, the error names the member and the field.

| Attribute | Notes |
| - | - |
| `cluster_id` | The Ankra cluster ID. |
| `helm_command` | Installs the Ankra agent in the cluster. It contains a live agent token, so it is marked sensitive. Ankra issues it only when the cluster is first registered. |
| `state`, `kind` | As Ankra reports them. `state` is `offline` until the agent checks in, then `online`. |

Run `helm_command` against the cluster to connect it. Terraform cannot run it inside the cluster for you, but a `remote-exec` provisioner on a host that can reach the cluster can:

```hcl theme={null}
resource "null_resource" "install_agent" {
  provisioner "remote-exec" {
    connection {
      type        = "ssh"
      host        = var.host
      user        = var.user
      private_key = file(var.private_key)
    }

    inline = [ankra_cluster.prod.helm_command]
  }
}

variable "host" {
  type = string
}

variable "user" {
  type = string
}

variable "private_key" {
  type = string
}
```

To run it yourself instead, expose it as a sensitive output and read it with `terraform output -raw agent_install_command`:

```hcl theme={null}
output "agent_install_command" {
  value     = ankra_cluster.prod.helm_command
  sensitive = true
}
```

If a cluster with the same `cluster_name` already exists, creating the resource adopts it: Ankra updates that cluster with your configuration and Terraform manages it from then on. Because the agent command is only issued on first registration, `helm_command` is empty for an adopted cluster, and Terraform prints a warning saying so. Copy the command from the Ankra UI if you need it.

`terraform destroy` deletes the cluster from Ankra.

## Secrets, tokens and settings

* **Secrets are write-only.** API tokens, keys, passwords and webhook URLs are marked sensitive, and Ankra never returns them, so a secret changed outside Terraform is not detected. Terraform state still holds the value you configured, so keep state in an encrypted backend. On Terraform 1.11 and newer, `ankra_application_env_secret` takes `value_wo`, which is never stored in state.
* **Values shown once** (the token of `ankra_api_token` and `ankra_service_token`, a registry robot's secret, a generated SSH private key, `ankra_host_join_token`) are captured into state when they are created.
* **Changing a token's expiry, scopes, label or project mints a new token value.** The provider creates the new token before it removes the old one, so there is no gap, but every holder needs the new value. An empty `scopes` list is refused because Ankra reads it as full access. A member's or service account's role is changed in the UI, not in Terraform.
* **Settings resources** (`ankra_ci_settings`, `ankra_ai_environment`, `ankra_ai_spend_cap`, `ankra_cluster_agent_ci_settings`, `ankra_cost_settings`, `ankra_cost_autopilot`) write only the attributes you set and reset only those on destroy. Some refuse to create over settings already changed in the UI; import those instead.
* **Applications.** Creating `ankra_application` opens a setup pull request on its repository, which Ankra merges for you if `ankra_application_settings.auto_merge_setup_pull_requests` is on. Replacing an application removes every deployment of it, so consider `lifecycle { prevent_destroy = true }`. `ankra_pipeline_definition` is for repositories without a committed `.ankra/pipeline.yaml`.
* **Data protection.** The plan refuses a change that would replace a backup vault or bucket while `destroy_provider_resources = true`, because the replacement would delete its data.

## Import existing objects

Every resource imports, most by their Ankra ID and cluster-scoped ones by `<cluster_id>/<key>`. Each resource's Registry page shows its import ID.

```bash theme={null}
terraform import ankra_cluster.prod <cluster-id>
terraform import ankra_hetzner_cluster.dev <cluster-id>
terraform import ankra_managed_cluster.aks aks/<cluster-id>
terraform import ankra_cluster_variable.domain <cluster-id>/ingress_domain
```

Ankra does not return a cluster's build arguments or a credential's secrets, so after an import the first apply adopts the values in your configuration as an in-place update instead of replacing the object. Write a configuration that matches the real object before you apply, and read the plan. `ankra_host_join_token` cannot be imported.

## Readiness and timeouts

| Resource | Waits for | Default timeouts |
| - | - | - |
| Cloud cluster resources | The cluster to reach `running`. Set `wait_for_ready = false` to return as soon as Ankra accepts the request. | `create` 60 minutes, `delete` 30 minutes |
| `ankra_managed_cluster` | The provider's cluster, and with `wait_for_agent = true` the Ankra agent. A pool rename waits for the new pool. | `update` 30 minutes; set `create` and `delete` in `timeouts` |
| `ankra_node_group` | Each change, until the group's nodes reflect it. | Set `create`, `update` and `delete` in `timeouts` |
| `ankra_cluster` | Registration. Set `wait_for_online = true` to also wait for the agent to check in, which only happens after someone runs `helm_command`. | `create` 60 minutes, `update` 20 minutes |
| `ankra_application_deployment` | The application's setup to complete. | `create` 30 minutes |

Keep the wait on when anything in the same plan uses the cluster, such as a kubeconfig, a `kubernetes` provider or a module, because provisioning runs in the background. The cluster ID is saved to state before the wait starts, so a timeout reports how far the cluster got without losing track of it.

## Known limits

* **Changing `github_repository` or `github_branch`** on an existing `ankra_cluster` fails with a 409 error. Ankra refuses to move a cluster to a different GitOps source until the move is acknowledged, and the provider has no argument for that yet. Make the move outside Terraform as described under `spec.git_repository` in the [ImportCluster reference](/reference/importcluster), then update your configuration to match.
* **`helm_command` is empty** for an adopted cluster, and when Ankra queued the import instead of running it.
* **Resizes made outside Terraform to a cluster's own arguments are not detected.** Node groups and managed node pools do refresh.
* **Secrets changed outside Terraform are not detected.** See [Secrets, tokens and settings](#secrets-tokens-and-settings).
* **Stack variables** cannot be managed from Terraform yet. Use cluster or organisation variables, or the Stack itself.

Keep each object managed from one place, so Terraform, the CLI and the UI do not overwrite each other's changes.

## Upgrade from 0.2.x

1. **Set `project_id`** on the provider if your organisation uses projects. See [Projects and organisations](#projects-and-organisations).
2. **Imports of the original five cloud clusters** now adopt your configuration on the first apply instead of planning a rebuild. Make the configuration match the real cluster first.
3. **Read the first plan.** Plan-time checks are stricter: values Ankra would refuse at apply now fail the plan instead.

## Upgrade from 0.1.x

0.1.6 cannot create or update a cluster against the current Ankra API, so upgrade before you use the provider. Before you run `terraform init -upgrade`:

1. **Pin `distribution` and `cni` on cloud resources.** Both now default to `kubeadm` and `cilium`, and both force replacement. If a cluster was created with the old k3s and flannel defaults, add `distribution = "k3s"` and `cni = "flannel"` first, or the next plan replaces it.
2. **Use Terraform 1.0 or newer.** The provider runs on Terraform plugin protocol 6.
3. **Move the token to the provider.** Set `token` on the provider block or `ANKRA_TOKEN`. The per-resource `ankra_token` still works but is deprecated, and changing it no longer replaces the cluster.
4. **Update add-ons.** Replace `repository_url` with `registry_url` (the old name still works) and add `registry_name`. Write `job_configuration` as `jsonencode({ ... })`. `configuration_type` is ignored.
5. **Update `parents`.** Use `"manifest:<name>"` or `"addon:<name>"`, or a bare name that matches exactly one member of the resource.
6. **Rotate agent tokens printed by 0.1.x.** `helm_command` contains a live agent token and 0.1.x did not mark it sensitive. If a plan or CI log printed it, rotate that token.

Then run `terraform plan` and check it reports no replacement you did not expect.

The full list of changes is in the provider's [changelog](https://github.com/ankraio/terraform-provider-ankra/blob/main/CHANGELOG.md).

## Next steps

Create an [API token](/reference/tokens), find your project's ID, and add the provider block above to your configuration. Start with a credential and a cluster, then move the rest of your organisation's setup into the same plan.


# AI Gateway
Source: https://docs.ankra.ai/pipelines/ai-gateway

The AI Gateway connects Ankra's AI to Slack, Microsoft Teams, GitHub, GitLab and Bitbucket - how a message or a pull request event reaches the AI and back, Ask and Agent safety modes per connection, what each connection may do, the staging cluster for workspaces and previews, and the settings that govern it.

The AI Gateway is how Ankra's AI meets your team where it already works. A question in Slack, an `@ankraai` in a pull request, a push that needs a review, a failed build that needs a diagnosis: each arrives through one gateway, is answered by the same AI with the same knowledge of your clusters and pipelines, and goes back to where it came from.

```mermaid theme={null}
flowchart LR
    subgraph Chat["Chat"]
        Slack[Slack]
        Teams[Microsoft Teams]
    end
    subgraph SCM["Source control"]
        GH[GitHub]
        GL[GitLab]
        BB[Bitbucket Cloud]
    end

    Slack --> GW
    Teams --> GW
    GH --> GW
    GL --> GW
    BB --> GW

    GW[AI Gateway<br/>one profile per connection:<br/>mode + capabilities] --> AI[Ankra AI<br/>your clusters, pipelines,<br/>runs, findings, docs]
    AI --> Lanes{What was asked}
    Lanes --> Answer[Answer in the thread]
    Lanes --> Review[Pull request review]
    Lanes --> Fix[Diagnosis or fix pull request]
    Lanes --> Preview[Preview or workspace<br/>on the staging cluster]
```

## Every connection has a profile

Each connection (a Slack workspace, a Teams tenant, a GitHub App installation, a GitLab token, a Bitbucket workspace) carries a **profile**: a safety mode, and the capabilities switched on for it.

| Connection | Starts with | Capabilities you switch on |
| - | - | - |
| Slack, Microsoft Teams | Chat, alert actions and notifications. Anything that changes something asks first | Follows the organisation's default mode |
| GitHub, GitLab, Bitbucket Cloud | **Everything off.** Installing an app or connecting a token grants access, nothing more | AI review, review drafts, mention replies, PR previews, push code review, failed-build review, skills review, merge when green |

Source-control connections start off because a pull request is a shared, public place. Nothing should post there until someone decides it should.

## Ask and Agent

The mode bounds **how far** an answer may go. The capability switches decide **whether** the AI answers at all.

```mermaid theme={null}
flowchart LR
    subgraph Ask["Ask (default)"]
        A1[Investigate and explain]
        A2[Read runs, logs, findings]
        A3[Safe creations:<br/>workspace pod, PR demo,<br/>a brand-new Stack]
    end
    subgraph Agent["Agent: Can act"]
        G1[Everything in Ask]
        G2[Open fix pull requests]
        G3[Merge when green]
        G4[Other changes<br/>still ask to confirm]
    end
```

| | Ask | Agent |
| - | - | - |
| Explain a failing pipeline run | Yes | Yes |
| Spin up a throwaway workspace or PR demo | Yes | Yes |
| Change existing infrastructure | No | With confirmation |
| Open a fix pull request | No | Yes, and the pull request is the review gate |
| Merge when green | Refused, naming the setting | Yes |

* **Ask is the default**, and the fallback for a connection with no mode set.
* **Automatic events stay read-only in either mode.** A review comments. A proposed fix arrives as a separate pull request you review like any other.
* **An unconfigured chat connection** inherits the organisation's default mode:

```bash theme={null}
ankra org ai-environment set --default-gateway-mode ask
```

The same two modes exist everywhere: `ankra chat --mode ask|agent` in the CLI, and `mcp:read` and `mcp:write` tokens on the [MCP server](/pipelines/cli-and-mcp).

## From a Slack question to an answer

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor You
    participant Slack
    participant GW as AI Gateway
    participant AI as Ankra AI
    participant P as Ankra Pipelines

    You->>Slack: @Ankra why is main red?
    Slack->>GW: Event
    GW->>GW: Is this Slack user linked to an Ankra account?
    alt not linked yet
        GW-->>Slack: Connect your Ankra account
        You->>GW: Link (once)
        GW->>GW: Replay the parked question
    end
    GW->>AI: Ask, as you, with your permissions
    AI->>P: Latest run on main, failing step, log tail
    P-->>AI: e2e failed, exit 1, findings
    AI-->>Slack: Streamed answer in the thread
    You->>Slack: Reply in the thread
    Slack->>GW: Continues the same conversation
```

* **The AI answers as you.** Each person links their Slack or Teams account to their Ankra account once. From then on the AI has exactly that person's permissions, never more.
* **Threads are conversations.** Mention the bot to start one, and reply in the thread to continue it.
* **Ticket threads sync with the board.** A reply that starts with `Decision:` answers a pending choice on a board ticket.
* **`/ankra status`, `/ankra logout` and `/ankra help`** work in Slack.

Prompts that work from Slack or Teams:

> @Ankra is the pipeline for my-org/my-repo green on main, and if not, what broke?

> @Ankra show me the failing step's log for the last pipeline run on pull request 412 in my-org/my-repo.

> @Ankra the nightly e2e failed again. Is it the same test as yesterday?

## From a pull request event to a review

Provider webhooks feed separate lanes, each with its own switch. Every event is deduplicated, so a redelivered webhook never reviews twice.

```mermaid theme={null}
flowchart LR
    Event[Webhook: opened, pushed,<br/>ready, comment, closed] --> Dedup[Deduplicate]
    Dedup --> R[AI review lane]
    Dedup --> M[Mention lane: @ankraai]
    Dedup --> Pv[Preview lane]
    Dedup --> Ac[Failed build lane]
    Dedup --> Am[Merge when green lane]
    R & M & Pv & Ac & Am --> SC[One status comment<br/>plus inline findings]
```

What each lane does is on [AI in pull requests](/pipelines/ai-in-pull-requests). What each switch means is on [AI Code Review](/platform/ai-code-review).

## The staging cluster

Workspaces, pull request previews and PR demos run on one cluster your organisation nominates for AI work: the **staging cluster**. If your organisation has no separate CI cluster, Ankra Pipelines runs there too.

```mermaid theme={null}
flowchart LR
    AI[Ankra AI] --> WS[Workspace pod<br/>locked down, shallow clone,<br/>time-limited]
    PR[Pull request] --> PV[Preview<br/>own namespace,<br/>public https URL]
    WS --> Staging[(Staging cluster)]
    PV --> Staging
    DNS["*.previews.example.com<br/>your wildcard DNS"] --> PV
```

```bash theme={null}
ankra org ai-environment get
ankra org ai-environment set --staging-cluster staging
ankra org ai-environment set --workspace-ttl-hours 12 --demo-ttl-hours 48
ankra org ai-environment set --demo-ttl-role-cap member=24 --demo-ttl-role-cap operator=96
ankra org ai-environment set --demo-base-domain previews.example.com
```

* **Workspaces** are locked-down, time-limited pods that shallow-clone a repository so the AI can read and test code. `--workspace-ttl-hours` takes 1 to 168.
* **Previews and demos** run in their own namespace with a public https URL. `--demo-ttl-hours` takes 1 to 720, and `--demo-ttl-role-cap` caps it per role.
* **The preview domain is yours.** Ankra publishes no DNS for `--demo-base-domain`: point a wildcard record at the staging cluster's ingress. The command tells you when a setting would leave previews on plain http.

## Who can change what

| Action | Who |
| - | - |
| Connect Slack, Teams, GitHub, GitLab or Bitbucket | Organisation administrator |
| Change a connection's mode or capabilities, per connection or per repository | Organisation administrator |
| Set the staging cluster and its time limits | Organisation administrator |
| Ask the AI in chat | Any linked member, with their own permissions |
| Request merge when green | A member with `pipelines.operate` and a verified GitHub identity, on an Agent-mode connection |
| Turn an application's auto-fix off | Deploy permission on that application |

## Related

* [AI connections](/platform/ai-connections): connecting Slack and Teams step by step.
* [GitHub](/integrations/github), [GitLab](/integrations/gitlab) and [Bitbucket Cloud](/integrations/bitbucket-cloud): the source-control integrations and their permissions.
* [AI workspaces](/platform/ai-workspaces): what a workspace can and cannot do.


# AI in pull requests
Source: https://docs.ankra.ai/pipelines/ai-in-pull-requests

What Ankra's AI does on a pull request that runs on Ankra Pipelines - the one status comment, the review that reads your diff and your pipeline's result, @ankraai mentions, merge when green, diagnosis and fix pull requests for failed builds, and preview environments.

A pull request on Ankra Pipelines gets more than a check mark. Ankra's AI reads the change and what the pipeline found, explains a failure in plain words, proposes or commits a fix, deploys a preview you can click, and merges when everything is green. All of it lands in **one** comment that updates in place. There is no stream of bot comments to scroll past.

```mermaid theme={null}
flowchart TB
    PR[Pull request opened or pushed] --> Run[Ankra pipeline run]
    PR --> Review[Ankra AI review]
    Run --> Facts[Pipeline facts<br/>failing step, findings,<br/>gate verdict, digest]
    Facts --> Review
    Run -->|build digest| Preview[Preview environment]
    Run -->|failed build| Diagnose[Diagnosis and fix]
    subgraph Comment["One status comment on the pull request"]
        S1[Pipeline]
        S2[Preview]
        S3[Review]
        S4[Promotion]
    end
    Run --> S1
    Preview --> S2
    Review --> S3
    Diagnose --> S1
```

Everything starts switched off. An organisation administrator turns each capability on per connection, or per repository, under **AI** → **Settings** → **Connections** → **Source control & AI review**. See [AI Code Review](/platform/ai-code-review) for every switch.

## The review

### When it runs

| Event | Review? |
| - | - |
| Pull request opened or reopened | Yes |
| A push to the pull request | Yes, for the new head |
| Draft marked ready for review | Yes |
| A draft pull request | No by default. **Review drafts** turns it on |
| A head commit already reviewed | No: one review per commit |
| Past the per-pull-request cap (default 5) or the daily cap | No, and the check run says why |
| `@ankraai review` in a comment | Always. A review someone asks for runs even on a draft or once the cap is reached, and it is added to the pull request's count, so fewer automatic reviews are left after it |

A skipped review is never silent. The **Ankra AI review** check run says why it did not run. The check is advisory: it concludes neutral and never blocks a merge.

### What it reads

The review is more than a diff summary, because it sees what your pipeline saw:

* **The diff**, with line numbers, and the pull request's title and description.
* **Callers of the changed code** in the same repository.
* **Related repositories** you declared, and their references to what changed. A `Depends-on: my-org/other-repo#123` line links a companion pull request. See [Cross-repository review](/platform/ai-code-review-cross-repo).
* **Your pipeline's result for that commit**: the failing step and its error, the scan findings by tool and severity, the gate's verdict and blocking count, and the image digest. Each fact is sourced separately, so a missing one never reads as a clean one.
* **Your organisation's review instructions**, up to 4,000 characters per installation: what to weigh heavily, which conventions to enforce, which language to write in.

The review has no tools and cannot act. Instructions written inside a diff are treated as text to review, never as instructions to follow.

### What it posts

```markdown theme={null}
## Ankra AI review

**Verdict: <looks good | comments | changes requested | no findings>.**

<two to four sentences on the change as a whole>

### Findings

- **[<high | medium | low>] <finding title>** (`<file>:<line>`)
  <what is wrong and why it matters>

---
_Reviewed commit <sha>. This review is read-only and advisory._
```

* **Verdict:** looks good, comments, changes requested, or no findings.
* **Findings:** at most eight, each `high`, `medium` or `low`, each pinned to its line as an inline comment as well. A finding that needs more context is checked against the file and restated or dropped, rather than posted as a guess.
* **One comment, edited in place.** A re-review updates it, and its footer names the commit it reviewed.

## Talk to it: `@ankraai`

With **Mention replies** on, anyone in the pull request can ask:

| You write | It does |
| - | - |
| `@ankraai review` | A full review, now |
| `@ankraai why did the build fail?` | Reads the run and the failing step's log, and explains |
| `@ankraai how would you fix the finding on line 88?` | In **Ask** mode, explains the fix. In **Agent** mode, proposes a ready-to-apply fix and, on GitHub, offers to open it as a pull request |
| `@ankraai merge when green` | Records a merge request (below) |

On GitLab and Bitbucket Cloud, an Agent-mode reply proposes the fix with a branch name and commit message, because Ankra does not open pull requests there.

## Merge when green

Comment **`@ankraai merge when green`**, press the button in the portal, or ask Ankra AI in chat or through MCP. Ankra records the request and merges (squash) the moment every condition holds:

```mermaid theme={null}
flowchart LR
    Req[merge when green] --> A{Agent mode,<br/>verified requester}
    A -->|no| Refuse[Refused, with the reason]
    A -->|yes| W[Watching]
    W --> C{Newest run green<br/>gate passed<br/>approved authority<br/>no changes requested}
    C -->|not yet| W
    C -->|all hold| T{Merge train on?}
    T -->|yes| Train[Joins the train]
    T -->|no| Merge[Squash-merged]
    W -->|new push, or 24 hours| Expire[Request expires]
```

* The connection is in **Agent** mode, and the requester is a member with `pipelines.operate` whose GitHub identity is OAuth-verified. That is re-checked at merge time, not only when the comment was written.
* The newest pipeline run for the head succeeded, and its `gate` passed.
* The run executed under plainly approved authority.
* Ankra's review did not request changes on that commit, and no human reviewer's latest review is **Changes requested**.
* The head is not a fork.

A new push invalidates the request, and it expires after 24 hours. Every refusal is posted once, naming the condition that failed. On a repository with a [merge train](/pipelines/merge-train), the request puts the pull request on the train instead. Merge when green works on GitHub today.

## When a build fails

A failed `build` step, a `gate` that blocked the image, a failed `run` step such as your tests, or a pull request that conflicts with its base, gets attention routed by who owns the branch. Ankra's own infrastructure failures are excluded: they are retried, not "fixed".

```mermaid theme={null}
flowchart TD
    Fail[build failed, gate blocked, test failed,<br/>or the pull request conflicts] --> Where{Which run?}
    Where -->|push to your tracked branch| Mission[Fix mission]
    Mission --> Mode{Connection mode}
    Mode -->|Ask, the default| Propose[Proposes the fix]
    Mode -->|Agent| FixPR[Opens a fix pull request]
    Where -->|Ankra's setup pull request| Commit[Commits the fix to the setup branch]
    Where -->|a pull request from a branch of your repository| Branch[Commits the fix to that branch]
    Where -->|a setup or same-repository pull request<br/>that conflicts with its base| Merge[Merges the base into the branch<br/>with a merge commit]
    Where -->|a pull request from a fork| Diag[Diagnosis in the status comment:<br/>failing step, error class, log excerpt]
    Diag --> Button[You choose Fix with Ankra<br/>on the run]
```

* **A pull request from a branch of your repository is fixed on that branch.** The agent commits to its head branch, opens no second pull request, changes only what the failure needs, and watches the run its commit starts. A conflict is resolved with a merge commit of the base into the head, never into your default branch. See [When a pull request fails its checks](/concepts/applications#when-a-pull-request-fails-its-checks).
* **A fork's pull request is never committed to.** It gets a diagnosis, and a person decides whether to ask for the fix.
* **A fix for your tracked branch never lands on it unattended:** in Agent mode it arrives as a pull request a human merges, in Ask mode as a proposal. One fix mission runs per branch per day.
* **Auto-fix is on by default per application,** and turning it off needs deploy permission on that application. To ask for a fix by hand: `ankra application demo fix-build <application-id>`.

## Previews you can click

With **PR previews** on, every pull request deploys to a throwaway environment on your organisation's staging cluster, from the exact digest its pipeline built, never from a mutable tag. The status comment's preview section shows it building, then a **Visit Preview** link, and it is torn down when the pull request closes.

Previews work on GitHub, and on GitLab and Bitbucket Cloud for applications on Ankra Pipelines. See [PR preview environments](/guides/pr-preview-environments) and [AI Gateway](/pipelines/ai-gateway#the-staging-cluster) for where previews run and how they get a public URL.

## Configure it from the terminal

```bash theme={null}
ankra org ai-review repos list --reachable
ankra org ai-review repos set my-org/my-repo --review --mentions --previews --max-reviews-per-pr 5
ankra org ai-review repos set my-org/my-repo --review-drafts=false
ankra org ai-review related-repos add my-org/api my-org/web
ankra org ai-review repos unset my-org/my-repo
```

`set` changes only the switches you pass, and keeps the rest of the repository's rule. Listing needs membership; `set`, `unset` and related repositories need an organisation administrator.


# Pipeline caching
Source: https://docs.ankra.ai/pipelines/caching

Keep package stores, module caches and build caches warm between runs - cache keys and hashFiles, restore_keys, the trust scopes that stop a branch poisoning main, what Ankra generates per toolchain, and how to read a hit, a miss and a cold start.

A cache keeps directories of the workspace from one run to the next: the pnpm store, the Go module and build caches, a Cargo `target/`, pip wheels. Declare it on the stage that fills it, and the next run of that stage starts warm.

```yaml theme={null}
- name: test
  kind: run
  image: node:24
  needs: [checkout]
  env:
    PNPM_STORE_DIR: /workspace/.ankra-node-cache/pnpm-store
  run: |
    corepack enable
    pnpm install --frozen-lockfile --store-dir "$PNPM_STORE_DIR"
    pnpm test
  cache:
    - key: "pnpm-${{ hashFiles('pnpm-lock.yaml') }}"
      paths: [".ankra-node-cache/pnpm-store"]
      restore_keys: ["pnpm-"]
      fallback: "none"
```

That is all a stage needs. The rest of this page explains what happens around it, so you can trust a cache instead of guessing about it.

## The life of a cache

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Plan as Planner
    participant Restore as Restore (before the step)
    participant Step as Your step
    participant Save as Save (after success)
    participant Vault as Vault

    Plan->>Restore: Key computed after checkout<br/>pnpm-4b1e... from hashFiles
    Restore->>Vault: Exact key?
    alt exact hit
        Vault-->>Restore: Archive for pnpm-4b1e...
    else no exact key
        Restore->>Vault: Newest entry starting with "pnpm-"
        Vault-->>Restore: Closest archive, or nothing
    end
    Restore->>Step: Unpack into .ankra-node-cache/pnpm-store
    Step->>Step: pnpm install (only what changed)
    Step->>Save: Step succeeded
    Save->>Vault: Store under the exact key (once)
```

1. **The key is computed after checkout.** `${{ hashFiles('pnpm-lock.yaml') }}` becomes the SHA-256 of the matching files, read in the stage's `working_directory`. The key changes exactly when the lock file does.
2. **Restore runs before the step.** The exact key wins. Otherwise each `restore_keys` prefix is tried in order, and the newest stored entry that starts with it is restored. A cache that changed slightly still starts nearly warm.
3. **Save runs only after the step succeeds.** A failed, cancelled or timed-out step saves nothing, so a broken install never becomes the next run's starting point.
4. **A key with `hashFiles` is saved once.** When the exact key was restored, its content is already stored. A key with no `hashFiles` is saved again after every successful step, and the newest save wins.

## Trust scopes: a branch can never poison main

A cache is a way for one run to put files into another run's workspace. Ankra treats that as a security boundary, not just a performance feature.

```mermaid theme={null}
flowchart LR
    subgraph Trusted["Default branch scope"]
        MainSave[Runs on main<br/>save here]
        MainCache[(main caches)]
        MainSave --> MainCache
    end

    subgraph Branches["Branch scope"]
        PRSave[Pull requests, feature branches,<br/>manual runs of other refs<br/>save here]
        BranchCache[(branch caches)]
        PRSave --> BranchCache
    end

    MainCache -->|restore fallback| PRRun[Pull request run<br/>starts warm from main]
    BranchCache -->|restore first| PRRun
    BranchCache -.-x|never| MainRun[Run on main]
    MainCache --> MainRun

    Fork[Fork or tag run] -.->|no shared cache| Empty[Empty directories]
```

* **A run on the default branch** restores only what default-branch runs saved.
* **Any other run** (a feature branch, a pull request, a manual run of another ref) looks in its own scope first and then falls back to the default branch's. A new pull request starts warm from `main`.
* **Nothing a branch saves ever reaches a default-branch run.** A less-trusted ref cannot plant a poisoned dependency in what your release build restores.
* **A restricted fork run and a tag run get no shared cache at all.** Every declared path starts empty, and the step records `caches are not shared with fork runs` or `caches are not shared with tag runs`.
* **Scopes are per repository and cluster.** One repository never restores another's cache.

`cache` is a [protected section](/pipelines/how-it-works#logic-is-open-authority-is-closed). A pull request can rewrite its scripts, but it cannot change which earlier output is restored into the workspace until the change reaches the default branch and an administrator approves it.

## Writing good keys

| You want | Write |
| - | - |
| A cache that follows a lock file | `key: "pnpm-${{ hashFiles('pnpm-lock.yaml') }}"` |
| Several files in one key | `key: "go-${{ hashFiles('go.mod', 'go.sum') }}"` |
| Every lock file in a monorepo | `key: "go-${{ hashFiles('**/go.sum') }}"` |
| A warm start when the lock file changed | `restore_keys: ["pnpm-"]` |
| One cache per toolchain version | `key: "cargo-1.85-${{ hashFiles('Cargo.lock') }}"` |
| To start over | Change the prefix: `pnpm-v2-...`. Old entries age out. There is no purge. |

`hashFiles` patterns are relative and `/`-separated. At most one `**` may stand immediately before the file name, and the file name may use `*`. One call takes up to eight patterns, and files under `.git` are never hashed. A pattern that matches no file adds nothing to the key. A key Ankra cannot read this way is used as written, and the step's cache note says so.

> [!TIP]
>
> **Point the toolchain at the workspace.** A cache path is relative to the workspace (`/workspace`). Set the tool's own cache variable in the stage's `env`, for example `GOMODCACHE=/workspace/.ankra-go/mod`, `GOCACHE=/workspace/.ankra-go/cache`, `PNPM_STORE_DIR`, `npm_config_cache`, `UV_CACHE_DIR`, `PIP_CACHE_DIR` or `CARGO_HOME`. A tool that writes to `$HOME` writes outside the workspace, and nothing is kept.

## What Ankra generates for you

The pipeline a new application's setup pull request commits already declares its test stage's caches. They use `fallback: "none"`, live in directories under `.ankra-` that the scan step skips, and point the toolchain at them through `env`. A pipeline you already committed is never rewritten. Copy the block below into it to get the same.

| Toolchain | Key | Paths |
| - | - | - |
| pnpm | `pnpm-${{ hashFiles('pnpm-lock.yaml') }}` | `.ankra-node-cache/pnpm-store`, `.ankra-node-cache/corepack` |
| Yarn | `yarn-${{ hashFiles('yarn.lock') }}` | `.ankra-node-cache/yarn`, `.ankra-node-cache/yarn-global`, `.ankra-node-cache/corepack` |
| npm | `npm-${{ hashFiles('package-lock.json') }}` | `.ankra-node-cache/npm` |
| Go | `go-${{ hashFiles('go.mod', 'go.sum') }}` | `.ankra-go/mod`, `.ankra-go/cache` |
| uv | `uv-${{ hashFiles('uv.lock') }}` | `.ankra-python-cache/uv` |
| Poetry | `poetry-${{ hashFiles('poetry.lock') }}` | `.ankra-python-cache/pip`, `.ankra-python-cache/poetry/cache`, `.ankra-python-cache/poetry/artifacts` |
| Pipenv | `pipenv-${{ hashFiles('Pipfile.lock') }}` | `.ankra-python-cache/pip`, `.ankra-python-cache/pipenv` |
| pip | `pip-${{ hashFiles('requirements.txt') }}` | `.ankra-python-cache/pip` |
| Rust | `cargo-registry-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}` and `cargo-target-` the same | `.ankra-cargo/home/registry`, `.ankra-cargo/home/git`; `.ankra-cargo/target` |

Each key's `restore_keys` is its own prefix (`pnpm-`, `go-`, and so on). In a monorepo, each component's directories carry the component's name (`.ankra-node-cache-web/...` for `web/`), because its test stage runs beside its siblings'.

## Recipes

> [tab] Go
>
> ```yaml theme={null}
> - name: test
>   kind: run
>   image: golang:1.26
>   needs: [checkout]
>   env:
>     GOMODCACHE: /workspace/.ankra-go/mod
>     GOCACHE: /workspace/.ankra-go/cache
>   run: go test ./... -race
>   cache:
>     - key: "go-${{ hashFiles('go.mod', 'go.sum') }}"
>       paths: [".ankra-go/mod", ".ankra-go/cache"]
>       restore_keys: ["go-"]
>       fallback: "none"
> ```
>
> `GOCACHE` holds compiled packages and test results. Restoring it is what lets `go test` print `(cached)` for packages your change did not touch.

> [tab] pnpm
>
> ```yaml theme={null}
> - name: test
>   kind: run
>   image: node:24
>   needs: [checkout]
>   env:
>     PNPM_STORE_DIR: /workspace/.ankra-node-cache/pnpm-store
>     COREPACK_HOME: /workspace/.ankra-node-cache/corepack
>   run: |
>     corepack enable
>     pnpm install --frozen-lockfile --store-dir "$PNPM_STORE_DIR"
>     pnpm test
>   cache:
>     - key: "pnpm-${{ hashFiles('pnpm-lock.yaml') }}"
>       paths: [".ankra-node-cache/pnpm-store", ".ankra-node-cache/corepack"]
>       restore_keys: ["pnpm-"]
>       fallback: "none"
> ```

> [tab] Python (uv)
>
> ```yaml theme={null}
> - name: test
>   kind: run
>   image: ghcr.io/astral-sh/uv:python3.13-bookworm
>   needs: [checkout]
>   env:
>     UV_CACHE_DIR: /workspace/.ankra-python-cache/uv
>   run: |
>     uv sync --frozen
>     uv run pytest --junitxml=reports/junit.xml
>   cache:
>     - key: "uv-${{ hashFiles('uv.lock') }}"
>       paths: [".ankra-python-cache/uv"]
>       restore_keys: ["uv-"]
>       fallback: "none"
> ```

> [tab] Rust
>
> ```yaml theme={null}
> - name: test
>   kind: run
>   image: rust:1.85
>   needs: [checkout]
>   env:
>     CARGO_HOME: /workspace/.ankra-cargo/home
>     CARGO_TARGET_DIR: /workspace/.ankra-cargo/target
>   run: cargo test --locked
>   cache:
>     - key: "cargo-registry-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}"
>       paths: [".ankra-cargo/home/registry", ".ankra-cargo/home/git"]
>       restore_keys: ["cargo-registry-"]
>       fallback: "none"
>     - key: "cargo-target-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}"
>       paths: [".ankra-cargo/target"]
>       restore_keys: ["cargo-target-"]
>       fallback: "none"
> ```
>
> Two caches, so a new dependency invalidates the target directory without throwing away the registry download.

## Did my cache work?

Every step records one result for all its caches, and one entry per cache. `ankra pipeline get` shows the result in the **CACHE** column, and the portal's run timeline shows it as a chip on the step.

```bash theme={null}
ankra pipeline get <run-id>                    # CACHE column per step
ankra pipeline get <run-id> --step test        # one row per cache: outcome, bytes, time, saved
```

| `cache_result` | Meaning |
| - | - |
| `hit` | Every declared cache was restored, by its exact key or a `restore_keys` prefix |
| `partial` | Some caches were restored and others were not |
| `miss` | Nothing was stored yet for any declared cache. Normal on a first run or a new key |
| `restore_failed` | No cache was restored and at least one restore failed. The step ran cold because something broke |
| `disabled` | No cache was shared with the step, for example a fork run, or `fallback: none` on an older agent |
| `unknown` | Nothing was reported. Never read it as a miss |

A failed restore never fails the step. The step starts cold and logs a line starting `[ankra] cache` that says why: the key could not be computed (`key_unresolvable`), the archive did not download or unpack, or the restore pod was not scheduled or timed out.

## Limits and retention

| Limit | Value |
| - | - |
| One saved path | 4 GiB. A larger one is not kept |
| Per repository | 10 GiB across both trust scopes, least recently used removed first |
| Retention | An entry nothing restored for `ci_cache_retention_days` (default 14, 1 to 365) is removed |
| Largest declared cache | `max_cache_size` on the organisation's pipeline policy, when an administrator sets one |

**On an older agent.** Caches are stored as archives in the vault on clusters whose agent supports it. On an older agent, `fallback: volume` (the default) gives each path one 5Gi volume shared by runs of the same trust scope on that cluster, and `fallback: none` gives the step an empty directory. Prefer `none` for a cache that is only an optimisation: a shared volume attaches to one node at a time, so two overlapping runs could wait on each other. Upgrade the agent (`ankra cluster agent upgrade`) to get archives.

## Image builds cache their layers for you

A `build` stage needs no `cache:` block. Every image build imports and exports a BuildKit **layer cache** in your organisation's CI staging repository, next to the images it builds, one per component. An unchanged `RUN pnpm install` layer is pulled, not rebuilt.

* The cache is written only by runs that may push. A restricted fork run neither reads nor writes it.
* A failed cache write never fails the build.
* `build.cache_to` in your pipeline is used only when no organisation cache could be resolved.

To get the most from it, order your Dockerfile so what changes least comes first: copy the lock file and install dependencies before you copy the source.

## Set a cache once for every stage

`defaults.cache` applies to every stage that declares no `cache` of its own, the same way `defaults.image` and `defaults.network` do.

## Caching is one of three ways to save time

A warm cache makes the work you run faster. Two other features stop you running work at all:

* **[Affected-only stages](/pipelines/fast-ci#run-only-what-a-change-touches)** skip tests that a change cannot reach, using your Go or pnpm dependency graph.
* **[Promotion](/pipelines/fast-ci#build-once-promote-on-merge)** publishes the image a pull request already built and tested, instead of rebuilding it on merge.

Every run records the time all three saved. `ankra pipeline time-saved` totals it for your organisation.


# Pipelines from the CLI and MCP
Source: https://docs.ankra.ai/pipelines/cli-and-mcp

Drive Ankra Pipelines from the terminal and from any MCP client - the commands you reach for every day, scripting with stable exit codes and JSON, and the MCP tools an AI uses to validate, convert, watch and debug a pipeline, with worked scenarios for each.

Everything you can see on a run page, you can get from the `ankra` CLI and from the Ankra [MCP server](/platform/mcp-server). The CLI is for you and your scripts. MCP is for the AI you work with: Claude Code, Codex, Cursor, the Claude app, or Ankra's own chat.

```mermaid theme={null}
flowchart LR
    You([You]) --> CLI[ankra CLI]
    Script([CI job, release script]) --> CLI
    Agent([Claude Code, Codex,<br/>Cursor, Claude app]) --> MCP[Ankra MCP server]
    Chat([Ankra AI chat]) --> MCP
    CLI --> API[Ankra platform]
    MCP --> API
    API --> Runs[(Runs, steps, logs,<br/>findings, train)]
```

## The commands you will use every day

Run these from inside your repository's checkout. The CLI resolves the pipeline from your `origin` remote and the commit from your `HEAD`, and says which it used. Outside a checkout, name the pipeline with `--application <name>` or `--repository <id>`.

| You want to | Run |
| - | - |
| Start a run for the commit in front of you | `ankra pipeline run --wait` |
| See the latest runs | `ankra pipeline list` |
| See one run and its steps | `ankra pipeline get <run>` |
| Follow a step live | `ankra pipeline logs <run> --step test --follow` |
| Re-run only what failed | `ankra pipeline rerun <run> --failed-only --wait` |
| Run everything, ignoring path filters | `ankra pipeline run --full --wait` |
| Stop a run | `ankra pipeline cancel <run>` |
| See scan findings | `ankra pipeline findings <run>` |
| Download a report or artifact | `ankra pipeline artifacts <run>`, then `ankra pipeline artifacts download <artifact-id>` |
| Check the pipeline file before pushing | `ankra pipeline validate --changed-file src/app.ts` |
| See the slowest and flaky tests | `ankra pipeline tests <run> --slowest` |
| Queue a pull request on the merge train | `ankra pipeline train add 412` |
| See what fast CI saved | `ankra pipeline time-saved` |

## Scripting: exit codes and JSON

Every command takes `-o json`, and the commands that wait exit with the verdict. That makes the CLI safe to put in a release script or another CI system.

| Exit code | Meaning |
| - | - |
| `0` | The run succeeded |
| `1` | It concluded any other way (failure, cancelled, timed out, superseded), or the platform could not be read |
| `2` | Several runs matched your selection and you did not pass `--latest` |
| `3` | No run matched |
| `5` | `--timeout` ran out, or under `--exit-code` the run has not concluded yet |

Without `--wait`, `--watch` or `--exit-code`, a read always exits `0`, whatever the run's outcome.

### Scenario: wait for the run a push started

A push started the run, so your script has no run id. Select it by what you do know:

```bash theme={null}
ankra pipeline get --head-sha "$(git rev-parse HEAD)" --trigger push --latest --wait --timeout 45m
```

If the webhook lands a moment after you ask, `--wait` waits for the run to appear.

### Scenario: react to every state change

```bash theme={null}
ankra pipeline get <run-id> --watch -o json | while read -r event; do
  echo "$event" | jq -r 'select(.event == "step") | "\(.step_key): \(.status) \(.outcome // "")"'
done
```

`--watch -o json` prints one JSON object per line. The first lines are the current state, and the run's conclusion is always the last line.

### Scenario: gate a release on the pipeline

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail
sha="$(git rev-parse HEAD)"
if ankra pipeline get --head-sha "$sha" --branch main --latest --exit-code >/dev/null; then
  echo "Commit $sha is green, releasing"
else
  echo "Commit $sha is not green yet" >&2
  exit 1
fi
```

### Scenario: debug a red run

```bash theme={null}
ankra pipeline get <run-id>                         # which step failed, its exit code, the error
ankra pipeline logs <run-id> --step test            # its complete archived log
ankra pipeline tests <run-id>                       # failed and flaky tests with messages
ankra pipeline rerun <run-id> --failed-only --wait  # retry just the failed steps
```

## Settings and capacity from the terminal

| You want to | Run | Needs |
| - | - | - |
| See the organisation's CI settings | `ankra org ci-settings get` | Membership |
| Choose the CI cluster | `ankra org ci-settings set --cluster <cluster>` | Organisation admin |
| Add a cluster to the CI pool | `ankra org ci-settings pool add <cluster>` | Organisation admin |
| Allow more runs at once | `ankra org ci-settings set --max-parallel-runs 32` | Organisation admin |
| Make the image gate stricter | `ankra org ci-settings set --image-gate all` | Organisation admin |
| Turn on pipeline workers on a cluster | `ankra cluster agent ci set --workers 8 --cluster <cluster>` | Cluster manage |
| Pin CI to a node group | `ankra cluster agent ci set --node-group pipelines --cluster <cluster>` | Cluster manage |
| Connect a repository with no application | `ankra pipeline repositories connect --provider github --owner my-org --name my-repo --credential <git-credential>` | `pipelines.manage` |
| Approve a definition's authority | `ankra pipeline definitions approve <definition-id>` | `pipelines.manage`, a person |

Approving authority is always a human act. A service token or an AI agent is refused, because approving grants whatever secrets, credentials and network the definition declares.

## MCP: the tools an AI uses

Connect the [MCP server](/platform/mcp-server) once, and your AI client can read and reason about your pipelines. Every read tool works in **Ask** mode and with an `mcp:read` token.

| Tool | What it does | Reads or writes |
| - | - | - |
| `cicd_validate_pipeline_yaml` | Validates a `.ankra/pipeline.yaml`. Returns `ok`, `warn` or `fatal`, every violation by key, the stages and the trigger events | Read |
| `cicd_convert_workflow_to_pipeline` | Converts GitHub Actions, GitLab CI, Bitbucket Pipelines or CircleCI files into one pipeline, with notes on everything it could not map. Writes nothing | Read |
| `cicd_propose_application_pipeline` | Renders the pipeline, manifests and optionally a Dockerfile Ankra would generate for a repository, with validator results | Read |
| `watch_pipeline_run` | Waits for a run to conclude and returns the failing step, a log tail, findings and the gate verdict | Read |
| `get_pipeline_step_logs` | Reads a run's steps and one step's archived log tail, by run id, run number, branch, pull request or commit | Read |
| `get_application_code_security`, `get_application_container_security` | The application's scan findings | Read |
| `scm_merge_pull_request` | Records a merge when green request, or joins the merge train where the repository has one. Never merges at once | Write: `mcp:write` and Agent mode |

> [!NOTE]
>
> **Over MCP, `watch_pipeline_run` waits up to 45 seconds per call.** It returns the concluded run, or `timed_out: true` with the run id. Your client calls it again with that id. Inside Ankra's own chat the same tool registers a watch and wakes the conversation when the run concludes.

There is deliberately no MCP tool that approves a pipeline's authority, and none that dispatches, cancels or re-runs an Ankra pipeline. An AI can explain, validate, convert and watch. Starting and approving runs stays with you and your scripts through the CLI.

### Scenario prompts

These are prompts to type into your AI client once the MCP server is connected.

> [accordion] Is my pull request green, and if not, why?
>
> > Watch the Ankra pipeline run for my-org/my-repo pull request 412. When it concludes, tell me which step failed and the likely cause from its log.
>
> The AI calls `watch_pipeline_run` with `owner`, `repo` and the pull request, then `get_pipeline_step_logs` for the failing step.

> [accordion] Move this repository off GitHub Actions
>
> > Convert .github/workflows/ci.yml and release.yml into an Ankra pipeline. Validate the result and list every step you could not map.
>
> The AI reads your workflow files, calls `cicd_convert_workflow_to_pipeline`, then `cicd_validate_pipeline_yaml` on the output. You review and commit the file.

> [accordion] Check my pipeline edit before I push
>
> > Validate my .ankra/pipeline.yaml. I added a matrix to the test stage and a postgres service.
>
> `cicd_validate_pipeline_yaml` returns every violation by key. A `fatal` cannot be planned. A `warn` names, for example, a stage kind with no executor yet.

> [accordion] Merge it when it passes
>
> > Merge my-org/my-repo pull request 412 when its pipeline is green.
>
> With an `mcp:write` token and a connection in Agent mode, the AI calls `scm_merge_pull_request`. Ankra records the request and merges only when the run, its gate, both reviews and the authority all pass. With a merge train, the pull request joins the train.

> [accordion] Why is my build slow?
>
> > Look at the last Ankra pipeline runs on main for my-org/my-repo and tell me which steps take longest and whether the caches hit.
>
> The AI reads the runs and step logs. Combine it with `ankra pipeline get <run> --step <key>`, which prints each cache's outcome, size and time.

## Next

* [Pipelines with coding agents](/pipelines/coding-agents): connect Claude Code, Codex or the Claude app, and install the Ankra skills.
* [CLI reference: pipeline](/reference/cli/pipeline): every flag of every command.
* [MCP tools](/platform/mcp-tools): the full MCP catalogue.


# Pipelines with Claude Code, Codex and the Claude app
Source: https://docs.ankra.ai/pipelines/coding-agents

Let your coding agent write, validate, watch and fix your Ankra pipeline - connect the Ankra MCP server and install the Ankra skills in Claude Code, Codex and the Claude app, then use the edit, push, watch, fix loop with prompts that work.

Your coding agent already writes the code. With Ankra connected, it can also see whether that code passes CI, read why it failed, and fix it. No copying logs out of a web page, no guessing which step broke.

Two things make that work, and you want both:

* **The Ankra MCP server** gives the agent live data: validate a pipeline, convert a workflow, watch a run, read a step's log, request merge when green.
* **The Ankra skills** teach the agent how Ankra pipelines work: the stage kinds, the authority rules, caching, fast CI. It then writes a pipeline that validates the first time instead of a GitHub Actions workflow.

The agent can also run the `ankra` CLI in its terminal, which covers everything the MCP tools do not, such as starting a run.

## The loop your agent runs

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor You
    participant Agent as Coding agent
    participant MCP as Ankra MCP
    participant Git as Git host
    participant CI as Ankra Pipelines

    You->>Agent: "Add a Postgres integration test and get it green"
    Agent->>Agent: Edit code and .ankra/pipeline.yaml
    Agent->>MCP: cicd_validate_pipeline_yaml
    MCP-->>Agent: ok (or every violation by key)
    Agent->>Git: git push
    Git->>CI: Webhook starts the run
    Agent->>MCP: watch_pipeline_run (head_sha)
    MCP-->>Agent: failed: e2e step, exit 1, log tail
    Agent->>MCP: get_pipeline_step_logs (step e2e)
    Agent->>Agent: Fix the cause
    Agent->>Git: git push
    Agent->>MCP: watch_pipeline_run
    MCP-->>Agent: success, gate passed
    Agent-->>You: Green, here is the summary
```

The agent never needs your CI provider's web page, and you never paste a log into a chat.

## Set up

> [tab] Claude Code
>
> **1. Connect the Ankra MCP server**
>
> ```bash theme={null}
> claude mcp add --transport http --scope user ankra https://platform.ankra.app/api/v1/mcp
> ```
>
> Start Claude Code, run `/mcp`, select **ankra** and choose **Authenticate**. Sign in, pick your organisation and approve. `mcp:read` is enough to validate, convert and watch. Grant `mcp:write` only if you want the agent to request merge when green.
>
> **2. Install the Ankra skills**
>
> ```bash theme={null}
> ankra skills install --client claude-code
> ```
>
> The skills land in `~/.claude/skills`, with the `/ankra-*` workflow commands in `~/.claude/commands`. Claude Code picks the right one from what you ask. `ankra-ship` and `ankra-cicd` cover pipelines.
>
> **3. Check it works**
>
> Ask: *"Validate .ankra/pipeline.yaml with Ankra."* Claude Code should call `cicd_validate_pipeline_yaml` and report `ok`, `warn` or `fatal`.

> [tab] Codex
>
> **1. Create an MCP token**
>
> ```bash theme={null}
> ankra tokens create codex --scopes mcp:read
> export ANKRA_MCP_TOKEN="<your-token>"
> ```
>
> Use `--scopes mcp:read,mcp:write` if the agent should request merge when green. Keep the variable in your shell profile, not in a repository.
>
> **2. Connect the Ankra MCP server**
>
> ```bash theme={null}
> codex mcp add ankra --url https://platform.ankra.app/api/v1/mcp --bearer-token-env-var ANKRA_MCP_TOKEN
> ```
>
> That writes the server into `~/.codex/config.toml`. `codex mcp list` shows it.
>
> **3. Install the Ankra skills**
>
> ```bash theme={null}
> ankra skills install --client codex
> ```
>
> The skills land in `~/.codex/skills`, with an index in `~/.codex/AGENTS.md` that Codex always loads, and prompts in `~/.codex/prompts`. Add `--dir .` to install into the repository instead, and commit it so your whole team's Codex gets it.

> [tab] Claude app
>
> **1. Add Ankra as a connector**
>
> In Claude (web or desktop), open **Settings** → **Connectors** → **Add** → **Add custom connector**. Name it `Ankra`, set the URL to `https://platform.ankra.app/api/v1/mcp`, leave the OAuth fields empty, and select **Add**. Then select **Connect** and sign in to Ankra. Custom connectors need a paid Claude plan. See [MCP server](/platform/mcp-server#connect-claude-with-oauth) for screenshots.
>
> **2. Upload the Ankra skills**
>
> ```bash theme={null}
> ankra skills install --client claude-app
> ```
>
> This writes one `.zip` per skill under `~/.ankra/claude-app`. Upload `ankra-cicd` and `ankra-ship` (or all of them) at **Settings** → **Capabilities** → **Skills** → **Upload skill**.
>
> **3. Use it**
>
> The Claude app cannot push to your repository, but it can read your pipelines. Ask it to explain a red run, convert a pasted workflow, or review a pipeline file you paste in.

## Prompts that work

These are written for an agent with the MCP server connected and the skills installed. Replace `my-org/my-repo` with your repository.

> [accordion] Put this repository on Ankra Pipelines
>
> > This repository has no CI yet. Write an .ankra/pipeline.yaml that tests on every pull request and push to main, caches dependencies, and builds, scans, gates and publishes the image on push. Validate it with Ankra before you show me.
>
> The `ankra-cicd` skill steers the agent to the right stage kinds, network tiers and cache directories. `cicd_validate_pipeline_yaml` catches anything wrong before you commit.

> [accordion] Convert our GitHub Actions
>
> > Convert everything under .github/workflows into one Ankra pipeline. Keep the matrix and the Postgres service. List every step you could not convert, and delete the workflow files in the same change.
>
> The agent calls `cicd_convert_workflow_to_pipeline`, which returns the pipeline plus notes for every step it could not map one to one.

> [accordion] Get my pull request green
>
> > Push this branch, watch the Ankra pipeline for my-org/my-repo, and if it fails, read the failing step's log, fix the cause and push again. Stop after three attempts and tell me what you changed.
>
> `watch_pipeline_run` returns the failing step and a log tail. `get_pipeline_step_logs` gets more of the log when the tail is not enough.

> [accordion] Make CI faster
>
> > Our pull request runs take too long. Add affected: to the Go and pnpm test stages, path sets for the components, and caches where they are missing. Show me with ankra pipeline validate --changed-file which stages a change to web/ would skip.
>
> The agent edits the pipeline and runs the CLI to prove the plan, as described in [Fast CI](/pipelines/fast-ci).

> [accordion] Merge it when it is green
>
> > Request merge when green for my-org/my-repo pull request 412.
>
> This needs `mcp:write` and a connection in **Agent** mode. Ankra merges only when the pipeline, its gate, both reviews and the authority all pass. On a repository with a [merge train](/pipelines/merge-train), the pull request joins the train.

## What the agent cannot do, by design

Ankra keeps the decisions that grant power with people:

* **No agent can approve a pipeline's authority.** Approval grants secrets, credentials and network access, so it needs a person with `pipelines.manage` (`ankra pipeline definitions approve`). A pull request the agent writes that adds a secret runs without it until a person approves on the default branch.
* **No agent can merge around your rules.** Merge when green waits for every condition, refuses forks, and is refused outright on a connection in **Ask** mode.
* **The token is the boundary.** An `mcp:read` token cannot call a write tool at all. Give an agent `mcp:write` only where you want it to act.
* **Fork pull requests stay restricted** whoever opened them: no secrets, no credentials, no shared caches.

## When the agent is Ankra's own

You do not need a coding agent on your laptop to get this loop. Ankra's own AI does it inside the platform:

* In **Ankra chat**, ask it to watch a run. It wakes the conversation with the failing step, the log tail, findings and the gate verdict.
* On a **pull request**, the [AI review](/pipelines/ai-in-pull-requests) reads your pipeline's result and findings, and a failed build gets a diagnosis in the pull request's status comment.
* From **Slack or Teams**, the [AI Gateway](/pipelines/ai-gateway) answers questions about your runs and can investigate a failed build.


# Pipeline examples
Source: https://docs.ankra.ai/pipelines/examples

Complete, copy-ready .ankra/pipeline.yaml files for real shapes of repository - a Go service that builds once and promotes on merge, a pnpm and Go monorepo that tests only what changed, a Python API with a Postgres sidecar and a version matrix, a tests-only repository with no application, a nightly suite with a manual dispatch, and a tagged release.

Each example is a complete file. Copy one, change the names, and validate it before you commit:

```bash theme={null}
ankra pipeline validate .ankra/pipeline.yaml
```

For one stage per language, see [Starter pipelines](/guides/ankra-ci-starter-pipelines). For every key, see the [pipeline.yaml reference](/guides/pipeline-reference).

## A Go service that builds once

Tests run on every pull request and push. The image is built, scanned and gated on both, and published only on push. A merge publishes the image the pull request already tested instead of rebuilding it.

```mermaid theme={null}
flowchart LR
    checkout --> test[test<br/>go test, cached]
    test --> build --> scan --> gate{gate}
    gate -->|push| publish[[publish<br/>promote_from: pull_request]]
```

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "orders-api"
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
    fork_policy: "read_only"
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
workspace:
  size: "10Gi"
  access: "rwo"
defaults:
  image: "golang:1.26"
  timeout: "30m"
  network: "egress-https"
permissions:
  contents: "read"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "test"
    kind: "run"
    needs: ["checkout"]
    env:
      GOMODCACHE: "/workspace/.ankra-go/mod"
      GOCACHE: "/workspace/.ankra-go/cache"
    run: "go run gotest.tools/gotestsum@v1.13.0 --jsonfile test-results.json -- ./... -race"
    cache:
      - key: "go-${{ hashFiles('go.mod', 'go.sum') }}"
        paths: [".ankra-go/mod", ".ankra-go/cache"]
        restore_keys: ["go-"]
        fallback: "none"
    artifacts:
      - name: "test-results"
        paths: ["test-results.json"]
    test_results:
      - format: "go-test"
        path: "test-results.json"
  - name: "build"
    kind: "build"
    needs: ["test"]
    build:
      dockerfile: "Dockerfile"
      provenance: true
      sbom: true
  - name: "scan"
    kind: "scan"
    needs: ["build"]
    scan:
      scanners: ["semgrep", "checkov", "trivy"]
      fail_on:
        semgrep: "error"
  - name: "gate"
    kind: "gate"
    needs: ["scan"]
    gate:
      require_stages: ["scan"]
  - name: "publish"
    kind: "publish"
    needs: ["gate"]
    when:
      events: ["push"]
    publish:
      promote_from: "pull_request"
```

* `test_results` turns the JSON report into the run's **Tests** section, with flaky tests detected from retries. The report is also listed under `artifacts`, which is what uploads it.
* `promote_from` is a protected section, so it takes effect once an administrator approves the definition on `main`.

## A monorepo that tests only what changed

A pnpm web app and a Go API in one repository. Each test stage follows its own dependency graph, so a change to a shared Go library runs the API tests and skips the web tests. A change to a shared pnpm package does the opposite.

```mermaid theme={null}
flowchart LR
    checkout --> tw[test-web<br/>affected: pnpm @acme/web]
    checkout --> ta[test-api<br/>affected: go ./...]
    tw --> bw[build-web] --> sw[scan-web] --> gw{gate-web} --> pw[[publish-web]]
    ta --> ba[build-api] --> sa[scan-api] --> ga{gate-api} --> pa[[publish-api]]
```

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "shop"
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
defaults:
  timeout: "30m"
  network: "egress-https"
path_sets:
  pipeline: [".ankra/**"]
  web: ["web/**", "packages/**", "pnpm-lock.yaml", { set: pipeline }]
  api: ["api/**", "libs/**", "go.work", { set: pipeline }]
stages:
  - name: "checkout"
    kind: "checkout"

  - name: "test-web"
    kind: "run"
    image: "node:24"
    needs: ["checkout"]
    affected:
      pnpm: ["@acme/web"]
    env:
      PNPM_STORE_DIR: "/workspace/.ankra-node-cache-web/pnpm-store"
    run: |
      corepack enable
      pnpm install --frozen-lockfile --store-dir "$PNPM_STORE_DIR"
      pnpm --filter @acme/web... test
    cache:
      - key: "pnpm-${{ hashFiles('pnpm-lock.yaml') }}"
        paths: [".ankra-node-cache-web/pnpm-store"]
        restore_keys: ["pnpm-"]
        fallback: "none"

  - name: "test-api"
    kind: "run"
    image: "golang:1.26"
    needs: ["checkout"]
    working_directory: "api"
    affected:
      go: ["./..."]
    paths: ["migrations/**"]
    env:
      GOMODCACHE: "/workspace/.ankra-go-api/mod"
      GOCACHE: "/workspace/.ankra-go-api/cache"
    run: "go test ./..."
    cache:
      - key: "go-${{ hashFiles('api/go.mod', 'api/go.sum') }}"
        paths: [".ankra-go-api/mod", ".ankra-go-api/cache"]
        restore_keys: ["go-"]
        fallback: "none"

  - name: "build-web"
    kind: "build"
    needs: ["test-web"]
    when:
      paths: [{ set: web }]
    build:
      context: "web"
      dockerfile: "web/Dockerfile"
  - name: "scan-web"
    kind: "scan"
    needs: ["build-web"]
    working_directory: "web"
    scan:
      scanners: ["semgrep", "trivy"]
  - name: "gate-web"
    kind: "gate"
    needs: ["scan-web"]
    gate:
      require_stages: ["scan-web"]
  - name: "publish-web"
    kind: "publish"
    needs: ["gate-web"]
    when:
      events: ["push"]

  - name: "build-api"
    kind: "build"
    needs: ["test-api"]
    when:
      paths: [{ set: api }]
    build:
      context: "api"
      dockerfile: "api/Dockerfile"
  - name: "scan-api"
    kind: "scan"
    needs: ["build-api"]
    working_directory: "api"
    scan:
      scanners: ["semgrep", "trivy"]
  - name: "gate-api"
    kind: "gate"
    needs: ["scan-api"]
    gate:
      require_stages: ["scan-api"]
  - name: "publish-api"
    kind: "publish"
    needs: ["gate-api"]
    when:
      events: ["push"]
```

* The `-web` and `-api` suffixes tie each build to its component, so `publish-web` can only ever re-tag the web image. The application has to record components named `web` and `api` (in [`.ankra/ankra.yaml`](/reference/application-descriptor#components), or from its analysis). Otherwise `ankra pipeline validate` warns that both builds would publish to one repository.
* `when.paths` on each build skips that component's whole chain (build, scan, gate, publish) when nothing of it changed. `affected:` on the test stages goes deeper than paths: it follows imports.
* Check the plan before you push: `ankra pipeline validate --changed-file libs/auth/token.go`.

## A Python API with Postgres and a version matrix

The tests run against a real Postgres sidecar on three Python versions, side by side.

```mermaid theme={null}
flowchart LR
    checkout --> t1[test 3.11] & t2[test 3.12] & t3[test 3.13]
    pg[(postgres:16 sidecar)] -.-> t1 & t2 & t3
```

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "billing-api"
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
defaults:
  timeout: "20m"
  network: "egress-https"
services:
  postgres:
    image: "postgres:16"
    env:
      POSTGRES_PASSWORD: "test"
      POSTGRES_DB: "billing"
    ports: ["5432"]
    ready:
      tcp: "5432"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "test"
    kind: "run"
    image: "python:${{ matrix.python }}-slim"
    needs: ["checkout"]
    matrix:
      python: ["3.11", "3.12", "3.13"]
    services: ["postgres"]
    network: "services"
    env:
      DATABASE_URL: "postgresql://postgres:test@postgres:5432/billing"
      PIP_CACHE_DIR: "/workspace/.ankra-python-cache/pip"
    run: |
      pip install -r requirements.txt
      pytest --junitxml=reports/junit.xml
    cache:
      - key: "pip-${{ matrix.python }}-${{ hashFiles('requirements.txt') }}"
        paths: [".ankra-python-cache/pip"]
        restore_keys: ["pip-${{ matrix.python }}-"]
        fallback: "none"
    artifacts:
      - name: "junit"
        paths: ["reports/junit.xml"]
    test_results:
      - format: "pytest"
        path: "reports/junit.xml"
    resources:
      cpu: "2"
      memory: "2Gi"
```

* `network: services` lets the stage reach its sidecar by name. It is a protected tier, so it applies after an administrator approves the definition.
* The matrix value is part of the cache key, so each Python version keeps its own wheels.

## A repository with no application

A library, a docs site or a platform repository needs tests, not a deploy. Connect it as a bare repository, and the pipeline needs no `build` or `publish` at all.

```bash theme={null}
ankra pipeline repositories connect --provider github --owner my-org --name my-library \
  --credential <git-credential> --default-branch main
```

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "my-library"
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
defaults:
  image: "rust:1.85"
  timeout: "30m"
  network: "egress-https"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "lint"
    kind: "run"
    needs: ["checkout"]
    run: |
      rustup component add clippy rustfmt
      cargo fmt --check
      cargo clippy --locked -- -D warnings
  - name: "test"
    kind: "run"
    needs: ["checkout"]
    env:
      CARGO_HOME: "/workspace/.ankra-cargo/home"
      CARGO_TARGET_DIR: "/workspace/.ankra-cargo/target"
    run: "cargo test --locked"
    cache:
      - key: "cargo-registry-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}"
        paths: [".ankra-cargo/home/registry", ".ankra-cargo/home/git"]
        restore_keys: ["cargo-registry-"]
        fallback: "none"
      - key: "cargo-target-${{ hashFiles('Cargo.toml', 'Cargo.lock') }}"
        paths: [".ankra-cargo/target"]
        restore_keys: ["cargo-target-"]
        fallback: "none"
  - name: "audit"
    kind: "scan"
    needs: ["checkout"]
    scan:
      scanners: ["semgrep", "trivy"]
```

`lint` and `test` start together. A `scan` without a `build` scans the source tree.

## A nightly suite and a manual dispatch

Pull requests run the fast tests. A schedule runs the slow end-to-end suite every weekday night, and anyone can dispatch it by hand against a chosen environment.

```mermaid theme={null}
flowchart LR
    subgraph PR["Every pull request"]
        c1[checkout] --> unit
    end
    subgraph Nightly["Weekday nights, or manual"]
        c2[checkout] --> e2e[e2e against inputs.environment]
    end
```

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "storefront"
on:
  pull_request:
    branches: ["main"]
  schedule:
    - cron: "0 2 * * 1-5"
      branch: "main"
      stages: ["checkout", "e2e"]
  manual:
    inputs:
      - name: "environment"
        type: "choice"
        enum: ["staging", "production"]
        default: "staging"
defaults:
  image: "mcr.microsoft.com/playwright:v1.56.0-noble"
  network: "egress-https"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "unit"
    kind: "run"
    needs: ["checkout"]
    when:
      events: ["pull_request"]
    run: "npm ci && npm test"
  - name: "e2e"
    kind: "run"
    needs: ["checkout"]
    when:
      events: ["schedule", "manual"]
    timeout: "90m"
    env:
      TARGET_ENVIRONMENT: "${{ inputs.environment }}"
    run: |
      npm ci
      npx playwright test --reporter=json > reports/playwright.json
    artifacts:
      - name: "playwright"
        paths: ["reports/playwright.json"]
    test_results:
      - format: "playwright"
        path: "reports/playwright.json"
on_failure:
  - name: "collect-traces"
    kind: "run"
    run: "tar czf reports/traces.tgz test-results || true"
    artifacts:
      - name: "traces"
        paths: ["reports/traces.tgz"]
```

Dispatch it by hand:

```bash theme={null}
ankra pipeline run --input environment=production --wait
```

* `stages` on the schedule names exactly what the nightly runs, `checkout` included. A re-run of a red nightly repeats the nightly, not the whole pipeline.
* Cron fields are numeric only (`1-5`, not `MON-FRI`).
* `on_failure` stages run after the main stages, and only when one of them failed. Here it keeps the Playwright traces of a red night. A failed run already raises `pipeline_run_failed`, which your [notification rules](/guides/notification-routing) send to Slack or Teams.

## A tagged release

A push of a `v*` tag builds, scans and gates, then publishes with a moving `latest` tag and a numbered version tag beside the usual `sha-` tag.

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Pipeline
metadata:
  name: "agent"
on:
  push:
    branches: ["main"]
  tag:
    patterns: ["v*"]
defaults:
  timeout: "30m"
  network: "egress-https"
stages:
  - name: "checkout"
    kind: "checkout"
  - name: "build"
    kind: "build"
    needs: ["checkout"]
    build:
      dockerfile: "Dockerfile"
      provenance: true
      sbom: true
  - name: "scan"
    kind: "scan"
    needs: ["build"]
    scan:
      scanners: ["trivy", "semgrep"]
  - name: "gate"
    kind: "gate"
    needs: ["scan"]
    gate:
      require_stages: ["scan"]
  - name: "publish"
    kind: "publish"
    needs: ["gate"]
    when:
      events: ["tag"]
    publish:
      tags: ["latest", "1.${{ ankra.run.number }}.0"]
```

Each extra tag is a manifest re-tag of the one gate-approved digest. No layer is pushed again. A registry that refuses a tag, for example through a tag-immutability rule, fails the step and names the tag, so a `latest` that did not move never reads as published.

## A matrix across operating systems and architectures

`runs_on` places one leg per architecture on matching nodes of your CI cluster.

```yaml theme={null}
- name: "test"
  kind: "run"
  image: "golang:1.26"
  needs: ["checkout"]
  matrix:
    arch: ["amd64", "arm64"]
  runs_on:
    node_selector:
      kubernetes.io/arch: "${{ matrix.arch }}"
  run: "go test ./..."
```

`runs_on` is a protected section, and the organisation's pipeline policy decides which node selectors a pipeline may ask for. Your CI cluster needs nodes of each architecture.


# Fast CI
Source: https://docs.ankra.ai/pipelines/fast-ci

Make pipelines fast without making them unsafe - skip what a change cannot reach with path filters and the Go and pnpm dependency graph, let the newest commit win, honour [skip ci] where it is safe, build once and promote on merge, and see exactly how much time each run saved.

The fastest step is the one that does not run. Ankra Pipelines gives you five ways to skip work, and each one is built to fail safe. When Ankra cannot prove a skip is safe, the stage runs.

| Technique | What it saves | Where it is set |
| - | - | - |
| [Path filters](#run-only-what-a-change-touches) | Stages whose files did not change | `paths:` and `when.paths` on a stage, `on.<event>.paths` on the pipeline |
| [Dependency graph](#follow-the-imports-affected) | Tests a change cannot reach through imports | `affected:` on a stage |
| [Newest commit wins](#newest-commit-wins) | Runs for commits that were already superseded | `concurrency` |
| [Build once, promote](#build-once-promote-on-merge) | The second build and test of a merge | `publish.promote_from` |
| [Caches](/pipelines/caching) | Re-downloading and recompiling what did not change | `cache` on a stage |

## How Ankra decides whether a stage runs

```mermaid theme={null}
flowchart TD
    Start[Stage in the plan] --> Full{Full run?<br/>label, flag, org policy}
    Full -->|yes| Run[Run]
    Full -->|no| List{Change list read<br/>in full, 300 paths or fewer?}
    List -->|no| Run
    List -->|yes| Pipe{.ankra/pipeline.yaml<br/>changed?}
    Pipe -->|yes| Run
    Pipe -->|no| Paths{paths: or when.paths<br/>match a changed file?}
    Paths -->|yes| Run
    Paths -->|no filter declared| Aff{affected: declared?}
    Paths -->|no match| Skip[Skip: path_filter]
    Aff -->|no| Run
    Aff -->|yes| Graph{Checkout reads the graph:<br/>does any change reach it?}
    Graph -->|yes, or no answer| Run
    Graph -->|no| NA[Skip: not_affected]
```

The rule at every branch is the same: a file Ankra could not see is not a file that did not change. An unreadable diff, a change of more than 300 files, a created branch or a force push all mean "run it", and the run's `paths_unverified` records why.

## Run only what a change touches

There are two kinds of stage path filter. The difference is what happens to the stages after a skipped one.

```mermaid theme={null}
flowchart LR
    subgraph A["paths: affected-only"]
        A1[test-api<br/>skipped] -.-> A2[build<br/>still runs]
    end
    subgraph B["when.paths: the whole chain"]
        B1[build-web<br/>skipped] -.-> B2[scan-web<br/>skipped] -.-> B3[publish-web<br/>skipped]
    end
```

* **`paths:` makes a stage affected-only.** When no changed file matches, the stage is skipped as `path_filter`, and the stages that need it run without it. Use it for a test stage whose absence should hold nothing back.
* **`when.paths` skips the chain.** The stages behind a skipped stage are skipped too, unless they list it in `skippable_needs`. Use it for a component's whole build, scan, gate and publish chain in a monorepo. It is what the generated monorepo pipeline uses.

```yaml theme={null}
path_sets:
  pipeline: [".ankra/**"]
  web: ["web/**", "packages/ui/**", { set: pipeline }]
  api: ["api/**", "go.work", { set: pipeline }]

stages:
  - name: checkout
    kind: checkout
  - name: test-web
    kind: run
    image: node:24
    needs: [checkout]
    paths: [{ set: web }]
    run: pnpm -C web test
  - name: test-api
    kind: run
    image: golang:1.26
    needs: [checkout]
    working_directory: api
    paths: [{ set: api }]
    run: go test ./...
```

`path_sets` names a list once, so every stage reuses it and the pipeline file is in every list. Sets can include other sets, and `!` excludes a pattern (the last matching pattern decides).

**Pull requests check what they touch, pushes check everything.** Use an event-scoped `when` block, so the pull request filters on paths and the push does not:

```yaml theme={null}
- name: test-api
  kind: run
  needs: [checkout]
  run: go test ./...
  when:
    pull_request:
      paths: [{ set: api }]
    push: {}
```

```bash theme={null}
ankra pipeline validate --changed-file web/app.ts
```

That prints every stage against a push and a pull request for that change, before you commit, so you can see the plan instead of guessing.

## Follow the imports: `affected:`

A path glob has one blind spot: a package your tests import from elsewhere in the repository. `test-api` lists `api/**`, a change to `libs/auth` matches nothing, and the tests that would have caught the break are skipped. `affected:` names packages instead of files, and Ankra follows their imports.

```mermaid theme={null}
flowchart LR
    Change([changed: libs/auth/token.go]) --> Auth[libs/auth]
    Auth --> API[api/internal/server]
    API --> T1[test-api runs]
    Web["@acme/web"] --> T2[test-web skipped: not_affected]
    style T2 stroke-dasharray: 5 5
```

```yaml theme={null}
- name: test-api
  kind: run
  image: golang:1.26
  needs: [checkout]
  working_directory: api
  affected:
    go: ["./..."]
  paths: ["migrations/**"]
  run: go test ./...

- name: test-web
  kind: run
  image: node:24
  needs: [checkout]
  affected:
    pnpm: ["@acme/web"]
  run: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @acme/web... test
```

* **`go`** names packages as `go test` does: `./...`, `./internal/api`, or an import path. Every `go.mod` in the repository is read, so a local `replace` counts. A change to `go.mod`, `go.sum` or `vendor/` reaches every package of that module.
* **`pnpm`** names workspace packages by name (`@acme/web`) or directory (`./apps/web`). Workspace dependencies are followed. A change to the root lock file, root `package.json`, `pnpm-workspace.yaml` or a patch reaches every pnpm stage.
* **`paths:` beside `affected:`** adds what no import graph sees, such as migrations or fixtures a test opens by path. Either one matching runs the stage.
* **The checkout reads the graph** of the exact commit it checked out, in seconds. No extra step, nothing cached. A stage is skipped only when the checkout positively answered that no change reaches it. A pattern that names nothing, a failed analysis, or one that took over two minutes runs the stage.
* **A skip never waits for capacity.** A not-affected stage is concluded as soon as the checkout answers, without taking a CI slot.

## Newest commit wins

Push three commits to a branch in a minute, and only the last one's result matters.

```mermaid theme={null}
sequenceDiagram
    participant Dev as Developer
    participant Ankra as Ankra
    Dev->>Ankra: push c1
    Note over Ankra: run 41 running
    Dev->>Ankra: push c2
    Ankra-->>Ankra: run 41 superseded (grey, neutral)
    Note over Ankra: run 42 running
    Dev->>Ankra: push c3
    Ankra-->>Ankra: run 42 superseded
    Note over Ankra: run 43 is the one that reports
```

```yaml theme={null}
concurrency:
  group: "${{ ankra.repository.provider }}:${{ ankra.repository.owner }}/${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
```

* **`cancel_in_progress: true`** cancels the in-flight run when a newer one arrives in the same group. Every pipeline Ankra generates sets it.
* **`cancel_queued: true`** is the gentler choice: it keeps one running and one waiting run per group, cancelling older runs that have not started, and never the running one.
* **A different policy per event.** Either flag can be one expression, settled per run, so a pull request supersedes its old run while a push to your default branch always finishes and keeps only its newest waiting commit: `cancel_in_progress: "${{ event.kind != 'push' }}"` with `cancel_queued: "${{ event.kind == 'push' }}"`. See [A concurrency policy per event](/guides/pipeline-reference#a-concurrency-policy-per-event).
* **Superseded is not failed.** The older run concludes cancelled, shows as **Superseded** in grey, leaves a neutral status on GitHub, GitLab or Bitbucket, and raises no failure notification.

A definition you wrote keeps what it says. Ankra never flips the flag for you, but `ankra pipeline validate` gives advice (`pipeline_concurrency_queues_behind:`) when a per-branch group would queue a branch behind itself.

## Skip a push with `[skip ci]`

A pushed commit whose message carries `[skip ci]`, `[ci skip]`, `[no ci]`, `[skip ankra]` or `[ankra skip]`, or ends with a `skip-checks: true` trailer, records a skipped run instead of queueing one. The check is still posted.

Markers are honoured where they are safe and nowhere else:

| Run | Marker honoured? |
| - | - |
| Push to a branch other than the default | Yes, by default |
| Push to the default branch | Only when the organisation sets `ci_skip_markers: everywhere` |
| Pull request | Never. Its check is what branch protection reads |
| Tag | Never. A tag releases |
| Merge train car | Never |

## Full runs: set the filters aside

Sometimes you want every stage, whatever the paths say: before a release, after a toolchain bump, or to prove a flaky skip.

| Who asks | How |
| - | - |
| You, for one run | `ankra pipeline run --full`, or `ankra pipeline rerun <run> --full` |
| A pull request | Add the `ankra:full-run` label. Every push runs in full while it stays on, and so does its merge train car |
| The pipeline | A top-level `full_run: { events: [push], branches: [main] }` block |
| Your organisation | `ci_full_run_on_default_branch`, or stages listed in `ci_always_run_stages` that no pull request can filter away |

```bash theme={null}
ankra pipeline run --full --wait
```

The run records why it was a full run and who asked.

## Build once, promote on merge

A merge to `main` normally builds and tests the merged commit again, even though the pull request run already did all of that for the same files. `promote_from` re-tags the tested image instead.

```mermaid theme={null}
flowchart LR
    subgraph Before["Without promotion"]
        direction LR
        P1[PR run:<br/>test, build, scan, gate] --> M1[merge] --> R1[push run:<br/>test, build, scan, gate, publish]
    end
    subgraph After["With promote_from"]
        direction LR
        P2[PR or train car run:<br/>test, build, scan, gate] --> M2[merge] --> R2[push run:<br/>publish only, re-tag]
    end
```

```yaml theme={null}
- name: publish
  kind: publish
  needs: [gate]
  when:
    events: [push]
  publish:
    promote_from: pull_request
```

A push is promoted only when a run tested **exactly the same git tree**, under the same approved authority, within 72 hours, with every needed stage green and the gate having judged the same digest. A squash merge of a pull request that was up to date has that tree. One that was behind does not, and builds in full, unless the [merge train](/pipelines/merge-train) merged it, because the train's car tested exactly the merged tree. Anything short of the rules builds in full and records why.

## See what you saved

Every run records the CI time it did not spend because of a path filter, the dependency graph or a promotion, estimated from the median of that stage's recent successful runs.

```bash theme={null}
ankra pipeline get <run-id>                         # a "Time saved" line under the steps
ankra pipeline time-saved                           # organisation total, last 30 days
ankra pipeline time-saved --window 7d --repository <repository-id>
```

| `reason` | Saved by |
| - | - |
| `path_filter` | A stage a path filter left out |
| `dependency_skipped` | A stage skipped because one it needs was left out |
| `not_affected` | A step the dependency graph skipped |
| `promoted` | A step a promoted publish did not run again |
| `run_paths_excluded` | A whole run that `on.<event>.paths` excluded |

The figure is runner time, the seconds the skipped steps would have run added up. A stage with no usable history counts as unknown, never as zero and never as a guess.


# Generated pipelines
Source: https://docs.ankra.ai/pipelines/generated-pipelines

How Ankra writes your pipeline for you - the repository analysis, the Dockerfile it adopts or generates, the stages it chooses and why, monorepo component chains, the setup pull request, which file governs a run, and converting an existing GitHub Actions, GitLab, Bitbucket or CircleCI definition.

You do not have to write a pipeline to get one. Point Ankra at a repository, and it reads the code, decides what the service is and how to test it, and commits a complete `.ankra/pipeline.yaml` in a pull request. That pipeline tests, builds, scans, gates and publishes from the first push.

```bash theme={null}
ankra application ship . --cluster my-dev-cluster
```

`ship` runs the whole road: register the application, open the setup pull request, build the first image, deploy it and verify it. Run it again and it carries on from wherever it stopped. To read the setup pull request before anything deploys, use `ankra application add . --name my-service --wait` instead.

## What happens when you register a repository

```mermaid theme={null}
flowchart TB
    Repo[(Your repository)] --> Detect[Detect the stack<br/>language, framework, test command]
    Detect --> Docker{Dockerfile in<br/>the repository?}
    Docker -->|yes| Adopt[Adopt it, never rewritten]
    Docker -->|no| Gen[Generate a hardened one<br/>non-root, patched base]
    Adopt --> Comp[Decide components]
    Gen --> Comp
    Comp --> Tailor[AI tailors the standard pipeline<br/>rule-based templates when no AI]
    Tailor --> Validate[Validate and plan]
    Validate --> Record[Stored as the definition of record]
    Record --> PR[Setup pull request<br/>.ankra/pipeline.yaml, ankra.yaml,<br/>Dockerfile, manifests]
    Record --> Push[The next push already builds]
```

1. **Detect.** Ankra reads the files that name a stack: `package.json` (Next.js, Vite, React, Express, NestJS), `requirements.txt` or `pyproject.toml` (FastAPI, Django, Flask), `go.mod`, `Cargo.toml`, `pom.xml` or `build.gradle`, `Gemfile` (Rails), `composer.json` (Laravel) and `mix.exs`. Failing those it counts file types, and a root `index.html` with nothing else is a static site.
2. **Dockerfile.** A Dockerfile you already have is adopted as it is. Otherwise Ankra generates one whose final stage applies OS package upgrades and runs as a non-root user, on a maintained toolchain release.
3. **Components.** A monorepo gets one component per service. Ankra decides them in a fixed order: what `.ankra/ankra.yaml` declares (always wins), then what the repository already carries, then what the AI proposed, then what the tree implies. Names stay stable across re-runs, so stage names never shift under you.
4. **Tailor.** An AI step adapts the standard pipeline to the repository, using the same render and validate tools you can call. With no AI available, rule-based templates produce the same shape.
5. **Record.** The pipeline is validated, planned, and stored as the **definition of record** before the pull request even opens.

## What the generated pipeline contains

```mermaid theme={null}
flowchart LR
    checkout --> test[test<br/>only if a test command was found<br/>package caches declared]
    test --> build[build<br/>provenance + SBOM<br/>native architecture]
    build --> scan[scan<br/>Semgrep, Checkov, Trivy]
    scan --> gate{gate}
    gate -->|push only| publish[[publish<br/>promote_from: pull_request]]
```

| Part | What Ankra sets, and why |
| - | - |
| Triggers | `push` and `pull_request` on your tracked branch, plus `manual`. Pull requests from forks run as `read_only`. |
| Concurrency | One group per ref with `cancel_in_progress: true`, so the newest commit on a branch wins. |
| Defaults | A 30-minute timeout, the `egress-https` network tier, `contents: read`. |
| `test` | Only when a test command was detected. There is never an empty test stage pretending to test. Package caches are declared for the toolchain, under `.ankra-*` directories the scan skips. See [Caching](/pipelines/caching#what-ankra-generates-for-you). |
| `build` | Provenance and SBOM attestations on. No platform pinned, so it builds natively for the node it runs on. |
| `scan` | Semgrep, Checkov and Trivy against the digest just built. Semgrep blocks on `error`, Checkov reports only, Trivy follows your organisation's image gate (by default, fixable critical and high findings in your own dependencies). Semgrep's rule packs are `p/default` and `p/docker` plus your language's packs, with `p/github-actions` only when the repository has workflows. |
| `gate` | Requires `scan`, so nothing unscanned can publish. |
| `publish` | Push events only, with `promote_from: pull_request`: a merge re-tags the image its pull request already tested, and builds in full when no run tested the same tree. |

**A monorepo gets one file.** Each component has its own chain (`build-web`, `scan-web`, `gate-web`, `publish-web`), path-filtered to its directory, all sharing one checkout and one run. A component at the repository root is not filtered.

## The setup pull request

The pull request carries `.ankra/pipeline.yaml`, `.ankra/ankra.yaml`, the Dockerfile when Ankra generated it, and `.ankra/manifests/`.

```mermaid theme={null}
sequenceDiagram
    participant Ankra
    participant PR as Setup pull request
    participant CI as Ankra Pipelines
    Ankra->>Ankra: Store the pipeline as definition of record
    Ankra->>PR: Open as draft
    PR->>CI: Pull request run
    alt run passes
        CI->>PR: Marked ready for review
    else build or gate fails
        CI->>Ankra: Fix mission
        Ankra->>PR: Commits the fix to the setup branch
    end
    Note over PR: You review and merge.<br/>Merging puts the file in Git.
```

* **The pull request is a proposal, not a gate.** Because the definition is already recorded, the next push to your branch builds whether or not you merge it. Merging is how the file reaches Git, where you own it from then on.
* **When the setup pull request's own build or gate fails,** Ankra's AI commits a fix to the setup branch, so the pull request you review is one that passes.
* **After a failed setup**, `ankra application retry <application-id>` runs it again.

## Which file governs a run

```mermaid theme={null}
flowchart LR
    Head{.ankra/pipeline.yaml<br/>at the run's commit} -->|parses, has stages| Committed[Your committed file<br/>wins whole, no merging]
    Head -->|absent, empty,<br/>unparseable, no stages| Generated[The generated definition<br/>plus the validation errors]
```

Once the file is committed, **it is yours**. Ankra never rewrites a pipeline you committed, never merges its own opinions into it, and never flips a setting for you. Improvements Ankra makes to generated pipelines (a new cache layout, say) reach new applications. For an existing one, copy the block from these docs.

The application records where its builds come from as `pipeline_source`:

| `pipeline_source` | Meaning |
| - | - |
| `ankra_pipeline` | A committed `.ankra/pipeline.yaml` or a stored definition of record governs builds |
| `own_ci` | Your repository's own workflow pushes the image |
| `generated_workflow` | The legacy GitHub Actions workflow Ankra used to generate. Convert it (below) |
| `none` | Nothing builds yet |

`ankra application get <application-id> -o json` shows it, with a reason. `pipeline_file_committed_no_ci_cluster` means the file is fine and your organisation has not chosen a CI cluster yet: an administrator sets one with `ankra org ci-settings set --cluster <cluster>`.

## Already have CI? Convert it

> [tab] An application on GitHub Actions
>
> ```bash theme={null}
> ankra application pipeline convert <application-id>
> ```
>
> One call converts the workflow, stores the result as the definition of record, switches the application to Ankra Pipelines at once, switches Ankra's generated workflow off, and opens a pull request that adds the pipeline and removes the generated workflow. A workflow your repository wrote itself is never touched. `--keep-workflows` keeps the generated workflow running beside the pipeline while you compare.

> [tab] GitLab CI, Bitbucket or CircleCI
>
> Ask Ankra AI, or your coding agent through the [MCP server](/pipelines/cli-and-mcp):
>
> > Convert .gitlab-ci.yml into an Ankra pipeline and validate it.
>
> `cicd_convert_workflow_to_pipeline` reads GitHub Actions, GitLab CI, Bitbucket Pipelines and CircleCI. It returns the pipeline and a note for everything it could not map. It writes nothing. You review and commit the file.

**What converts, and how.** Nothing is dropped silently. The result is always a starting point to review, never a black box.

| In your workflow | In the pipeline |
| - | - |
| `actions/checkout` | A `checkout` stage |
| `docker/build-push-action`, `depot/build-push-action` | A `build` stage: file, context, platforms, build args, provenance, SBOM, cache, tags |
| `aquasecurity/trivy-action` | A `scan` stage |
| `actions/setup-node`, `setup-go`, `setup-python`, `setup-java` | The stage image: `node:<v>`, `golang:<v>`, `python:<v>`, `eclipse-temurin:<v>` |
| `actions/cache` | A stage `cache` block |
| `services:`, `strategy.matrix`, `needs:`, `concurrency` | The same concepts, one to one |
| `docker/login-action`, `setup-buildx`, `setup-qemu`, cloud login actions | Dropped with a note: Ankra provides registry login, the builder, and credentials through the pipeline's `credentials` block |
| A GitLab job and its `stages:` order | One `run` stage per job, with `needs` edges in stage order; `rules: changes:` become path filters |
| Anything with no equivalent | A `run` stage that fails with an explanation, and a note naming it |

[Migrate from GitHub Actions](/guides/migrate-from-github-actions) covers the review checklist after conversion, and how to run both side by side before you switch.


# How Ankra Pipelines works
Source: https://docs.ankra.ai/pipelines/how-it-works

The moving parts of Ankra Pipelines in diagrams - what happens between a git push and a green check, where every step runs, how authority is decided, and how build, scan, gate and publish chain one digest from your commit to your registry.

Ankra Pipelines turns one committed file, `.ankra/pipeline.yaml`, into runs on a Kubernetes cluster you already operate through Ankra. This page explains the system as a whole. For every key in the file, see the [pipeline.yaml reference](/guides/pipeline-reference). For the full operating detail (settings, limits, diagnosis codes), see the [Ankra Pipelines guide](/guides/ankra-pipelines).

## The big picture

Three places take part in every run: your Git host, the Ankra platform, and your CI cluster. Your source and your build traffic never leave your cluster. The platform decides what runs, and the agent in your cluster runs it.

```mermaid theme={null}
flowchart TB
    Repo[(Your repository<br/>.ankra/pipeline.yaml)]
    Check[Ankra pipeline check<br/>and PR status comment]

    subgraph Platform["Ankra platform"]
        direction LR
        Authority{{Authority<br/>default branch, approved}} --> Planner[Planner<br/>stages, matrix, needs, skips]
        Trigger[Trigger decision] --> Planner
        Planner --> Queue[Org-fair queue]
        Settle[Settle and report]
    end

    subgraph CI["Your CI cluster"]
        direction LR
        Agent[Ankra agent<br/>CI workers] --> Steps[One hardened Job per step<br/>namespace ankra-ci]
        Agent --> Build[Rootless BuildKit<br/>namespace ankra-ci-build]
    end

    subgraph Storage["Your storage"]
        direction LR
        Vault[(Backup vault<br/>logs, artifacts, reports, caches)]
        Registry[(Your registry)]
    end

    Repo -- webhook --> Trigger
    Queue -- signed step payload --> Agent
    Steps --> Vault
    Build -- digest --> Registry
    Agent -- verdict --> Settle
    Settle --> Check
```

* **The agent connects out.** Your CI cluster needs no inbound access, so a cluster behind NAT or a firewall runs pipelines like any other.
* **The agent renders the Kubernetes objects itself.** The platform sends a signed description of the step, never a manifest to apply verbatim.
* **Everything archival goes to a vault.** Step logs, artifacts, scan reports and caches go to your organisation's own [backup vault](/concepts/backup-vaults), or to the Ankra-managed default vault when you have none. You do not need to provision anything before a first run.

## From push to green check

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Dev as Developer
    participant Git as Git host
    participant Ankra as Ankra platform
    participant Agent as Agent (CI cluster)
    participant Vault as Vault and registry

    Dev->>Git: git push / open pull request
    Git->>Ankra: Verified webhook
    Ankra->>Ankra: Decide: connected? trusted? cluster? definition? on: matches?
    Ankra->>Git: Read .ankra/pipeline.yaml at the run's own commit
    Ankra->>Ankra: Plan the step DAG and resolve authority
    Ankra->>Git: Check run "Ankra pipeline" (queued)
    loop For every ready step
        Ankra->>Agent: Dispatch step with one-time secret grants
        Agent->>Agent: Run a hardened Job, stream live logs
        Agent->>Vault: Upload log, artifacts, caches, digest
        Agent->>Ankra: Step verdict
        Ankra->>Git: Update check and status comment
    end
    Ankra->>Git: Conclude the check (success, failure, cancelled)
    Ankra-->>Dev: Notification to Slack, Teams, PagerDuty or webhook
```

Each numbered step has one job:

1. **Trigger.** A push, pull request, tag, schedule or manual dispatch becomes one normalised event. Ankra answers five questions in a fixed order: is the repository connected, is the head trusted, is there a cluster to run on, is there a definition, and does the `on:` block accept the event. Every answer is recorded, so a push that started nothing still says why.
2. **Plan.** The planner reads the pipeline file at the run's own commit (on GitHub), so a pull request that edits the pipeline tests its own edit. It expands matrices (at most 64 legs per stage) and applies path filters and the dependency graph. Every stage it leaves out is recorded with a reason, never dropped silently.
3. **Dispatch.** Steps are handed out org-fairly. Organisations are served in order of how much they already have running, so one busy team cannot starve another. Secrets become one-time, per-step reveal grants at this point, never written into a payload or a log.
4. **Run.** Each step is a Kubernetes Job with a read-only root filesystem, no privilege escalation, and the network tier the stage asked for. All steps of one run share a workspace volume.
5. **Settle and report.** Ankra records the verdict, unblocks the steps that waited for it, and updates the `Ankra pipeline` check run (or commit status on GitLab and Bitbucket Cloud) and the pull request's one status comment.

## A run is a graph, not a list

Stages declare what they need. Everything whose needs are met runs in parallel, up to your concurrency limits.

```mermaid theme={null}
flowchart LR
    checkout([checkout]) --> lint[lint]
    checkout --> unit[unit tests<br/>matrix: 3 legs]
    checkout --> build[build image]
    unit --> e2e[e2e<br/>with postgres sidecar]
    build --> e2e
    build --> scan[scan<br/>Trivy, Semgrep, Checkov]
    scan --> gate{gate}
    e2e --> gate
    lint --> gate
    gate -->|push only| publish[[publish sha-abc1234]]
    gate -.->|any failure| notify[on_failure: notify]
```

* `needs` draws the edges. A stage with no `needs` starts as soon as the run does.
* `matrix` fans one stage out into legs, with the same include and exclude rules as GitHub Actions.
* `on_failure` stages run only when something failed. `finally` stages run whatever the outcome, including after a cancel.
* A stage a path filter or the dependency graph left out is **satisfied** for what needs it, so the graph keeps moving.

## One digest from commit to registry

Most CI systems build, push and then scan, so a vulnerable image is already in the registry by the time the scan fails. Ankra Pipelines splits the work into four stage kinds, and the image only moves forward when the stage before it passed.

```mermaid theme={null}
flowchart LR
    B[build<br/>rootless BuildKit] -->|digest sha256:9f2c| S[scan<br/>reads the digest]
    S -->|findings persisted| G{gate<br/>your org policy}
    G -->|approved: same digest| P[publish<br/>re-tag as sha-abc1234]
    G -.->|blocked| X[Nothing is published]
    P --> D[Push-to-deploy<br/>rolls out the digest]

    style X stroke-dasharray: 5 5
```

* `build` pushes by digest to a **staging** repository, never to the repository your application deploys from.
* `scan` runs Trivy (filesystem, SBOM and the image itself), Semgrep and Checkov from pinned images that a pipeline cannot swap out.
* `gate` judges the run's own persisted findings against the organisation's image gate. A pipeline may make the gate stricter for itself, never looser. A scanner that recorded nothing fails the gate, because an unread scan is not a clean scan.
* `publish` re-tags the exact digest the gate judged. It refuses if the gate is missing, failed, or recorded a different digest. No rebuild, no mutable tag until this point.

## Logic is open, authority is closed

Anyone who can push may change what a pipeline **does**: stages, scripts, images, conditions, matrices. What a run may **touch** is fixed by the default branch's definition, once an organisation administrator has approved it.

```mermaid theme={null}
flowchart TB
    PR[Pull request edits<br/>.ankra/pipeline.yaml] --> Logic[Logic from the head<br/>stages, scripts, images, needs]
    Default[Default branch definition] --> Approved{Approved by an<br/>administrator?}
    Approved -->|yes| Auth[Authority from that definition]
    Approved -->|no| Last[Last approved authority, or none]
    Logic --> Run((Run))
    Auth --> Run
    Last --> Run
```

The protected sections include:

* `secrets` and `credentials`
* `permissions`
* the fork policy
* network tiers above `egress-https`
* placement and `resources`
* `timeout`
* `cache`
* `services`
* a stage's `with:` block
* `promote_from`

A pull request that adds a credential or widens its network still runs its scripts, but under the trusted authority. The check run says, in a sentence, what was ignored and why. So nobody can sneak a production credential into a pull request, and you never have to choose between letting contributors edit CI and keeping it safe.

Fork pull requests run too, with no secrets, no credentials, no shared caches, no network outside `checkout`, `build` and `scan`, and a fixed budget of compute and artifact space. Their plan applies those clamps up front, so what a reviewer sees is what runs.

## Where a step runs

```mermaid theme={null}
flowchart TB
    subgraph Pool["Organisation CI pool"]
        A[CI cluster A]
        B[CI cluster B]
    end
    Run[New run] -->|least-loaded member| Pool
    A --> NodeA[Nodes with free room]
    B --> NodeB[Dedicated node group<br/>tainted for CI]
```

* The organisation names a CI cluster, or a **pool** of several. A new run goes to the least-loaded member and never moves once started.
* Each cluster's agent runs at most `ci_worker_count` steps at once. These CI slots are separate from the agent's deploy work, so CI never delays a rollout.
* A **step placement** can pin every pipeline pod to a dedicated node group. Ankra node groups scale up when steps ask for more room than the nodes have.
* All steps of one run share one node, because they share one workspace volume. A run that fans out picks the emptiest node first.

## What the run leaves behind

| Where | What you get |
| - | - |
| Your Git host | One `Ankra pipeline` check run per run (GitHub), with a step table and a Cancel button. A commit status on GitLab and Bitbucket Cloud. On a pull request, a single status comment with pipeline, preview and review sections. |
| The portal | The run timeline, an in-app log viewer, test results with flaky detection, cache hit chips, and the time the run saved. |
| The CLI and MCP | `ankra pipeline get`, live `logs --follow`, artifacts and findings, the same data for scripts and AI agents. See [CLI and MCP](/pipelines/cli-and-mcp). |
| Your vault | The complete step log, declared artifacts, scan reports and test reports, kept by your retention settings. |
| Your channels | `pipeline_run_failed`, `pipeline_run_succeeded`, `image_gate_blocked`, `preview_ready` and `preview_failed`, routed by your [notification rules](/guides/notification-routing). |

## Next

> [card] [Generated pipelines](/pipelines/generated-pipelines)
>
> How Ankra writes the pipeline for you from your repository.

> [card] [Fast CI](/pipelines/fast-ci)
>
> Run only what a change touches, and never build the same commit twice.

> [card] [Caching](/pipelines/caching)
>
> Warm package and build caches that respect trust boundaries.

> [card] [Merge train](/pipelines/merge-train)
>
> Test every pull request as it will merge, then merge it.


# The merge train
Source: https://docs.ankra.ai/pipelines/merge-train

Keep the default branch green by testing every pull request as the exact commit its merge will produce, several at once, then merging it through GitHub - how cars are built, what evicts one, how a tested image is published without a rebuild, and every command and setting.

A pull request's own run tests its head. It does not test that head on top of everything that merged since the branch was cut. Two pull requests can both be green and still break `main` when they land together. That is how a default branch goes red with nobody to blame.

The merge train closes that gap. Ankra tests each pull request **as the commit its merge will produce**, on top of the base branch and every pull request ahead of it. It merges only after that exact commit passes. It does what GitLab's merge trains and GitHub's merge queue do, on any GitHub plan, inside your own CI cluster.

> [!NOTE]
>
> The merge train works with **GitHub** repositories today, and merges with **squash**. It is off until you turn it on for a repository.

## Why it is worth turning on

* **`main` stays green.** Nothing merges onto a base its car did not test, so a semantic conflict between two pull requests is caught before it lands, not after.
* **No bisection.** Each car tests everything ahead of it. When a car fails, the pull request in that car is the one that broke it.
* **Parallel, not serial.** With several cars, the train tests up to eight pull requests at once, each stacked on the ones ahead.
* **Merge to published is a re-tag.** The merge commit's tree is exactly what the car tested, so a pipeline with [`promote_from`](#build-once-publish-the-tested-image) publishes the car's image instead of building and testing the same tree again.
* **Your rules still apply.** The train merges through GitHub's own merge API. Branch protection, required reviews and required checks hold exactly as for a person's merge. Ankra never pushes to or force-pushes the base branch.

## How a car is built

For each pull request in the train, Ankra writes a **car**: the pull request squashed onto the base branch, or onto the car ahead of it.

```mermaid theme={null}
gitGraph
    commit id: "main A"
    commit id: "main B"
    branch car-412
    commit id: "B plus 412"
    branch car-415
    commit id: "B plus 412, 415"
    branch car-418
    commit id: "B plus 412, 415, 418"
    checkout main
    merge car-412 id: "squash 412"
```

1. The car's branch, `ankra-merge-train/<entry id>`, starts at its base: the base branch head for the first car, or the car ahead for every other car.
2. The pull request's pinned head is merged in, using the same merge GitHub's squash merge computes.
3. A single-parent commit with that tree is written. It is exactly the squash commit the merge will create, titled `<title> (#<number>)`.
4. A pipeline run tests that commit. The run records the car's tree, which is what lets the merge publish without a rebuild.

**How the car's run is planned.** A car run is planned as a pull request into the base branch, under the base branch's approved [authority](/pipelines/how-it-works#logic-is-open-authority-is-closed):

* It runs only when the pipeline declares `on.pull_request` with `branches` that match the base branch.
* `when.events: [pull_request]` stages run. Push-only `publish` and deploy stages do not.
* It never joins the pull request's own concurrency group, and a push to an `ankra-merge-train/*` branch never starts a run of its own.
* A `[skip ci]` marker never skips a car.

## The life of a pull request in the train

```mermaid theme={null}
stateDiagram-v2
    direction LR
    [*] --> queued: added (CLI, label, merge when green)
    queued --> building: a car slot is free
    building --> testing: car commit written
    testing --> passed: car run succeeded
    passed --> merging: first car, base unchanged
    merging --> merged: squash-merged through GitHub
    testing --> evicted: run failed or cancelled
    building --> evicted: merge conflict
    passed --> evicted: GitHub kept declining the merge
    queued --> cancelled: removed, closed, train off
    testing --> queued: base moved or car ahead changed
    passed --> queued: base moved or car ahead changed
    merged --> [*]
    evicted --> [*]
    cancelled --> [*]
```

| Status | What it means |
| - | - |
| `queued` | Waiting for a car. Just added, or sent back to be rebuilt |
| `building` | The car branch is being written |
| `testing` | The car commit exists and its pipeline run is testing it |
| `passed` | The run passed. It waits to be the first car with an unchanged base |
| `merging` | The merge is in progress |
| `merged` | The train merged the pull request |
| `evicted` | The train removed it: its car failed, it could not merge, or it changed under the train |
| `cancelled` | A person removed it, the train was switched off, or the pull request was closed or merged elsewhere |

A car whose run concludes **skipped** counts as passing. For example, every changed file is outside `on.pull_request.paths`. A skipped car is never a promotion source, though.

## Several cars at once

With `--max-cars 3`, the train tests three pull requests side by side, each on top of the ones ahead.

```mermaid theme={null}
flowchart LR
    Main[(main)] --> C1[Car 1<br/>main + 412]
    C1 --> C2[Car 2<br/>main + 412 + 415]
    C2 --> C3[Car 3<br/>main + 412 + 415 + 418]
    C3 -.-> Q[PR 421 queued]

    C2 -. fails .-> E[PR 415 evicted]
    E -.-> R[Car 3 rebuilt on Car 1<br/>main + 412 + 418]
```

* Only the **first** car merges. It merges once its run passed and the base branch head, re-read just before the merge, is still the head it was built on.
* **When a car fails**, its pull request leaves the train with the failing run linked. Every car behind it included the failed change, so they are rebuilt without it (`predecessor_changed`). Nothing has to be bisected.
* **When someone merges around the train**, every built car goes back to `queued` with `base_moved` and is rebuilt on the new head.
* **When you lower `max_cars`**, cars beyond the new limit are requeued with `train_shortened`.

Ankra builds one car per pass, because the next car needs the commit this one writes. Cars are not batched: each car is one pull request, and each merge is one squash commit.

> [!TIP]
>
> **Picking `max_cars`.** Start with `1` (one pull request at a time on the latest base) and raise it when pull requests wait in the queue. More cars means more throughput, and more rebuilds when an early car fails. A high merge rate with a reliable test suite is the case for 3 to 8.

## Turn it on

**1. Make sure the pipeline tests pull requests into the base branch**

The car run is a pull request run, so the pipeline needs:

```yaml theme={null}
on:
  pull_request:
    branches: ["main"]
```

Without it, a car is evicted with `pipeline_not_triggered`.

**2. Enable the train**

```bash theme={null}
ankra pipeline train enable --max-cars 2
```

Run it from inside the repository's checkout, or name it with `--application <name>` or `--repository <id>`. This needs `pipelines.manage`. `--max-cars` takes 1 to 8 and defaults to 1.

**3. Require the train's check on the base branch**

Ankra posts an **Ankra merge train** check on every pull request it holds, and concludes it `success` only immediately before it merges. In GitHub's branch protection, require that check, pinned to the Ankra GitHub App rather than any source. Every merge then goes through the train. A pull request outside the train shows the check as expected and waiting, and cannot merge.

**4. Optionally, publish the tested image on merge**

Add `promote_from: pull_request` to your `publish` stage, so a train merge publishes the car's image instead of rebuilding it. See [Build once, publish the tested image](#build-once-publish-the-tested-image).

## Put a pull request on the train

There are three ways in, and they all lead to the same queue.

> [tab] CLI
>
> ```bash theme={null}
> ankra pipeline train add 412                     # put #412 at the end of the train
> ankra pipeline train add 412 --head-sha 9f2c1e7  # pin the exact commit you reviewed
> ankra pipeline train list                        # the train in order, and what recently left it
> ```

> [tab] Label
>
> Add the `ankra:merge-train` label to the pull request, in any letter case. Removing the label only removes an entry the label put there.

> [tab] Merge when green
>
> Comment **`@ankraai merge when green`**, press the button in the portal, or ask Ankra AI. On a repository with the train on, the request enters the train instead of merging directly. See [AI in pull requests](/pipelines/ai-in-pull-requests#merge-when-green).

**Who may add a pull request.** You need `pipelines.operate` and must be a person, not a service token. You also need one of these: organisation administrator, the pull request's author, or write access to the repository on GitHub through your verified GitHub identity. You can always remove an entry you added yourself. When GitHub cannot be asked, nothing changes and the command says so.

**Pushing to a pull request in the train takes it out** (`head_changed`). The train merges the head a person put in it, never one that arrived later. Push your fix, then add it again.

## Merges GitHub declines

The train merges through GitHub's merge API, so GitHub can say no, usually because one of the pull request's own required reviews or checks has not arrived.

```mermaid theme={null}
flowchart LR
    P[Car passed] --> M{GitHub merge}
    M -->|merged| OK[merged]
    M -->|declined| W[Stays passed,<br/>retried every pass]
    W --> M
    W -->|failing required check<br/>for 15 minutes| E1[evicted: merge_declined]
    W -->|any other reason<br/>for 3 hours| E2[evicted: merge_declined]
    W -.-> Behind[Cars behind keep<br/>building and testing]
```

* The car stays `passed` and the merge is retried on every pass, with GitHub's message shown as the reason.
* **Cars behind it keep building and testing meanwhile.** The train does not freeze behind one stuck merge.
* When GitHub says a required status check **is failing**, the car is evicted after **15 minutes**. A failed check does not turn green by waiting, so re-run it and add the pull request again.
* For any other reason, such as a review that has not arrived yet, the car waits up to **3 hours** before it is evicted.

## Why a pull request left the train

`ankra pipeline train list` shows what recently left the train and why. The same sentence is on the pull request's check run.

| Reason | Status | What it means and what to do |
| - | - | - |
| `run_failed` | evicted | The car's run did not pass. Open the linked run, fix, and add it again |
| `run_cancelled` | evicted | The car's run was cancelled |
| `merge_conflict` | evicted | It does not merge cleanly onto the base and the pull requests ahead. Rebase or merge `main` in, then add it again |
| `head_changed` | evicted | Pushed to after it entered the train. Add it again to test the new head |
| `base_branch_changed` | evicted | The pull request now targets a different base branch |
| `merge_declined` | evicted | GitHub kept declining the merge (above) |
| `pipeline_not_triggered` | evicted | The pipeline has no `on.pull_request` trigger matching the base branch |
| `fork` | evicted | Pull requests from forks are never merged automatically |
| `host_unavailable` | evicted | GitHub could not be reached for this pull request for over three hours |
| `nothing_to_merge` | evicted | The base branch already contains the change |
| `pull_request_closed` | cancelled | The pull request was closed |
| `merged_outside_train` | cancelled | Someone merged it outside the train |
| `dequeued` | cancelled | Someone removed it |
| `train_disabled` | cancelled | The train was switched off |

A car sent back to be rebuilt shows `queued (<reason>)`: `base_moved`, `predecessor_changed`, `train_shortened`, `run_missing` or `run_replaced`. That is normal train motion, not a failure.

After every merge, the train compares the merge commit's tree with the car's tree. The **TESTED AS MERGED** column of `train list` is that comparison: it is the proof that what merged is what was tested.

## Build once, publish the tested image

Without the train, a merge to `main` builds, scans, tests and gates the merged commit again, even when the pull request run already did the same work. With the train, the merge commit's tree is exactly the tree the car tested, so that second build is pure waste.

```mermaid theme={null}
sequenceDiagram
    participant Car as Car run (merge_train)
    participant GH as GitHub
    participant Push as Push run on main
    participant Reg as Registry

    Car->>Car: checkout, test, build, scan, gate
    Note over Car: records tree T and<br/>gate-approved digest D
    Car->>GH: squash-merge (tree T)
    GH->>Push: push webhook for the merge commit
    Push->>Push: tree T was tested by car run, same authority, under 72h
    Push->>Reg: publish: re-tag digest D as sha-<merge commit>
    Note over Push: every other stage shows<br/>"already passed for exactly this tree"
```

Declare it on the `publish` stage:

```yaml theme={null}
- name: publish
  kind: publish
  needs: [gate]
  when:
    events: [push]
  publish:
    promote_from: pull_request
```

The push is promoted only when all of these hold. Otherwise it builds in full, and the run records why:

* Every `publish` stage declares `promote_from`, under approved authority. It is a protected section, so a pull request cannot turn it on for itself.
* The push's plan is only `publish` and the stages it needs.
* A pull request or car run tested the same git tree, under the same approved authority, within the last 72 hours.
* Every stage `publish` needs passed in that run on its newest attempt. A stage that run skipped as [not affected](/pipelines/fast-ci#run-only-what-a-change-touches) counts too.
* That run's `gate` judged exactly the digest its `build` reported.
* The run was not from a fork, and was not a skipped car.

The run's detail says `Promotion: promoted (from run #N)`, or names the reason it fell back, such as `no_tested_run`, `source_inputs_differ` or `source_too_old`.

## Commands

| Command | What it does | Needs |
| - | - | - |
| `ankra pipeline train enable [--max-cars 1-8]` | Turn the train on, or change how many cars test at once | `pipelines.manage` |
| `ankra pipeline train disable` | Turn it off. The train empties on the next pass | `pipelines.manage` |
| `ankra pipeline train add <pr> [--head-sha <sha>]` | Put a pull request at the end of the train | `pipelines.operate`, and author, writer or admin |
| `ankra pipeline train list` | The train in order: pull request, status, attempt, car, run, entry id. Then what recently left, with why | Membership |
| `ankra pipeline train remove <entry-id>` | Take one entry out | `pipelines.operate` |
| `ankra pipeline train front <pr or entry-id>` (CLI 0.47.0+) | Move a pull request ahead of every car still queued, building or testing. Cars it passes are rebuilt | Organisation administrator with `pipelines.operate` |

Every command takes `--application <name>` or `--repository <id>`, or infers the repository from your checkout's `origin`. Add `-o json` for scripts. `merge-train` is an alias for `train`. Over the [MCP server](/pipelines/cli-and-mcp), a coding agent enters a pull request through merge when green (`scm_merge_pull_request`), which joins the train on a repository that has one, and follows the car's run with `watch_pipeline_run`.


# Ankra Pipelines
Source: https://docs.ankra.ai/pipelines/overview

CI/CD that runs in your own cluster from one committed file - tests on every pull request, images built once, scanned and gated before they publish, a merge train that keeps main green, and AI that reads every run. Start here for the whole section.

Ankra Pipelines runs your repository's CI/CD as Kubernetes Jobs on a cluster you already operate through Ankra. One file, `.ankra/pipeline.yaml`, says what to run. Ankra writes it for you, runs it on every push and pull request, reports back to GitHub, GitLab or Bitbucket, and publishes only images it has scanned and gated.

```mermaid theme={null}
flowchart LR
    Code[Your repository] -->|push, PR, tag,<br/>schedule| AP[Ankra Pipelines]
    AP --> Test[Test only<br/>what changed]
    Test --> Build[Build once]
    Build --> Scan[Scan and gate]
    Scan --> Ship[Publish the<br/>tested digest]
    Ship --> Deploy[Push-to-deploy]
    AP <-.-> AI[Ankra AI<br/>review, diagnose, fix]
    AP <-.-> You[CLI, MCP,<br/>Slack, your agent]
```

## Get a pipeline in three commands

**1. Point a CI cluster at pipelines**

An organisation administrator chooses the cluster and turns on its pipeline workers, once:

```bash theme={null}
ankra org ci-settings set --cluster my-ci-cluster
ankra cluster agent ci set --workers 4 --cluster my-ci-cluster
```

**2. Ship a repository**

From the repository's checkout:

```bash theme={null}
ankra application ship . --cluster my-dev-cluster
```

Ankra analyses the code and opens a setup pull request with a generated `.ankra/pipeline.yaml`. The next push already builds. For a repository with nothing to deploy, connect it instead with `ankra pipeline repositories connect` and commit your own file. See [Examples](/pipelines/examples#a-repository-with-no-application).

**3. Watch it**

```bash theme={null}
ankra pipeline get --head-sha "$(git rev-parse HEAD)" --latest --wait
```

The same run is an **Ankra pipeline** check on your commit, a section in the pull request's status comment, and a timeline in the portal.

New to Ankra CI? [Get started with Ankra CI](/get-started/ankra-ci) walks the same path with every expected outcome.

## The section

> [card] [Why Ankra Pipelines](/pipelines/why-ankra-pipelines)
>
> What you care about in CI, and how each piece is delivered.

> [card] [How it works](/pipelines/how-it-works)
>
> From push to green check, in diagrams: planning, dispatch, authority, the digest chain.

> [card] [Generated pipelines](/pipelines/generated-pipelines)
>
> How Ankra writes your pipeline, and how to convert an existing one.

> [card] [Fast CI](/pipelines/fast-ci)
>
> Affected-only stages, the dependency graph, newest commit wins, build once.

> [card] [Caching](/pipelines/caching)
>
> Keys, restore, trust scopes, what Ankra generates, and reading a hit or a miss.

> [card] [Merge train](/pipelines/merge-train)
>
> Test every pull request as it will merge, several at once, then merge it.

> [card] [Examples](/pipelines/examples)
>
> Complete pipelines for services, monorepos, databases, libraries, nightlies and releases.

> [card] [AI in pull requests](/pipelines/ai-in-pull-requests)
>
> The review that reads your pipeline, merge when green, fixes for failed builds, previews.

> [card] [AI Gateway](/pipelines/ai-gateway)
>
> Slack, Teams, GitHub, GitLab and Bitbucket, with Ask and Agent modes.

> [card] [CLI and MCP](/pipelines/cli-and-mcp)
>
> The everyday commands, scripting with exit codes, and the MCP tools.

> [card] [With coding agents](/pipelines/coding-agents)
>
> Claude Code, Codex and the Claude app: connect, install skills, close the loop.

> [card] [Full guide and reference](/guides/ankra-pipelines)
>
> Every setting, limit, diagnosis code and key, for when you need the detail.


# Why Ankra Pipelines
Source: https://docs.ankra.ai/pipelines/why-ankra-pipelines

What developers and platform owners actually care about in CI - fast feedback, a green main branch, never paying for the same build twice, images that cannot ship unscanned, secrets a pull request cannot reach, and CI your AI agent can read - and how Ankra Pipelines delivers each one.

Every CI system runs scripts in containers. That part is a commodity. What separates a CI you stop thinking about from one you fight every week is everything around the scripts: how fast you hear back, whether `main` stays green, whether the same commit gets built three times, whether a pull request can reach a production secret, and whether you can find out why a run failed without opening five tabs.

This page is about those things, in the order people tend to care about them.

## 1. "Tell me fast whether my change works"

The feedback loop is the whole product. Ankra Pipelines shortens it by doing less, not by running the same work on bigger machines.

```mermaid theme={null}
flowchart LR
    Push[Your push] --> Plan{Planner}
    Plan -->|your files changed| Run1[Tests that can see the change]
    Plan -->|dependency graph<br/>cannot reach it| Skip1[Skipped: not_affected]
    Plan -->|older commit<br/>on the same branch| Cancel[Superseded]
    Run1 --> Warm[Warm caches<br/>packages and layers]
    Warm --> Result[Result on the pull request]
```

* **Only what your change can affect runs.** `affected:` follows your real Go and pnpm import graph, not just file globs, so a change to `libs/auth` runs the services that import it and skips everything else. When Ankra cannot prove a skip is safe, the stage runs. [Fast CI](/pipelines/fast-ci)
* **The newest commit wins.** Push three times in a minute and only the last run reports. The others are superseded, shown in grey, never as failures.
* **Caches are warm from the first pull request.** A new branch restores from `main`'s caches, and image builds reuse their layers automatically. [Caching](/pipelines/caching)
* **The time saved is measured, not claimed.** Every run records what it skipped and how long that would have taken, from your own history. `ankra pipeline time-saved` totals it.

## 2. "Keep `main` green"

A red `main` blocks everyone. Most of the time it is not one bad pull request. It is two good ones that conflict.

```mermaid theme={null}
flowchart LR
    A[PR 412 green alone] --> M{Merged together}
    B[PR 415 green alone] --> M
    M --> Red[main red]
    T[Merge train:<br/>PR 415 tested on top of PR 412] --> Green[main green]
    style Red stroke-dasharray: 5 5
```

* **The merge train tests every pull request as the exact commit its merge will produce,** on top of everything ahead of it, then merges it through GitHub with your branch protection intact. Several cars test in parallel. A failing car tells you exactly which pull request broke, with no bisection. It works on every GitHub plan. [Merge train](/pipelines/merge-train)
* **The default branch never skips.** `[skip ci]` is honoured on feature branches and refused on the default branch, on pull requests, on tags and on train cars, because those runs are what protect and release your code.
* **Path filters cannot quietly drop a safety check.** An organisation administrator can name stages that always run, and no pull request can filter them away.

## 3. "Don't make me pay for the same build twice"

The usual flow builds and tests a commit on the pull request, then builds and tests the identical tree again on merge, then sometimes again on deploy.

```mermaid theme={null}
flowchart LR
    subgraph Usual["Typical CI"]
        direction LR
        u1[PR: build + test] --> u2[merge: build + test again] --> u3[deploy]
    end
    subgraph Ankra["Ankra Pipelines"]
        direction LR
        a1[PR or train car:<br/>build + test once] --> a2[merge: re-tag the<br/>tested digest] --> a3[deploy that digest]
    end
```

* **Build once, promote on merge.** With `promote_from`, a merge whose tree a pull request or train car already tested publishes that exact image as a re-tag. What you tested is byte for byte what you ship.
* **No runner fleet to pay for.** Steps run as Kubernetes Jobs on a cluster you already operate through Ankra, in their own worker slots, never at the expense of a deploy. There is no per-minute bill from a CI vendor and no self-hosted runner pool to patch.
* **No second CI system.** Converting an existing workflow is one command, and Ankra warns you against running two CI systems on the same commit.

## 4. "Never ship an image nobody scanned"

```mermaid theme={null}
flowchart LR
    build --> scan --> gate{gate}
    gate -->|same digest| publish
    gate -.->|blocked| none[nothing published]
    style none stroke-dasharray: 5 5
```

* **Scan before publish, by design.** `build` pushes to a staging repository only. `publish` refuses unless a `gate` passed **and** that gate judged the same digest the build produced. A missing record is treated as unknown, not as agreement.
* **Three scanners, pinned.** Trivy (dependencies, SBOM and the image), Semgrep and Checkov run from pinned images no pipeline can swap out.
* **Pipelines can tighten the gate, never loosen it.** Your organisation sets the floor. A pull request may add scrutiny to its own pipeline, and nothing it writes can remove the organisation's.
* **An unread scan is not a clean scan.** A report that never uploaded, or did not parse, fails the step instead of passing as empty.

## 5. "A pull request must not be able to reach production"

The most common CI breach is a pull request that edits the workflow to print a secret. Ankra Pipelines makes that structurally impossible.

* **Logic is open, authority is closed.** Anyone can change what a pipeline does. What it may touch (secrets, credentials, network, placement, caches, compute, timeouts) comes only from the default branch's definition, after an administrator approves it. A pull request that adds a credential still runs, without it, and the check says why. [How it works](/pipelines/how-it-works#logic-is-open-authority-is-closed)
* **Secrets are references, not copies.** They are delivered to one step as one-time reveals, never written into a job spec or a log, and never copied into per-repository CI settings.
* **Approval is human.** No service token and no AI agent can approve authority.
* **Forks run safely.** No secrets, no credentials, no shared caches, no network outside checkout, build and scan, and a fixed compute budget, all applied to the plan a reviewer sees.
* **Caches cannot be poisoned.** Nothing a branch saves is ever restored into a default-branch run.

## 6. "Show me why it failed, where I already am"

* **One comment per pull request.** The run, the preview and the AI review share one status comment that updates in place.
* **The AI review reads your pipeline.** It sees the failing step, the scan findings and the gate verdict, not just the diff, and a failed build gets a diagnosis in plain words. [AI in pull requests](/pipelines/ai-in-pull-requests)
* **Ask from Slack or Teams.** "Why is main red?" gets an answer from the same AI, with your own permissions. [AI Gateway](/pipelines/ai-gateway)
* **Flaky tests are named, not hidden.** A test that passed on retry is recorded as flaky with its attempt count, and a repository can quarantine a proven-flaky test while someone fixes it.

## 7. "Let my AI agent work with CI, not around it"

Your coding agent already writes the code. Ankra lets it close the loop:

* **Validate before pushing**, with every violation by key, through the [MCP server](/pipelines/cli-and-mcp).
* **Watch the run and read the failing step's log**, then fix and push again, without you pasting logs into a chat.
* **Convert a GitHub Actions, GitLab, Bitbucket or CircleCI file** into a pipeline that validates.
* **Install the Ankra skills** so Claude Code, Codex, Cursor or the Claude app write Ankra pipelines correctly the first time. [With coding agents](/pipelines/coding-agents)

The agent can explain, validate, convert and watch. Granting power stays with you.

## 8. "Don't make me write it"

Point Ankra at a repository and it writes the pipeline: it detects the stack, adopts or generates a hardened Dockerfile, and picks the test command and the caches. It wires build, scan, gate and publish with promotion, and splits a monorepo into one chain per component. The setup pull request's own failures are fixed by the AI before you review it. Once you commit the file, it is yours, and Ankra never rewrites it. [Generated pipelines](/pipelines/generated-pipelines)

## At a glance

| What you care about | What you would otherwise build or buy | With Ankra Pipelines |
| - | - | - |
| Skip unaffected work | Path globs, or a monorepo build tool with remote caching | `affected:` from the real import graph, fail-safe |
| Green main | A merge queue, often a paid plan | A merge train in your cluster, up to 8 cars |
| Build once | Custom tagging scripts between workflows | `promote_from`, proven by git tree |
| Scan before ship | Ordering discipline across separate jobs | `build` → `scan` → `gate` → `publish`, enforced by digest |
| Secrets a PR cannot reach | Environment protection rules per repository | Protected sections, human approval, one-time reveals |
| Runners | A hosted per-minute bill or a self-hosted fleet | Jobs on a cluster you already run |
| Failure triage | Logs in the CI vendor's UI | AI review and diagnosis in the PR, Slack and Teams, your agent |
| Pipeline authoring | Hand-written YAML per repository | Generated, tailored and validated for you |

## Start

> [card] [Get started with Ankra CI](/get-started/ankra-ci)
>
> The short tutorial: from a repository to a green check.

> [card] [Examples](/pipelines/examples)
>
> Complete pipelines for services, monorepos, libraries and releases.


# Account Security & 2FA
Source: https://docs.ankra.ai/platform/account-security

Protect your Ankra account with TOTP authenticator apps, passkeys and security keys, and one-time recovery codes.

Ankra supports three second factors, managed from **Profile** → **Authentication**:

| Factor | What it is |
| - | - |
| **Authenticator app (TOTP)** | Six-digit codes from any authenticator app |
| **Passkeys / security keys** | WebAuthn - platform passkeys (Touch ID, Windows Hello) and roaming security keys |
| **Recovery codes** | One-time codes (`XXXXX-XXXXX`) for when you lose access to other factors |

## Enrolling

**1. Open Authentication settings**

Click your profile avatar → **Profile** → **Authentication**. The two-factor card shows your current status.

**2. Add an authenticator app**

Click **Set up authenticator app**, scan the QR code (or enter the secret manually), and confirm with a code. On confirmation you receive your recovery codes - store them somewhere safe; each works once.

**3. Add a passkey (optional but recommended)**

Click **Add passkey** and follow your browser's prompt. You can register multiple passkeys and security keys and remove them individually.

> [!NOTE]
>
> You cannot remove your last remaining factor while 2FA is active - add a replacement first.

## Signing In with 2FA

After your password (or SSO), Ankra prompts for a second factor. Use a passkey with one tap, enter a TOTP code, or switch to **Use a recovery code instead**. Repeated failed attempts invalidate the pending login and you'll need to start over.

## Organisation-Enforced 2FA

Organisations can require 2FA for all members. If any of your organisations enforces it and you haven't enrolled, Ankra shows a **Secure your account to continue** screen at sign-in and blocks the platform until you complete enrollment.

## Managing 2FA from the CLI

The CLI hands 2FA management to the browser, because TOTP enrollment, recovery codes and passkey registration (WebAuthn) all need one:

```bash theme={null}
ankra profile auth open   # open this account-security page in your browser
```

CLI logins that hit an MFA challenge complete in the browser and hand control back to the terminal automatically. Full command details are in the [CLI reference](/reference/cli/profile).


# Activity & Inbox
Source: https://docs.ankra.ai/platform/activity-inbox

A personal, real-time inbox of everything across your fleet that needs your attention - approvals, failures, and AI sessions waiting on you.

The Inbox is your personal worklist across the whole organisation. Instead of hunting through clusters to find what needs attention, Ankra surfaces actionable items - AI sessions waiting on you, plans to approve, actions to confirm, failed steps, and drafts the AI has edited - in one live, ranked list that updates in real time.

***

## What shows up in your inbox

| Item | Meaning | Typical action |
| - | - | - |
| **AI session awaiting you** | An [AI Assistant](/platform/ai-assistant) session is paused, waiting for your input | Answer and let it continue |
| **Plan awaiting approval** | An AI-generated plan is ready, with a breakdown of auto-executable vs confirmation-required steps | Review and approve/reject |
| **Pending action** | A single action awaits confirmation, tagged with a risk level and whether it's reversible | Confirm or decline |
| **Execution step failed** | A deployment or reconcile step failed (grouped into an incident when it spans multiple clusters) | Investigate and retry |
| **Draft with AI edits** | A [stack](/concepts/stacks) draft the AI has edited is waiting for your review | Review and commit |

Each item is ranked so the most pressing work rises to the top, and carries the context you need to act - the cluster, conversation, risk, and timestamps.

***

## Live activity feed

The Inbox is backed by a live stream (server-sent events), so items appear, update, and clear without refreshing the page. The feed delivers an initial snapshot, then incremental diffs as items are added, change, or are resolved, plus periodic heartbeats. It also tracks recent activity - sessions completed, plans approved, and actions resolved - so you can see momentum at a glance.

> [!NOTE]
>
> The live feed limits how many concurrent connections a single user can hold. If you open the dashboard in many tabs at once, additional connections are rejected until others close.

***

## Organisation messages and messages for you

A notification is addressed either to the whole organisation - a failed deployment, a firing alert - or to **you personally**, such as an agent reaching its daily token limit on a task you own or an answer only you were waiting for. Personal messages are visible only to their addressee and wear a **For you** marker in the feed; organisation messages reach every member, with reading, acknowledging and dismissing tracked per person - one member clearing a card never clears it for the team.

Filter the Activity page by audience (**All messages / For you / Organisation**), and the unread counts split out what is addressed to you personally.

## Dismissing and snoozing

Not everything needs action right now. Dismiss an item to clear it, or snooze it until a chosen time - it returns to the inbox when the snooze expires. You can restore a dismissed item at any time.

***

## How inbox cards clear

A failed operation and the card asking you to look at it are two different records. The operation stays in the cluster's history as failed for good (see [Find out why a deploy failed and retry it](/platform/operations#failed-history-versus-open-problems)); the card is the part that clears:

* **On their own.** Ankra re-checks open cards about once a minute. A failed-operation card resolves once the most recent run of that same operation on that cluster has succeeded; a card about a platform resource resolves when that resource's latest step succeeds or the resource is gone; a GitOps failure card resolves once the cluster reports itself in sync again. Resolved cards move to **Recently resolved** on the Activity page.
* **By hand.** Acknowledge a card to record that you have seen it, or dismiss it to clear it from your list. Both are tracked per person, so clearing a card never clears it for a colleague.

So a cluster that has recovered shows an empty or short **Open** section on the Activity page, while its operations history still lists every failed attempt from the rollout.

Acknowledging, dismissing and snoozing are portal actions: API tokens cannot reach the inbox. The token API covers the operations themselves, including cancel and retry - see the [API Reference](/api-reference/introduction).

***

## Recent drafts

Ankra keeps a list of the [stack](/concepts/stacks) drafts you've worked on recently, so you can jump back into in-progress work. Each entry shows the cluster, stack, when it was last touched, whether it has AI edits, and any co-editors (including the AI) collaborating on it.

***

## Preferences

Tailor your dashboard from preferences:

* **Pinned clusters** - keep the clusters you care about most at the top.
* **Widget layout** - show, hide, and arrange dashboard widgets.


# Add-on Catalog
Source: https://docs.ankra.ai/platform/addon-catalog

Find the add-on or Helm chart you want to run, check its version, values and license, and see where it is already installed.

Before you install monitoring, ingress or a database on a cluster, you need to find the right chart, pick a version and know what it will pull in. The add-on catalog is the one place in Ankra that answers this for every Helm registry your organisation has connected. Open it from **Add-ons** in the main sidebar.

## Add-ons and charts

The catalog shows two kinds of cards:

* **Add-ons** - a named tool such as Grafana or cert-manager, with a description, category and links. An add-on groups every chart that deploys it, using match rules (chart names, keywords and home URL prefixes), so the same tool published in several registries appears once. A card is marked **Public** when Ankra curates it for every organisation, or **Organisation** when your organisation curated it.
* **Charts** - a Helm chart from one of your registries. Charts that no add-on matches still appear, as uncurated charts.

A card that is already installed on one of your clusters shows **Installed**, or **Installed ×N** when it is installed more than once.

## Find what you need

Search matches display names, add-on names and the names of the charts an add-on groups. Three filters narrow the list:

| Filter | Options |
| - | - |
| Category | Every category in the catalog, with a count. Uncurated charts carry no category. |
| Source | **All sources**, **Curated by Ankra**, **My organisation**, **Uncurated charts**, and **Manifest add-ons** from [Applications](/concepts/applications) |
| In use | **All add-ons**, or **In-use** for the ones already installed |

When the catalog is empty or a chart you expect is missing, **Manage registries** takes you to the registries your organisation has connected. Adding a Helm or OCI registry there is covered in [Registries](/guides/registries); its charts are indexed and appear in the catalog.

## What a chart page shows

Selecting a chart opens it at a specific version, with a version selector and five tabs:

| Tab | What it shows |
| - | - |
| **Overview** | The chart's README, registry, homepage, sources, keywords, maintainers and license, and the add-on it belongs to |
| **Values** | The default values for this version |
| **Files** | The files inside the chart package, read-only |
| **Releases** | The chart's release notes |
| **Clusters** | The clusters and Stacks already running this chart, with their version |

The **License** field shows the license's SPDX identifier (for example `Apache-2.0`). Ankra reads it from the `artifacthub.io/license` annotation in `Chart.yaml`, or detects it from a `LICENSE` or `COPYING` file in the package, and says which. Copyleft licenses such as the GPL and AGPL family are highlighted, so a license that carries obligations for derived works stands out before you deploy.

## Install from the catalog

Add-ons run on a cluster as part of a [Stack](/concepts/stacks): you add the chart to a Stack, set its values, and Ankra installs it with Helm and keeps it reconciled. The steps are in [Install add-ons](/concepts/addons#install-add-ons). From a chart's **Overview** you can also use **Install with AI**, which asks the AI Assistant to help you pick a cluster and configure the installation.

## Curate your own add-ons

**Create add-on** defines an add-on for your organisation: a name, display details, a category and the match rules that link charts to it. On an add-on curated by Ankra, customising it creates your organisation's own copy, which takes precedence over the global one in your catalog. An add-on's page lists the charts that resolve to it, lets you link or unlink a chart by hand, and shows the clusters it is installed on.

Two guides cover sharing what you build:

* [Publishing add-ons](/platform/addon-publishing) - propose an add-on your organisation curated to the global catalog every organisation sees.
* [Publishing applications as add-ons](/platform/application-addons) - snapshot an application's manifests as a versioned add-on your organisation can install on any cluster.

## Next steps

* [Connect a Helm registry](/guides/registries) so its charts appear in the catalog.
* [Install an add-on through a Stack](/concepts/addons#install-add-ons).


# Publishing Add-ons
Source: https://docs.ankra.ai/platform/addon-publishing

Publish an add-on your organisation curated to the global Ankra Catalog, through a reviewable pull request.

> [!NOTE]
>
> Publishing proposes an add-on definition your organisation curated to the global Ankra Catalog. Nothing changes until the pull request it opens is reviewed and merged - after that, the add-on appears in the add-on catalog of every organisation on Ankra.

## What publishing does

The add-on catalog every organisation sees is backed by a public Git repository, [ankraio/ankra-global-resources](https://github.com/ankraio/ankra-global-resources). Each globally available add-on is one `kind: Addon` manifest in that repository's `addons/` directory - a small YAML file carrying the add-on's name, display metadata, and the match rules that link Helm charts to it.

When you publish an add-on:

1. Ankra renders your organisation's definition as a `kind: Addon` manifest.
2. It opens a pull request against the catalog repository on your behalf, on a dedicated branch.
3. The Ankra team reviews the pull request. Merging it is the approval.
4. The platform sync ingests the merged manifest, and the add-on becomes available to **all organisations**.

Your organisation keeps its own copy of the definition. An organisation-scoped add-on always shadows the global one with the same name, so publishing never changes what your own catalog shows you.

## Who can publish

Publishing puts your organisation's name on a pull request against a public repository, and once merged the entry is visible to every organisation on Ankra. It therefore requires the **Manage Helm registries** permission (`helm.manage`), which organisation **admins** and **owners** hold. Members and operators can open the publish flow and see everything it would propose, but not submit it.

## Publishing an add-on

1. Open **Add-ons** and select an add-on curated by your organisation (global add-ons are already published).
2. Select **Publish to Ankra Catalog**.
3. **Target** - where the proposal lands, and whether it can be made at all. Publishing is unavailable when:
   * the platform has no catalog repository configured
   * a publish request for this add-on is already open
   * the definition contains material that must not reach a public repository (see below)
   * you do not hold `helm.manage`
4. **Review** - the exact manifest the pull request will add, or a **diff** against the currently published version when the add-on is already in the catalog.
5. **Confirm** - a recap of what changes and where, then **Publish via pull request**.

The flow shows the opened pull request immediately, with a direct link. Publishing is idempotent: while a pull request for the add-on is open, publishing again returns the existing request instead of opening a duplicate.

## What cannot be published

The catalog repository is public, and a pull request is effectively permanent - a credential that reaches it is in the repository's history even if the branch is later closed. Ankra screens the rendered manifest before it can be proposed and refuses anything carrying:

* credentials embedded in a URL, such as `https://user:password@host`
* recognisable provider tokens - GitHub, GitLab, AWS, Slack, generic API secret keys, or a PEM private key block

The offending field is named so it can be corrected. This is a check on the ten metadata fields an add-on definition publishes; it is not a substitute for keeping credentials out of your definitions in the first place.

## Tracking a publish

The add-on's detail page gains a **Publish history** section listing every publish request with its pull request link and lifecycle state:

| State | Meaning |
| - | - |
| **Pull request open** | The proposal is awaiting review on the catalog repository. |
| **Merged - awaiting sync** | The pull request was merged; the platform sync (which runs every few minutes) has not ingested it yet. |
| **Live in the catalog** | The add-on is available to every organisation. |
| **Closed without merging** | The pull request was declined. |
| **Failed** | The pull request could not be opened; the reason is shown on the request. |

States advance automatically - open pull requests are re-checked by the platform, and the history refreshes while a request is in flight.

## The Addon manifest

The manifest published for your add-on mirrors the definition fields:

```yaml theme={null}
apiVersion: v1
kind: Addon
spec:
  name: grafana
  display_name: Grafana
  description: The open observability platform.
  website_url: https://grafana.com
  documentation_url: https://grafana.com/docs/
  icon_url: https://grafana.com/logo.svg
  category: Data Visualization
  match_chart_names:
    - grafana
  match_home_url_prefixes:
    - https://grafana.com/oss
```

`spec.name` is the add-on's unique slug across the catalog. The match rules (`match_chart_names`, `match_keywords`, `match_home_url_prefixes`) determine which Helm charts resolve to the add-on in every organisation's catalog.

## Removing a published add-on

Removing the manifest from the catalog repository (again through a pull request) retires the global add-on. Organisations that customised it keep their own copies - only the shared, Ankra-curated entry goes away.


# Teach Your Agents with AGENTS.md
Source: https://docs.ankra.ai/platform/agents-md

Per-add-on and per-manifest AGENTS.md documents capture operational learnings that teammates and Ankra's AI read and write.

Every manifest and add-on in a Stack can carry an optional **AGENTS.md** - a markdown document of operational learnings for that one component: upgrade gotchas, safe rollout order, values that must stay pinned. Teammates and Ankra's AI accumulate knowledge there over time, so the next person (or agent) touching the component starts from what the last one learned.

AGENTS.md is deliberately narrow: it belongs to a single add-on or manifest and travels with it in the GitOps repository. For organisation-wide conventions that apply to every conversation, use [AI Skills](/platform/ai-skills) instead - skills are org-scoped instructions, AGENTS.md is per-resource learnings.

## Where the Files Live

Ankra writes each document as a sibling file next to the component it describes, in the connected GitOps repository:

```
clusters/<cluster-name>-<short-id>/
└── stacks/<stack-name>/
    ├── README.md                      # the Stack's description
    ├── add-ons/
    │   └── <addon-name>/
    │       ├── values.yaml
    │       └── AGENTS.md              # learnings for this add-on
    └── manifests/
        ├── <manifest-name>.yaml
        └── <manifest-name>.AGENTS.md  # learnings for this manifest
```

This mirrors how a Stack's `description` becomes `README.md`: the main IaC document carries only an `agents_md_from_file` pointer, never the content itself, so the markdown stays readable and diffable in Git.

## Authoring

There are three equivalent ways to write an AGENTS.md, and they converge on the same sibling file:

* **Portal** - every add-on and manifest panel in the Stack Builder has an **AGENTS.md** tab with a markdown editor and preview.
* **IaC YAML** - set `agents_md` (inline markdown) or `agents_md_from_file` (a path relative to the cluster directory) on the entry in your [ImportCluster](/reference/importcluster) definition. Inline content is normalised to a sibling file on the next platform push.
* **Git** - commit an AGENTS.md file directly in the GitOps repository and reference it with `agents_md_from_file`.

```yaml theme={null}
addons:
  - name: fluent-bit
    chart_name: fluent-bit
    chart_version: 0.49.1
    registry_name: fluent
    registry_url: https://fluent.github.io/helm-charts
    namespace: fluent-bit
    agents_md: |-
      # fluent-bit learnings
      - Keep `service.enabled: true` - the health checks depend on it.
      - Upgrade one minor version at a time; jumping 0.48 to 0.50 broke parsers.
```

## Semantics

| Behaviour | Detail |
| - | - |
| Omit the field | The stored document is preserved unchanged |
| Empty string | Clears the document - the file is removed from the GitOps repository on the next reconcile |
| Edit the content | Never triggers a redeploy of the resource - AGENTS.md is documentation-only and deploy-neutral |
| GitOps conflicts | AGENTS.md edits auto-merge rather than conflicting with body edits |
| Encryption | Content is plaintext in the Git repository - it is never SOPS-encrypted |

> [!WARNING]
>
> AGENTS.md is stored as plaintext in your Git repository and is shown to AI agents. Never put credentials, tokens, or other secrets in it - use [SOPS](/guides/sops) encrypted values or Kubernetes Secrets for sensitive data.

## How Ankra's AI Uses It

Ankra's AI - the [AI Assistant](/platform/ai-assistant), agents, and [MCP clients](/platform/mcp-server) - reads AGENTS.md wherever it reads the Stack: `get_stack_details` returns each component's document, and `export_cluster_iac` includes it in the exported IaC. When the AI learns something worth keeping - a flag that must stay pinned, an upgrade that needs a manual step - it can write that learning back through the `create_stack` and `update_stack` tools' `agents_md` field, so the knowledge persists beyond the conversation.

## Related

* [ImportCluster YAML Schema](/reference/importcluster) - the `agents_md` and `agents_md_from_file` fields
* [GitOps](/concepts/gitops) - how the repository is structured and synced
* [AI Skills](/platform/ai-skills) - organisation-wide AI instructions


# AI Agents
Source: https://docs.ankra.ai/platform/ai-agents

Your organisation's AI team - six preloaded role agents, direct persona chats, and an AI-guided wizard for creating custom agents

Every organisation comes with a preloaded **AI team**: six agents, each with a role, a persona, and safe defaults. They appear under **AI → Agents** the first time anyone opens the roster, and each one can be chatted with directly or dispatched to work autonomously.

Watch a stack deployed and its upgrades handed to an agent, with the risky change parked for a human to approve.

[Deploy a stack and hand its upgrades to an AI agent - Ankra](https://www.youtube-nocookie.com/embed/dspH7l5YO54?rel=0)

## Your default AI team

| Agent | Role |
| - | - |
| **AI Team Lead** | Your first point of contact. Triages requests, routes work to the right specialist, files tickets for anything that outlives the conversation. |
| **Developer** | Application delivery: Helm charts and values, deploys, CI/CD workflows, and pull-request demos. |
| **Database Admin** | Stateful workloads: StatefulSets, volumes, operators, and backup hygiene. Verifies backups before proposing anything that touches data. |
| **SRE** | Reliability: alert triage, golden signals, incident timelines, and postmortem notes. Evidence-first. |
| **DevOps** | The platform itself: clusters, node pools, add-ons and stacks, GitOps drift, and IaC. One reversible step at a time. |
| **DevSecOps** | Security findings: reads a cluster's security report, maps every vulnerable image to the connected application or add-on that deployed it, and fixes critical and high CVEs at the source as pull requests and add-on upgrade proposals. |

The defaults are deliberately conservative: they never run on a schedule, they only **propose** changes (every mutation waits for your approval), and they cost nothing until you talk to them or press **Run now**. Delete any you don't want - they stay deleted, and you can re-hire them individually from the agent catalog at any time. When a new role joins the default team, every organisation is offered it once, the next time anyone opens the roster; a default you deleted earlier is never brought back by that.

## The DevSecOps agent

The DevSecOps agent turns a cluster's security report into fixes. Open it from a cluster's chat (the report is per cluster) and ask it to clear the critical and high findings, or file a board ticket scoped to the cluster and let the dispatcher hand it over. It works in a fixed order:

1. **Reads the security report** for the cluster - the same Trivy Operator findings the [Security Center](/guides/cluster-security) shows - filtered to critical and high, and quotes the CVEs, their fixed versions, and the workloads each one runs in.
2. **Maps each vulnerable image to what deployed it**: a [connected application](/concepts/applications) deployed to that cluster, matched by namespace and image repository, or the add-on the report attributes the image to.
3. **Fixes applications at the source.** It reads the Dockerfile and dependency manifests in the application's repository, bumps the base image to a patched tag or the vulnerable package to its fixed version, and opens one pull request per application listing every CVE it clears with the installed and fixed versions and the workloads affected. The pull request is the review gate; it never commits to the default branch.
4. **Proposes add-on upgrades** for images that belong to a Helm add-on - the chart version that ships the fix, with the current version as the rollback - and hands the rollout to the DevOps agent.
5. **Verifies** once the pull request has merged and the image has been rebuilt, by re-reading the report and quoting the before-and-after counts.

Known-exploited CVEs ([CISA KEV](/guides/cluster-security#exploitation-intelligence-cisa-kev-and-epss)) come first, then criticals, then highs, fixable before unfixable, production clusters before the rest. A CVE with no published fix is reported, not hidden, and any risk acceptance stays a human decision. The agent's capability envelope refuses to delete a resource, an application, a stack, or an add-on, so a finding is never "fixed" by removing what runs.

It needs Trivy Operator on the cluster (the security baseline installs it) and, to open pull requests, a connected application whose repository Ankra's GitHub App can write to.

Unlike the other defaults, the DevSecOps agent ships **acting as your organisation's agent identity**, so it can propose changes and open pull requests from its first run. Ankra provisions that identity (the built-in **operator** role) the first time anyone opens the roster; you can change its role or stand it down under **Settings → Autonomy → Board staffing**, and a stood-down identity is never re-provisioned behind your back. Its autonomy stays **Propose**: every cluster write still waits for your approval, and a pull request is its own review gate.

## Fleet status at a glance

The Agents page is a triage surface: every row shows what its agent's latest run is doing, and what - if anything - it needs from you.

| Status | Meaning | Call to action |
| - | - | - |
| **Needs your input** | The run parked on a question or an approval and resumes once you answer. | **Respond** - opens the exact chat conversation the agent is waiting in. |
| **Blocked** | The mission ended because the agent judged the goal blocked; its verdict explains why. | **Review** - opens the agent with the run's transcript and outcome. |
| **Failed** / **Expired** | The last run errored or ran out its budget window. | **Review** |
| **Working** | A run is live right now. | **View live** - follow the transcript as it streams. |
| **Goal met** / **Completed** | The last run finished cleanly. | None |
| **Never run** | The agent has no run history yet. | **Run now** (admins) |

Picking a run in the **Runs** rail puts it in the page address, so a shared link opens that run rather than the agent's most recent one.

Each row also swaps its goal prompt for the latest run's **outcome summary** once one exists, so the list reads as "what happened last", not "what was asked months ago".

Agents that need a person sort to the top of their section, and a summary strip above the list counts them - **need input**, **blocked**, and **failed** chips filter the list to just those agents. Finished one-off missions fold away under **Completed missions**, keeping old dispatches out of the way without deleting their history. In the sidebar, the **AI Agents** item carries a badge with the number of agents currently waiting on your input - the same way the Board badges tickets that need a human.

## Chat with an agent

Every agent has a **Chat** action - on the roster, on the agent list, and on its detail page. It opens the AI chat scoped to that agent: the conversation carries the agent's persona, so the SRE talks incidents and evidence while the Database Admin double-checks backups before anything else. The persona only ever narrows what an agent may do; the platform's normal approval rules for mutating actions apply unchanged.

## Create your own with the AI wizard

**New agent** on the Agents page starts a short interview instead of a form. The wizard asks for a role, drafts a name (shuffle it if you disagree), lets you pick focus areas, a cluster scope, a communication style, and guardrails - then writes the agent's persona for you. Review and edit the persona before hiring; the result is a real agent that behaves exactly like the preloaded team.

Prefer the classic form? The wizard's footer switches to **Manual setup** at any point.

> [!NOTE]
>
> Creating, deleting, and running agents requires an organisation admin role. Chatting with an agent is open to every member.

## Autonomy and budgets

Each agent carries an autonomy level - **Observe** (read-only), **Propose** (suggests, you approve), or **Autonomous** (executes low-risk reversible actions itself) - and hard budgets for tool calls, turns, and runtime. Budgets are the hard stop for autonomous work; the defaults ship with **Propose** and modest budgets.

### Model

Each agent can be pinned to a model from your organisation's catalog: **Quick** (the fast, low-cost rung), **Think**, **Expert**, or any custom catalog entry. **Auto** leaves the choice to the router on every turn. The pin applies to the agent's scheduled and run-now dispatches, its board tickets, its mission continuations, and persona chats with it alike. Edit it from the agent's **Edit** dialog. Every agent Ankra ships - the six default roles and the catalog agents - is pinned to **Quick**, because most of their work is reading state and editing manifests. Raise one agent to **Think** or **Expert** when its work needs it.

### Daily token limit

Each agent can carry its own **daily token limit**: every token the model processes on the agent's behalf in one UTC calendar day, across runs and persona chats, cached prompt reads included. When an agent reaches its limit:

* the scheduler stops dispatching it for the rest of the day - schedules, **Run now**, board tickets, and mission continuations all wait;
* a turn already in flight finishes with one wrap-up iteration instead of being cut mid-thought;
* a **notification** goes out once for the day - in the inbox, and through your notification routes to Slack or Teams - naming the agent, the tokens used, and how to raise the limit.

The agent resumes at midnight UTC, or as soon as an admin raises the limit. Today's usage sits beside the limit on the agent page. The DevSecOps agent ships with a 2,000,000-token daily limit; the other default agents are unlimited until you set one.


# AI Assistant
Source: https://docs.ankra.ai/platform/ai-assistant

Ask Ankra's AI why something is failing, from the page you are on - what it reads, the Ask, Agent and Plan modes, example prompts, and where your data goes.

When something breaks, the slowest part is usually gathering context: logs, events, what was deployed and when. The AI Assistant reads all of that from the page you are on, so you can ask "why is this failing?" and get an answer based on your cluster's actual state - and connect a symptom in one pod to the deploy that caused it.

![AI Assistant interface](https://mintcdn.com/ankra/IxzKZ_b1d6AKyO5X/images/ai-chat.png?fit=max\&auto=format\&n=IxzKZ_b1d6AKyO5X\&q=85\&s=0503c32aa74d2843afaf579921f43437)

## Open the assistant

Press `⌘J` (Mac) or `Ctrl+J` (Windows and Linux) from anywhere in Ankra. `⇧⌘J` switches the chat to full screen, and `⇧⌘O` starts a new chat. You can also click the chat icon in the bottom-right corner of a cluster page, or search for "AI Chat" in the Command Palette (`⌘K`).

The assistant starts from what you are looking at, so you do not need to name the resource:

| You're viewing | The AI already knows |
| - | - |
| **A pod** | Its logs, manifest, events, resource usage, and parent deployment |
| **A deployment** | Its replicas, rollout status, services, and recent changes |
| **A Stack** | Its add-ons, Helm values, deployment history, and dependencies |
| **Logs** | The filtered logs, error patterns, and related resources |
| **A service** | Its endpoints, selectors, pods, and ingress rules |

Beyond the current page, it can read pod logs, the manifests actually deployed, which Stacks deployed what and with which values, resource states and events, and the [AGENTS.md](/platform/agents-md) notes your team keeps per add-on and manifest. Where [AI Insights](/platform/ai-insights) has flagged a resource, its banner offers **Ask AI** to open the chat with that finding loaded.

Watch the assistant build and troubleshoot a Stack:

[How to use Ankra AI Assistant for Cloud Native Kubernetes Stacks](https://www.youtube-nocookie.com/embed/4Y5Zcza1QG0?rel=0)

## Ask, Agent, or Plan

The chat's mode decides how far the assistant may go. Pick it in the chat input, or under the chat's **AI settings** → **Interaction mode**. It is your own preference, and it applies to your conversations only.

| Mode | What the assistant may do |
| - | - |
| **Ask** | Read-only on existing infrastructure. It investigates and explains, and may create throwaway AI workspaces and PR demos, but never changes what is already running. |
| **Agent** (default) | It runs tools and can act, but stops before every cluster write with a confirmation card describing the action, its blast radius and, for deploys, a diff. |
| **Plan** | It proposes a multi-step plan first. You approve the plan as a whole, then it runs the steps. |

Because clusters change underneath you, Ankra re-checks the live state when you confirm. If the cluster drifted from what the action or plan was based on, the confirmation is blocked so you review the change again rather than apply something stale.

For everything else that bounds the AI - connection modes, agents, alert remediation, and the emergency stops - see [What it can change without asking](/platform/ai-overview#what-it-can-change-without-asking).

> [!NOTE]
>
> Actions awaiting confirmation, plans awaiting approval, and sessions waiting on your input all surface in your [Activity & Inbox](/platform/activity-inbox), so long-running work does not get lost when you navigate away.

### Autonomy: Manual or Auto

In Agent mode, your **AI settings** → **Autonomy** preference decides whether writes stop for you:

* **Manual** (the default) - every write stops at a confirmation card.
* **Auto** - low-risk, reversible writes run immediately and land in the conversation as a receipt instead of a card. That includes a Stack deploy whose validated change set removes nothing, executed with its full bill of materials attached to the receipt.

Whatever the setting, cluster lifecycle changes, removals, high-risk or irreversible writes, and changes that failed validation still ask, and writes into protected namespaces such as `kube-system` are refused outright. Every auto-approved action is recorded in the [audit log](/guides/audit-log) with its autonomy attribution.

This setting is separate from the organisation-wide [AI Autonomy](/platform/ai-autonomy) controls, and from the **Auto** entry in the model picker, which only routes between models.

### Skills and tools

The assistant draws on **skills** - reusable instructions for specific tasks, such as packaging an add-on or generating a CI/CD pipeline. Organisation skills take precedence over Ankra's built-in ones; see [AI Skills and Custom Tools](/platform/ai-skills).

Its tools are the same ones the [MCP server](/platform/mcp-server) exposes, under the same permission checks; the full list is in the [MCP Tool Reference](/platform/mcp-tools). Chat from Slack, Microsoft Teams or pull request comments uses the same tools too, and each of those connections can be capped further with its own AI mode - see [AI Connections](/platform/ai-connections).

## Example prompts

Start from the symptom. The assistant checks pod logs for errors and timeouts, looks at which Stacks were deployed recently and what values changed, reads the state and events of the resources involved, and ties them together into a root cause with the evidence it found.

> [accordion] Incident response
>
> * "Why is this pod failing?"
> * "Users are reporting slow API responses. What changed in the last hour?"
> * "The API is returning 500 errors. Was anything deployed recently that could cause this?"
> * "Compare the current ingress configuration to what was running yesterday"
> * "Which upstream service is causing the 503 errors?"
> * "The deployment rollout is stuck - what's blocking it?"

> [accordion] Add-ons and Stacks
>
> * "Why did cert-manager fail to install?"
> * "I need a production-ready ingress with TLS" - it proposes the components (for example cert-manager and Traefik), their order, and starting values.
> * "My monitoring stack is using too much memory" - it reads the deployed Helm values and suggests changes such as retention windows and resource limits.
> * "Clone this Stack for staging but with smaller resource requests"

> [accordion] Configuration
>
> * "Is my resource limit configuration right for this workload?"
> * "Why is this HPA not scaling?"
> * "Explain the network policies affecting this service"
> * "What secrets does this deployment need?"

> [accordion] Cluster health
>
> * "Are all pods healthy?"
> * "How many namespaces are in this cluster?"
> * "Which nodes are under memory pressure?"

Follow-up questions keep the context of the conversation, so after asking about a failing pod you can ask "how do I fix that?" without naming it again. When a fix means creating Kubernetes resources, the assistant proposes them as a Stack change rather than a `kubectl` command, so the change is versioned in your GitOps repository.

## Common failure patterns

| Pattern | Usual cause | What the assistant checks |
| - | - | - |
| **CrashLoopBackOff** | The application exits with an error | Logs, exit code and error messages |
| **ImagePullBackOff** | The container image cannot be pulled | Image name, registry, and pull credentials |
| **Pending** | The pod cannot be scheduled | Node resources, taints, and tolerations |
| **OOMKilled** | Out of memory (exit code 137) | Memory limits against actual usage |
| **Evicted** | The node is under pressure | Node conditions and pod priority |
| **CreateContainerError** | Container configuration | Volume mounts, Secrets, and ConfigMaps |

For a failing add-on it also reads the Helm release state, the add-on's configuration values, the latest install or update job, and missing CRDs.

## History, models and feedback

Conversations are saved and can be resumed - open them from the history icon in the chat header or search "Chat History" in the Command Palette. The model picker switches between the **Expert**, **Think** and **Quick** tiers, trading speed for depth; **Auto** picks one per question. Rate any answer with the thumbs buttons - see [AI Memory and Feedback](/platform/ai-memory). What each tier runs on is described in [Models and Cost](/platform/ai-provider).

## What happens to your data

* **Which provider receives it.** Your question, the conversation, and what the assistant reads from your cluster (logs, events, manifests) are sent to the model that answers. On Ankra's default models that is Ankra's managed access: the Expert and Think models through OpenRouter, and Claude models through Anthropic. With your own [provider key](/platform/ai-provider#provider-modes), calls your key can serve go to your provider on your account; anything it cannot serve runs on Ankra's default access, and the **Models** settings page names which models those are.
* **Exceptions with your own endpoint.** Summarising a long conversation's earlier history runs on Ankra's platform access to Anthropic whatever provider you use. If a self-hosted endpoint fails mid-turn, the turn continues on the Ankra default with a notice, unless an admin sets the endpoint failure policy to **Fail the turn**.
* **Secrets are withheld.** Kubernetes Secret values never reach the model - only their key names. Tool results, your questions and the conversation history also pass through a secret detector that replaces anything that looks like a password, token or key with a redaction marker.
* **Where it is kept.** Conversations are stored against your account in your organisation. You can delete a conversation from your chat history, or with `ankra chat delete`.

## Next

Decide how far the AI may go on its own across your organisation: [What it can change without asking](/platform/ai-overview#what-it-can-change-without-asking).


# AI Automations
Source: https://docs.ankra.ai/platform/ai-automations

Build workflows on a canvas - triggers, agent steps, conditions, approval gates, and outputs - and let them run on a schedule, an alert, or a webhook.

The **Automations** designer under **AI** → **Automations** is where you build repeatable AI workflows as a node graph: a trigger starts the workflow, agent steps do the work, conditions route on results, approval gates pause for an administrator, and an output delivers the result. The page has three panels - the **Workflows** list, the canvas, and the **Inspector** for the selected node.

## Anatomy of a workflow

| Node | Role |
| - | - |
| **Trigger** | Starts the workflow |
| **Agent** | Investigates or takes action - a goal prompt plus a model, tool profile, and autonomy level |
| **Condition** | Routes by an earlier result - match on the previous step's outcome, status, or summary |
| **Approval** | Waits for an administrator before continuing |
| **Output** | Completes the workflow and posts a notification message |

Every workflow needs a trigger. The trigger kind decides when it runs:

* **Manual run** - only when someone presses **Test run**.
* **Schedule** - a cron expression with a timezone.
* **Alert fires** - bound to one of your [alert rules](/guides/alerts).
* **Webhook** - an external system calls in.

## How a run executes

Ankra walks the graph node by node. An agent step opens an agentic session with the step's goal prompt and waits for it to finish; a condition picks the branch whose comparison matches; an output posts its notification and completes the run. Recent runs are listed per workflow in the Inspector.

When a run reaches an **Approval** node, it pauses and files a ticket on the [AI Board](/platform/ai-board) directly into **Awaiting approval**. Approving - from the Inbox or the ticket - resumes the run; denying cancels it. The run's outcome settles the ticket when it finishes.

> [!NOTE]
>
> Approval gates are how an automation stays safe on a schedule: the workflow can investigate and prepare autonomously overnight, but nothing irreversible happens until a person signs off.

## Templates

**Start from a template** in the Workflows list seeds a ready-made graph you can adapt:

* **Nightly cluster fix plans** - scheduled sweep that drafts fixes and parks them for approval.
* **Daily insight digest** - collects the day's findings into one notification.
* **On alert: diagnose** - triggered by an alert rule, investigates, and reports.

## Editing and permissions

Workflows are **Enabled** or **Paused**, and the command bar shows an **Unsaved** chip until you press **Save**. **Test run** is available once an enabled workflow is saved. Only organisation admins can edit; everyone else sees the designer read-only. Deleting a workflow lives in the Inspector's danger zone.

Automations dispatch agent sessions per step, which makes them the graph-shaped complement to [AI Agents](/platform/ai-agents) - standing agents with a single trigger and goal. Reach for an agent when one prompt on one trigger is enough, and an automation when the work has stages, branching, or an approval in the middle.


# AI Autonomy
Source: https://docs.ankra.ai/platform/ai-autonomy

Control what Ankra's AI may do on its own - the global pause, the auto-remediation policy, approval rules, and proactive insight thresholds.

The **Autonomy** section under **AI** → **Settings** → **Autonomy** is the single place where organisation admins decide how much Ankra's AI does without a human in the loop. Everything on this page is organisation-wide.

> [!NOTE]
>
> Autonomy is opt-in. A new organisation starts with auto-remediation disabled and no active agents - nothing runs autonomously until an admin turns it on here.

## Stopping the AI

The **Stopping the AI** card at the top of the page has two stops, from least to most disruptive. Both apply to everyone in the organisation and take effect immediately.

1. **Pause autonomous actions** - chat, diagnosis and read-only investigation keep working, but the AI cannot change anything without a person approving it first. It switches off the auto-remediation policy and pauses every running agent. Resuming restores exactly what the pause switched off - it never enables anything that was off before the pause. The pause is stored on the server, so any admin can resume it from anywhere.
2. **Stop all AI** - the emergency stop. Nothing keeps working: it cancels every running AI session and agent run, expires pending approvals, and blocks chat for everyone until an administrator resumes it. Use it during an incident, not to tighten a policy.

Both are also in the CLI as `ankra ai autonomy pause` and `ankra ai autonomy stop-all`, with `resume` and `start-all` to undo them - see [`ankra ai`](/reference/cli/ai).

## Auto-Remediation Policy

The policy is off on a new organisation: firing alerts are not handed to an agent until an admin switches it on. When enabled, the remediation agent can act on detected incidents, within these limits:

* **Autonomy level** - **Observe only** (diagnose and report, never touch the cluster), **Propose** (every corrective action goes to Slack for approval; the default), or **Autonomous** (low-risk reversible actions run on their own; the rest ask first).
* **Approvals** - approval requests go to a Slack webhook; you can name the users allowed to approve.
* **Limits** - a cap on actions per incident (5 by default) and a cooldown before the same alert on the same cluster is picked up again (30 minutes by default).
* **Per-action rules** - override individual tools (for example `delete_pod` or `restart_deployment`) to **Run automatically**, **Ask on Slack**, or **Never run**. **Run automatically** means that action runs with no approval card at all.
* **Cluster scope** - apply the policy to all clusters or an explicit allow-list.

Enabling the policy asks for confirmation and shows what the chosen level authorises before saving.

## Ticket Desk

The ticket desk auto-files board tickets from proactive insights. Pick which severities create tickets and where ticket notifications go (a Slack channel or Teams conversation). See the [AI Board](/platform/ai-board) for how filed tickets are worked.

A drafted plan waits for a verdict from a reviewer agent. Bind the reviewer here, or turn the review requirement off so plans go straight to a person - otherwise plans park in review with nothing able to clear them.

## Board Staffing

Board tickets are only worked by an agent you designate here. Until one is, every ticket the AI files is escalated straight to a person. Platform-created agents need the board identity before they can be designated; both live on the same card.

## Proactive Insight Thresholds

Tune when the platform flags cluster health issues - the restart-count threshold and how recent restarts must be to count. Leave a field empty to use the platform default. The **Analyse cluster health issues automatically** toggle in the same section turns the analysis on or off entirely; see [AI Insights](/platform/ai-insights).

## Permissions

Everything on this page requires organisation **admin**. Members can view the current policy but not change it.

## Next

See how these controls fit with chat modes, connection modes and agent autonomy in [What it can change without asking](/platform/ai-overview#what-it-can-change-without-asking).


# AI Board
Source: https://docs.ankra.ai/platform/ai-board

The shared board where every unit of AI work is a ticket - statuses, plans, peer review, human approval, escalations, and Slack or Teams threads.

The **Board** under **AI** → **Board** is where all AI work lives. Every unit of work is a ticket: agents pick tickets up, investigate, draft a plan, get it peer-reviewed, and wait for a person to approve before executing. You watch, intervene at the gates, and close the loop.

## The ticket lifecycle

A ticket moves through these statuses, shown as columns in the Kanban view:

| Status | What it means | Who acts |
| - | - | - |
| **Triage** | Filed, not yet assigned | The dispatcher, or you |
| **Investigating** | An agent is gathering context | Agent |
| **Planning** | The agent is drafting a plan | Agent |
| **Awaiting review** | A plan is drafted and waiting for critique | Reviewer agent |
| **Awaiting approval** | A plan waits for a person to sign off | You |
| **Executing** | The approved plan is being carried out | Agent |
| **Verifying** | The agent is checking the fix took | Agent |
| **Blocked** | The assignee needs a human to unblock it | You |
| **Done** | Resolved, with a resolution recorded | - |

Cancelled tickets leave the board. A ticket closes with one of these resolutions:

| Resolution | Meaning |
| - | - |
| **Fixed** | The problem was corrected, with evidence recorded on the close - a probe that passed, a run's verification steps, an observation of live state, a link, or a person's word |
| **No action needed** | Nothing had to change |
| **Duplicate** | Folded into another ticket |
| **Won't fix** | Declined |
| **Escalated** | Handed to a person outside the board |
| **Unverifiable** | Fixes were applied and reported success, but nothing confirmed them against live state |
| **Cleared** | The alert stopped firing after a remediation, without anything confirming the resource is healthy |
| **Expired** | The ticket waited at a human gate until it timed out. Nothing was executed |

## Where tickets come from

* **Proactive insights** - findings from continuous cluster analysis are auto-filed at the severities you pick in the ticket desk settings. See [AI Insights](/platform/ai-insights).
* **Alert remediation** - when an alert fires and auto-remediation spawns, an incident ticket tracks it, and it closes itself when the alert clears. See [Alerts](/guides/alerts).
* **Known Ankra issues** - when an alert comes from a problem in Ankra itself rather than your cluster (an Ankra service failing, Ankra's registry erroring, the cluster agent's credential refused by Ankra), Ankra engineering gets the problem and your board gets a ticket titled `Known Ankra issue: ...`, labelled `known-issue` and `platform-owned`. It is parked at **Blocked**, no agent works it, nothing on the cluster is changed and no question is asked of you. It closes itself as **No action needed** when the alert clears, and reopens if the problem returns.
* **Automations** - a workflow that reaches an approval gate files a ticket directly into **Awaiting approval**. See [AI Automations](/platform/ai-automations).
* **People and agents** - the **File a ticket** button, or the `file_ticket` tool from a chat or [MCP](/platform/mcp-tools) session, including [your own agent](/guides/board-own-agent).
* **Chat fixes** - when a person applies a gated write on a cluster through the AI chat or an MCP client (a stack draft, a scale, a restart), Ankra records it on a receipt ticket labelled `chat-fix`, one per conversation, with every action recorded as a change. See [Changes and the bill of materials](#changes-and-the-bill-of-materials). Receipts are an audit trail of your own actions, so they stay off the board: its views, its counts and `ticket_list` leave them out. A receipt keeps its number and timeline and opens from a link, and the ticket list API returns receipts when asked with `include_receipts=true`.

Each ticket carries a kind - **Incident**, **Insight**, **Gap**, **Automation**, **Request**, or **Chore** - and a priority from **Urgent** to **Low**.

## How agents work a ticket

A dispatcher sweeps the board and assigns unowned **Triage** tickets to an agent designated as a **board worker**, preferring one scoped to the affected cluster. Only designated agents are staffed: designate them under **AI** → **Settings** → **Autonomy** → **Board staffing**. With no eligible board worker, a ticket is escalated to a person instead of waiting silently. The agent gets a work brief and starts investigating; everything it does lands on the ticket's timeline.

Commenting on a ticket wakes the assignee, even while the ticket is parked at **Awaiting approval** - so a reply is how you steer an agent mid-flight. Only a person's comment does this: a comment a model writes - from the AI chat or an MCP client - is recorded on the timeline but does not wake the agent. Run budgets come from your [autonomy policy](/platform/ai-autonomy): a cap on runs per ticket and a cooldown between them.

### Watching an agent work

While a run is in flight the ticket shows what the agent is doing right now, at the foot of the timeline just above the comment box: a spinner, the step it is on - the tool it is calling and what it is calling it on - and the last few steps behind it, updating as the run moves. A run that is queued, or parked waiting for a person, says so instead of claiming to be working.

**Open the agent's session** on that panel goes to the full transcript of the run working your ticket, where you can read every tool call and result, answer a question, decide an approval, or guide the agent. The same session is one click from three other places:

* the **is working** chip at the top of the ticket, while a run is live
* **Open the agent's session** under the timeline entries that record a run - the note saying an agent started work, and the entry reporting how the run ended
* the **Agent run** entry under **Linked** in the right rail

Every run has its own address, so a link to one can be pasted into a thread or a ticket and it opens the run it names rather than whatever that agent ran most recently. Runs older than the agent's loaded history say so rather than quietly showing a different one.

## Plans, review, and approval

The plan is the contract between the agent and you:

1. The agent drafts a plan on the ticket.
2. If a reviewer agent is configured in the ticket desk settings, it critiques the plan. Requiring peer review has an effect only while a reviewer is configured. Badges on the ticket row track the state: `plan drafted`, `changes requested`, `peer approved`.
3. The ticket parks at **Awaiting approval**. The decision panel at the top of the ticket offers **Approve**, which releases it to **Executing**, and **Reject**, which asks for a reason and sends the ticket back to **Planning** - the agent reads your reason and revises the plan.

An agent can also park a ticket at **Awaiting approval** without a plan, when what it needs is a decision rather than a review - a capacity call, an alert threshold change. The same panel decides those: **Approve** lets the agent proceed, **Reject** with a reason sends it back to re-plan. An automation approval gate is decided on the run (**Approve** / **Deny**) from the same panel or the Inbox, and an agent parked on a risky action is decided on that action under **Needs your approval**.

> [!NOTE]
>
> Approving a plan does not widen what the agent may do. Actions beyond its autonomy level still ask for confirmation individually - those requests appear in the Inbox and on the ticket's **Needs your approval** panel. Agents cannot approve plans on your behalf, and an assignee can never review its own plan.

## Changes and the bill of materials

Every write an agent or the chat applies on a ticket's behalf is a **change** on the ticket, listed under **Changes** like a commit log. Each entry names the tool that ran, who approved it (a person, an autonomy policy, an approved plan step), its risk level and reversibility, the **cluster** and **stack** it touched with the namespaces involved, when it was proposed and when it settled, and the **operation** it created on the cluster's operations ledger with its step outcome - `6/6 steps succeeded`, or the failing step and its error. The verdict follows the operation, not the tool's reply: a change whose apply is still running reads **applying**, one whose apply failed afterwards reads **failed**, and one parked for confirmation reads **awaiting approval**.

Expanding an entry shows **what changed** - the same bill of materials the approver reviewed before the action ran: the addons added, updated or removed with their chart and version, the manifests with their kind and namespace, and the value and content diffs behind them. An action that parked without a preview says so outright rather than listing nothing.

The **Bill of materials** panel in the ticket's rail folds every change into one view of the ticket's blast radius: the clusters and stacks (linked to their pages), the namespaces, each addon with its chart version, each manifest with its kind, and the executions on the operations ledger. A rejected or expired change contributes nothing to it. The same ledger is available on the API at `/api/v1/org/ai-tickets/{ticket_id}/changes`.

## When a person is needed

A ticket needs a human when it is **Awaiting approval**, **Blocked**, or **Awaiting review** with a peer-approved plan. The **Needs a human** view collects exactly those, and the AI sidebar badge counts them.

If a ticket goes stale - untouched for a day while unfinished - or becomes blocked, Ankra raises an **AI ticket needs a human** notification and records the escalation on the timeline. A plan arriving at **Awaiting approval** raises **Plan awaits your approval**. Both deep-link to the ticket.

### Answering a choice

When what blocks the ticket is a choice - the agent found more than one way forward and needs you to pick - the ticket page opens on the agent's question with the options it offered: each with a one-line title and a summary of what it involves, and the one the agent recommends marked. Pick one, add a note for the agent if you want, or choose **Something else** and say what should happen in your own words. Nothing is pre-selected. **Send decision** records your answer on the timeline as a comment starting with `Decision:` and hands the ticket back to the agent, which resumes from your answer without asking again. A ticket that leaves **Blocked** for any other reason drops the question.

The same choice is offered everywhere the ticket reaches you:

* **AI chat and MCP** - `ticket_get` shows the pending question under `decision_request`, and the `ticket_decide` tool records your answer ("go with option A on T-8", or "tell T-8 to publish to both for a week"). Ankra records the answer as relayed by you and does not check that a person chose it, so ask the assistant to relay your decision rather than to pick one.
* **CLI** - `ankra tickets get T-8` prints the options with their keys and the recommendation; `ankra tickets decide T-8 --option a` picks one, `--answer "..."` answers with something else, and both together record the option with your note. `ankra tickets list` shows which tickets wait on **your decision**.
* **Slack and Teams** - the thread reply that announces the block carries the options as buttons (the recommended one highlighted), and so does the escalation card while the ticket still waits. Clicking an option records it as your decision. **Something else** asks you to reply in the thread starting with `Decision:` - that reply is recorded as the answer rather than as a plain comment.
* **API** - `POST /api/v1/org/ai-tickets/{ticket_id}/decision` with `option_key` (one of the offered keys) and/or `answer` (required when no option is chosen). A ticket that is not waiting on a choice answers `409`.

## Slack and Teams threads

Bind a tickets channel in the ticket desk settings and every ticket gets its own thread: timeline events post as replies, and replies in the thread land back on the ticket's timeline, waking the assignee. An escalation carries **Assign to me** and, while a plan awaits a verdict, **Approve plan** / **Request changes**; a ticket blocked on a choice carries its options as buttons and **Something else** (see [Answering a choice](#answering-a-choice)). Plan approval itself otherwise happens in the product. Configuration lives under **AI** → **Settings** → **Autonomy**; see [AI Autonomy](/platform/ai-autonomy).

### Project channels

A [project](/concepts/projects) can bind its own Slack channel and Teams conversation for board threads. A ticket of that project then opens its thread there, with the same approval, plan sign-off and decision buttons. The organisation's tickets channel is the fallback, per provider: a project that binds only a Slack channel still posts to the organisation's Teams conversation. Binding project channels needs organisation **admin**.

For example, with projects `core` and `tools`, bind `#ankra-core` to `core` and `#ankra-tools` to `tools`. Add one routing rule per project for its other notifications; see [one channel per project](/guides/notification-routing#example-one-channel-per-project).

| API | Does |
| - | - |
| `GET /api/v1/org/ai-tickets/settings/projects` | Lists the projects that bind channels of their own |
| `PUT /api/v1/org/ai-tickets/settings/projects/{project_id}` | Sets `slack_channel_id` and/or `teams_conversation_id`. A member left out is kept; `null` clears it, so that provider falls back to the organisation's channel |
| `DELETE /api/v1/org/ai-tickets/settings/projects/{project_id}` | Removes the project's channels |

> [!NOTE]
>
> The Ankra bot's answers in a project channel still come from your default project, and remediation approval cards still go to the organisation's Slack remediation destination.

## Mirroring tickets into your own tracker

A **sync connection** mirrors board tickets outbound to a Jira project, a Linear team, or your own webhook endpoint: the external issue is created once per ticket, and timeline events follow as comments. Filters decide which kinds and priorities travel. Sync is one-way - status changes arrive as comments, and nothing done in the tracker comes back to the board. Set them up under **AI** → **Settings** → **Connections**; see [Sync board tickets to Jira, Linear, or a webhook](/guides/ticket-sync).

## Working the board from your own tools

The board is not tied to the portal. Every surface works the same tickets with the same gates:

* **CLI** - [`ankra tickets`](/reference/cli/tickets) lists, reads, comments on, moves and decides tickets from a terminal.
* **Your own agent** - Claude Code, Cursor, Codex or an agent you wrote can pick up tickets over MCP, investigate, draft a plan and carry it out once you approve it. See [Work the AI board with your own agent](/guides/board-own-agent).
* **Slack and Teams** - the ticket's thread, described above.

## Views and navigation

The left rail has saved views - **All open**, **Needs a human**, **In flight**, **Gaps**, **Shipped**, **My tickets**, plus one per agent with open tickets. Toggle between **List** and **Kanban**; a **Live** pill shows while the board is streaming updates. From the keyboard: `j`/`k` to move, `enter` to open, `s` for status, `a` to assign, `/` to search.


# AI Code Review
Source: https://docs.ankra.ai/platform/ai-code-review

How Ankra's AI reviews pull requests - connecting GitHub, GitLab, or Bitbucket, what every switch in Source control & AI review does, and what the review posts.

Connect a source-control provider and Ankra's AI reviews your pull requests: it reads the diff, posts a verdict with its findings, pins each finding to the line it is about, and answers when somebody mentions it in a comment.

Everything is configured in one place: **AI** → **Settings** → **Connections** → **Source control & AI review**.

> [!NOTE]
>
> **Nothing runs until you switch it on.** Every capability on a new connection is off. Installing the GitHub App, connecting a GitLab token, or authorising a Bitbucket workspace gives Ankra access, and nothing more: no review is posted, no mention is answered, and no preview is deployed until an organisation admin turns the switch on for that connection or for a single repository.

***

## Connect a provider

Each provider appears as its own card. Connecting one is an organisation **admin** action.

> [tab] GitHub
>
> Press **Install GitHub App** and pick the organisation or user account, then the repositories Ankra may see. You land back on this page with the installation listed.
>
> One account can carry several installations, and each is configured separately. See the [GitHub integration](/integrations/github) for the permissions the App requests and how to change which repositories it covers.
>
> GitHub is the only provider that also offers [PR preview environments](/guides/pr-preview-environments).

> [tab] GitLab
>
> Paste an access token, optionally naming a self-managed instance URL. Ankra validates it, then shows the webhook URL and secret to register in GitLab by hand.
>
> The form asks for `read_api` and `read_repository`, which is what Ankra validates against and enough to *read* your merge requests. Posting the review is a write, so use a token with the `api` scope unless you deliberately want a read-only connection.
>
> Webhook registration is manual for GitLab and the secret is shown once. The [GitLab integration](/integrations/gitlab) walks through both.

> [tab] Bitbucket Cloud
>
> Press **Connect workspace** and authorise the Ankra OAuth consumer against your Bitbucket Cloud workspace. Webhooks are registered for you: switching AI review or mention replies on registers one on every repository it covers - every repository the credential can see, for the **All repositories** row - and a repository found later gets its own within minutes. Switching a lane off leaves the webhook in place.
>
> The webhooks carry pull request events only when the credential grants Bitbucket's `pullrequest` scope. A credential connected before Ankra asked for it has to be reconnected; until then GitOps sync works and reviews and mentions receive nothing. See the [Bitbucket Cloud integration](/integrations/bitbucket-cloud#granting-the-pull-request-permission) for the OAuth scopes, their purpose, and reconnecting.

A connected card shows one row per installation, credential, or workspace. Its one-line summary says which lanes the default row runs and how many repositories deviate from it, so a connection reading **Nothing enabled** is doing exactly that. Rows that do nothing open collapsed; press the row to expand it.

***

## AI mode: Ask or Agent

Every connection carries an **AI mode** that bounds what the AI may do when it is talked to from that repository. It is separate from the capability switches: the switches decide *whether* the AI answers, the mode decides *how far* the answer may go.

| Mode | What the AI may do |
| - | - |
| **Ask** (default) | Read-only. It investigates, explains, and can spin up throwaway workspaces or PR demos, but never changes existing infrastructure and never opens a pull request. |
| **Agent** | It may act. It opens fix pull requests on its own, and the pull request is the review gate. Other destructive changes still ask for confirmation. |

A connection in Agent mode is marked **Can act**. Automatic review events themselves stay read-only whatever the mode: a review comments, and a proposed fix arrives as a separate pull request you review like any other.

On GitLab and Bitbucket Cloud, Ankra cannot open a pull request, so an Agent-mode reply proposes the fix with a branch name and a commit message instead of offering one.

***

## The repository table

Each connection expands into one table of every capability, with two kinds of row.

* **All repositories** is the default row. It carries the connection-wide values, and every repository with no rule of its own follows it.
* **A repository rule** is one row per repository that should differ. Pick the repository (or type `<owner>/<repository>`) and press **Add rule**; the new row starts as a copy of the default row. Removing the rule reverts that repository to the default row.

Every control saves the moment you change it. There is no separate save button on this table.

To manage rules from the terminal or a script instead, an organisation admin can use the CLI:

```bash theme={null}
ankra org ai-review repos list
ankra org ai-review repos set my-org/my-repo --review --mentions --max-reviews-per-pr 3
ankra org ai-review repos unset my-org/my-repo
```

`set` changes only the switches you pass (`--review`, `--mentions`, `--previews`, `--model`, `--review-drafts`, `--max-reviews-per-pr`; turn one off with `=false`) and keeps the rest of the repository's rule, or the default row's values when the repository has no rule yet. The connection is found from the repository; when that is ambiguous, pass `--binding <provider>/<id>` as `list` shows it. `list --reachable` also lists the repositories each GitHub App installation can see, and `unset` removes the rule so the repository follows the default row again. Listing needs organisation membership; `set` and `unset` need an organisation admin.

Over the API, an organisation admin's [API token](/reference/tokens) can send `PUT /api/v1/org/ai-gateway/scm-bindings/{provider}/{binding_external_id}/repo-overrides` with `repo_full_name`, `ai_review`, `mention_replies` and `pr_previews` to add or change a rule, and `DELETE` on the same path with `?repo_full_name=<owner>/<repository>` to remove it. `GET /api/v1/org/ai-gateway/scm-bindings` lists each connection's `binding_external_id` and its current rules; the [API Reference](/api-reference/introduction) has the full request shape.

> [!NOTE]
>
> Rules are keyed by the repository path, lowercased. For GitLab, use the full project path including subgroups, up to 20 levels deep - for example `my-group/my-subgroup/my-project`.

### What each column means

| Column | What it does | Default |
| - | - | - |
| **AI review** | Reviews every pull or merge request when it is opened and on every push to it, and posts the findings. | Off |
| **Review drafts** | Also reviews draft pull requests automatically. When off, a draft is skipped until it is marked ready. | Off |
| **Auto reviews / PR** | Caps how many reviews one pull request receives over its whole life, requested ones included. Blank or `0` means no cap. See [The two budgets](#the-two-budgets). | 5 |
| **Mention replies** | Lets the AI answer when somebody writes `@ankraai` in a pull request comment. | Off |
| **PR previews** | Deploys every pull request to a throwaway [preview environment](/guides/pr-preview-environments) with its own URL. GitHub only. | Off |
| **Review model** | Which model the review runs on: an entry from your organisation's [model catalogue](/platform/ai-provider), or any exact OpenRouter model from the searchable list. A repository row set to **Inherit** follows the default row. | Your organisation's **AI code review** model |

When nothing picks a review model - not the repository's [Application AI settings](/platform/application-ai), not a repository rule, not the default row - the review runs on your organisation's **AI code review** function under [Models per function](/platform/ai-provider#models-per-function). Unless an admin changes it, that follows the **Think** tier: GLM 5.3 on the Ankra provider, or your own Think model when the organisation runs on its own key. Every pull request gets that model, whatever the size of its diff.

> [!TIP]
>
> The cap and the draft switch gate *automatic* reviews only. Asking for a review in a comment always runs one, though it still counts toward the cap - see [Talking to the review](#talking-to-the-review) below.

***

## Review instructions

**Customise review instructions**, at the top of the section, opens your organisation's own review prompt, with one field per connected installation. It is what the reviewer should keep in mind on this installation: which areas to weigh heavily, which conventions to enforce, what language to write in.

```text theme={null}
Write review comments in Swedish.
Pay extra attention to Terraform and RBAC changes.
Our Helm values must never hardcode an image tag.
```

* Up to 4,000 characters per installation. The counter turns red past the cap and **Save** stays disabled until you shorten it.
* The instructions steer what the review focuses on and how it is phrased. They cannot override the platform guardrails or the review format.
* Every repository on the installation inherits them. An application that overrode its own **Pull request** settings under [Application AI settings](/platform/application-ai) keeps the instructions set there instead, because overriding a lane pins the whole lane.
* Only organisation admins can change them.

***

## What a review posts

One comment per pull request, updated in place on every re-review, never a stream of new ones. Where a pipeline, a preview, or a promotion is also running, they share that comment as separate sections.

The review section is laid out like this:

```markdown theme={null}
## Ankra AI review

**Verdict: comments.**

<two to four sentences on the change as a whole>

### Findings

- **[high] <short title>** (`path/to/file.go:42`)
  <what is wrong, why it matters, and what to do instead>

---
_Reviewed commit abc1234. This review is read-only and advisory._
```

| Verdict | What it means |
| - | - |
| **looks good** | The change looks safe. |
| **no findings** | The review ran and surfaced nothing. |
| **comments** | Worth reading, but nothing the reviewer calls a probable defect. |
| **changes requested** | A probable bug or a security issue. |
| **unavailable** | The model's answer could not be read. Push again or mention Ankra to re-run it. |

Findings carry a severity of **high**, **medium**, or **low**, and a review keeps to the issues that matter - at most eight. A finding that names a line is also posted as a comment pinned to that line, so it is read where the decision is made. Each inline comment carries an invisible fingerprint of its file and title, so re-reviewing a pull request never restates a finding it has already pinned, even if the line has drifted or the wording changed.

### How the review reads a change

* **Machine-written files are dropped before the diff is measured.** Lockfiles, minified bundles, source maps, and generated protobuf never reach the model. Beyond keeping the cost down, this is what stops a large lockfile from crowding the real change out of the review. Set **Ignore paths** per repository under [Application AI settings](/platform/application-ai) to drop more.
* **Uncertain findings are settled, not guessed.** When a finding rests on something the diff does not show, Ankra reads the file and either restates the finding as a definite defect or drops it. Where that check cannot run, the finding is posted with its uncertainty visible.
* **A truncated answer says so.** If the model runs out of output budget mid-answer, what arrived is posted under an explicit incomplete-review notice rather than as a finished review that found nothing.
* **The diff is treated as text, never as instructions.** An instruction planted in a diff or a pull request description asking the reviewer to act, change role, or reveal data is refused.

***

## What the review reads beyond the diff

Before it answers, the review also reads the code a change can break outside its diff: other callers of what changed in the same repository, files in related repositories that still use a name the change removes, and the companion pull request that carries the other half of a cross-repository change. A `Depends-on:` line in the description declares which pull request has to merge first.

On GitHub, when the diff changes a container build file (`Dockerfile`, `Dockerfile.*`, `*.dockerfile`, `Containerfile` or `Containerfile.*`), the review also reads the workflows under `.github/workflows` that build an image, at the reviewed commit. It compares what they copy into the image and the environment variables they set with the changed file, and searches the code for the items the changed file no longer provides. The comparison is textual, so an item may still arrive another way, such as a volume or a download at startup.

How each of those works, how to relate two repositories, and what an empty result does and does not mean are covered in [Cross-repository review](/platform/ai-code-review-cross-repo).

***

## Talking to the review

Mention `@ankraai` in a pull request or merge request comment and the AI answers in the thread, with the change as context. This needs **Mention replies** on for that repository.

* **Ask a question.** "@ankraai does this handle the empty case?" gets an answer grounded in the diff, and a plain statement when the diff does not contain the answer.
* **Ask under an inline comment** and the question is read as being about that line.
* **Ask for a review.** A mention is a direct request from a human, so it is never filtered by draft state, branch scope, or either review budget. It runs even on a draft and even past the **Auto reviews / PR** cap, and it is counted against both budgets.

On GitHub and GitLab, Ankra reacts to your comment with 👀 as soon as it picks the mention up, so you can tell a slow review from one that never started. Bitbucket Cloud has no comment reactions, so there the reply itself is the first sign; it is posted as a reply to your comment.

> [!NOTE]
>
> Only `@ankraai` summons the review. It is matched as a whole word, so `@ankraai-bot` and an address like `someone@ankraai.example.com` are ignored.

***

## When a review does not run

A skipped review is normal and costs nothing. Ankra decides before any model call, in the order below, and stops at the first reason that applies. On GitHub the reason is written to the **Ankra AI review** check run on that commit: its title reads **Review skipped** followed by the reason, and its summary says what lifts it. The check run is the one place the decision is recorded.

| Check-run title | Why | What to change |
| - | - | - |
| **Review skipped - AI review is switched off for this repository** | **AI review** is off on the default row and on any rule covering the repository. | Turn the switch on, on the default row or on that repository's rule. |
| **Review skipped - draft pull request** | The pull request is a draft and **Review drafts** is off. | Turn **Review drafts** on, mark the pull request ready, or mention `@ankraai`. |
| **Review skipped - target branch out of scope** | The pull-request lane's branch patterns exclude the target branch. | Widen **Target branches** under [Application AI settings](/platform/application-ai), or mention `@ankraai`. |
| **Review skipped - head already reviewed** | A review of exactly this commit is already on the pull request. | Push a new commit. Nothing was lost. |
| **Review skipped - superseded by a newer push** | A later push replaced this commit before its review started. | Nothing. The newest head gets the review. |
| **Review skipped - daily review budget reached** | The repository has used its **Max runs per day** since midnight UTC, across every pull request. | Raise or clear **Max runs per day** under [Application AI settings](/platform/application-ai), or mention `@ankraai`. |
| **Review skipped - per-pull-request review budget reached** | This pull request has used its **Auto reviews / PR** allowance over its lifetime. | Raise or clear **Auto reviews / PR** on the repository rules, or mention `@ankraai`. |

A skipped head is not retried. Nothing on Ankra's side re-queues a commit it declined; the next push is a new head, judged afresh against the same switches and counts. So once a pull request is over its budget, every later push to it is skipped until the budget changes.

### The two budgets

Two counters can decline a review, and they are set in different places.

| | **Auto reviews / PR** | **Max runs per day** |
| - | - | - |
| Counts | Reviews of one pull request over its whole life, keyed by the pull request number. A re-cut pull request starts at zero. | Reviews of the whole repository since midnight UTC, across every pull request. A brand-new pull request can be declined on its first push. |
| Default | 5 | No cap |
| No cap | Blank or `0` | Blank or `0` |
| Where | The repository rules on this page, per repository or on the default row. Organisation admins only. | The **Pull request review** card under [Application AI settings](/platform/application-ai). |
| Applies | From the next push. | From the next push. |

The daily budget is checked first, so a repository over both reads **daily review budget reached** on its check run. Both counters include reviews somebody asked for with `@ankraai`: a requested review runs past either budget, and it is still counted against both.

A completed review of a commit replaces any earlier **Review skipped** on that commit's check run, so a review requested with `@ankraai` clears a check that a budget had concluded.

***

## Per-application overrides

The table on this page sets your organisation's defaults. An [application](/concepts/applications) connected to a repository can override them on its own **Ankra AI** panel, which also exposes branch patterns, ignore paths, daily budgets, input-character budgets, and the deeper lanes. Both surfaces read the same stored settings, so they never disagree. See [Application AI settings](/platform/application-ai).

***

## Cost

A review is a model completion, billed to your organisation like any other AI usage. Four things keep it bounded, and all four are yours to set:

1. **Every lane is off until you turn it on**, per connection or per repository.
2. **Auto reviews / PR** caps the reviews one pull request can accumulate.
3. **Review model** picks what a review costs. The picker shows each model's context window and price. With nothing picked, the organisation's **AI code review** model applies.
4. **Ignore paths** and the input-character budget bound how much of a diff one review reads.

Reviews already spent appear in your AI usage - see [Models and Cost](/platform/ai-provider#usage-and-the-free-allowance).

***

## Permissions

Connecting a provider, disconnecting one, changing any switch, and editing the review instructions all require organisation **admin**. Members see the connections and their current settings, and the controls are disabled with the reason.

***

## Troubleshooting

| Symptom | What to check |
| - | - |
| No review appears on a new pull request | Is **AI review** on for that repository - the default row *and* any rule covering it? A rule wins over the default row. Then read the **Ankra AI review** check run on the commit: its title names the [skip reason](#when-a-review-does-not-run). |
| The connection card says **Nothing enabled** | Every lane is off on the default row and on every rule. Nothing will run for this installation until one is switched on. |
| A repository is missing from the add-rule picker | The picker lists what the installation can actually see. For GitHub, add the repository to the App installation; for other providers, type the path by hand. |
| Reviews run but mentions go unanswered | **Mention replies** is a separate switch from **AI review**, and mentions must spell `@ankraai`. |
| The review says **Verdict: unavailable** | The model's answer could not be read. Push a new commit or mention `@ankraai` to re-run it. A recurring one usually means the selected review model's output budget is too small; pick a larger model. |
| The review says it is incomplete | Same cause, caught mid-answer: the model stopped at its output ceiling. Re-run it, and consider a model with a larger output budget. |
| Findings repeat on every push | They should not: inline findings are fingerprinted and deduped. The summary comment does restate every finding in full by design, so a reader who only opens the conversation tab still sees the whole review. |
| GitLab reviews stop after a secret rotation | Regenerating the webhook secret invalidates the old one immediately. Update the hook in GitLab with the new secret. |
| Bitbucket pushes sync, but no review or mention reply ever runs | The credential does not grant Bitbucket's `pullrequest` scope, so its webhooks carry pushes only. Reconnect it - see [Granting the pull request permission](/integrations/bitbucket-cloud#granting-the-pull-request-permission). |

***

## Related

* [AI Connections](/platform/ai-connections) - every integration the AI communicates through
* [Cross-repository review](/platform/ai-code-review-cross-repo) - what the review reads outside the diff, related repositories, and merge order
* [Application AI settings](/platform/application-ai) - per-repository lanes, branch scope, ignore paths, and budgets
* [PR preview environments](/guides/pr-preview-environments) - what the **PR previews** switch deploys
* [GitHub](/integrations/github), [GitLab](/integrations/gitlab), [Bitbucket Cloud](/integrations/bitbucket-cloud) - connecting each provider
* [AI Skills](/platform/ai-skills) - the conventions the org skills review checks a change against
* [`ankra application pull-request-reviews`](/reference/cli/application) - read posted reviews from the CLI


# Cross-Repository Review
Source: https://docs.ankra.ai/platform/ai-code-review-cross-repo

How Ankra's AI code review reads the code a pull request can break outside its own diff - callers, related repositories, companion pull requests - and how to declare merge order.

A diff on its own hides the most valuable class of finding: *you changed this, and the code that depends on it is not in front of you*. The [AI code review](/platform/ai-code-review) pulls that code in before it answers, so it can raise the finding instead of leaving it to whoever greps for it later.

This page covers what the review reads beyond the diff, how to tell it which repositories belong together, and how to declare which pull request has to merge first.

## Callers in the same repository

For each declaration the diff changes, Ankra searches the repository for the other places that name appears and reads the best candidates into the prompt, at the reviewed commit. That is what lets a review say "three of this function's five callers are in files this pull request does not touch" - a finding the diff alone cannot support.

## Repositories deployed alongside this one

A pull request can be correct, green, and still break a different repository: it removes a route, and the client that calls it lives elsewhere with its own pipeline that has never heard of this change. Neither side disagrees until the deploy.

So for names this diff **removes**, and for contracts it **changes**, Ankra searches the repositories your organisation relates to this one and shows the review any file that still refers to them. A removal is reported as a possible breaking change on the line that does the removing; a changed contract is reported only where the file shows a real dependency on what changed.

| | |
| - | - |
| **Which repositories** | Three sources, combined. Two need no configuration at all: applications Ankra installs on the same cluster, and repositories tagged on that cluster under **Settings** → **AI Context**. The third you state yourself - see [Relating two repositories directly](#relating-two-repositories-directly) below. |
| **What triggers it** | A **removal**: a route path, a serialised field name or a constant's quoted value that a removed line carried and no added line carries. A **changed contract**: a serialised field whose declaration line changed while its name survived (a type, a nullability, an `omitempty`), or an exported declaration whose line changed (a function gaining a parameter, a version constant moving). An added route or a new field breaks nobody, so an additive change consults nothing and costs nothing, and a line that merely moved or was re-indented is not a change. Removals are searched first, up to four terms per review. |
| **Scope** | Up to five related repositories per review. GitHub only, code search being the mechanism. |
| **What is read** | Whole files at a named commit of the repository's **default branch**, quoted into the prompt as untrusted material under review - never as instructions, exactly like the diff. Code search indexes default branches only, so this pass alone cannot see a fix that is still on a branch; that is what [the other half of the change](#the-other-half-of-the-change) below is for. When the repository has an open companion pull request, the same file is read on that branch too, and the review is told whether the name survives there. |

> [!NOTE]
>
> The repository set is read from your organisation's own rows, never from the model and never from the text of the pull request. A pull request cannot name a repository to have it read, and a search result pointing outside the set is discarded.

> [!WARNING]
>
> **Silence here is not an all-clear.** The search is best effort. A rate limit, a failed request, a provider without code search, or an organisation with nothing co-installed all produce **no section at all** rather than one reading "nothing else uses this" - because a review that conflated those would tell you a removal is safe on the strength of a request that failed. Absence of a cross-repository finding is not evidence that nothing is affected.

## The other half of the change

A cross-repository change is almost never one pull request. The API removes a route in one repository and the client stops calling it in another, and the second half sits on a branch until the first has landed. Code search cannot see that branch, so on its own the pass above would say "the client still calls this" about a repository whose fix is already open.

So the review also reads the **companion pull requests** of the one under review, and shows each as it stands on its own branch:

| | |
| - | - |
| **Declared** | A line in this pull request's description reading `Depends-on: owner/repository#number` (or the full pull request URL). It is the same line [merge order](#declaring-merge-order) is declared with, read with the same grammar, so the review and the merge hold can never disagree about what it names. |
| **Linked** | A pull request in a related repository whose description or a comment links this one. GitHub records the link on this pull request's timeline, and the review reads it from there - so pasting the other half's URL into the description is enough. |
| **What is shown** | Up to three companions: state (open, merged, or closed without merging), whether it is a draft, its head commit, its base branch, and its diff, bounded, as untrusted material like everything else in the prompt. A companion closed without merging is shown by state alone, because it changes nothing. |
| **Which repositories** | Only the reviewed repository itself and the related set above. A declaration or a link naming any other repository is not read: a pull request may choose which pull request in the set the review looks at, never widen the set. |
| **On the companion's branch** | Where the pass above found a file on a related repository's default branch, and that repository has an open companion, the review reads the same file at the companion's head and states what it found: the file still mentions the name, no longer mentions it, or no longer exists there. That verdict is computed, not inferred. |

The review uses this to say which side has to merge first, and to stop asking you to confirm what the platform can read. A mention reply (`@ankraai`) sees the same companions, so "the other half is in that pull request" is checked rather than taken on your word.

> [!NOTE]
>
> A companion absent from the review is not evidence that none exists. Only declared lines and links GitHub recorded are read, up to three, and a companion that could not be read is left out rather than shown as unchanged.

## Relating two repositories directly

The two automatic sources only know what is deployed on the same cluster. A client and the API it calls, a shared library, or a client that runs outside Ankra have no cluster in common, so state those relationships directly: **AI** → **Settings** → **Connections** → **Source control & AI review**, open a GitHub connection, and use **Related repositories** at the bottom of its panel. This adds to the automatic sources; it does not replace them.

**1. Pick both repositories**

Both are chosen from drop-downs listing the repositories that GitHub App installation can reach. The review reads them with that installation's token, so a repository it cannot reach would contribute nothing and is refused. If one is missing, add it to the GitHub App installation first.

**2. Relate them**

The pair is saved immediately and appears in the list above, shown as `repo-a ↔ repo-b`.

| | |
| - | - |
| **Direction** | None. Reviews of either repository consider the other, and adding a pair you already have in the other order changes nothing. |
| **Where it applies** | The GitHub App installation you added it under. Two installations on one organisation keep separate lists. |
| **Who can change it** | Organisation admins. Everyone else sees the list read-only. |
| **Removing one** | The **✕** on the row. Removing a relationship stops future reviews consulting it; it changes nothing about reviews already posted. |

## Related repositories from the CLI or MCP

The list is not portal-only, and both other surfaces hold the same rules: organisation admin, one installation, both repositories reachable by it.

```bash theme={null}
ankra org ai-review related-repos list
ankra org ai-review related-repos add my-org/portal my-org/api
ankra org ai-review related-repos remove my-org/portal my-org/api
```

The CLI finds the installation from your GitHub App credential, so you name one only when the organisation has several: `--credential github-app-my-org`. `remove` also takes a relationship's ID from `list`, and it removes the pair whichever order it was stated in.

Over [MCP](/platform/mcp-tools) the three are `list_related_repositories`, `relate_repositories` and `unrelate_repositories`. They are addressed by the GitHub App installation's numeric id, which `list_credentials` reports for every GitHub App credential. The two writes need the `mcp:write` scope **and** an organisation admin's token: the MCP surface does not carry the chat lanes' permission gate, so the tools check admin themselves.

## Declaring merge order

Where a removal or a contract change is genuinely breaking, the risk is often the deploy *sequence* rather than the change, and the review will suggest declaring the order with a line in the pull request description:

```text theme={null}
Depends-on: my-org/my-api#1722
```

Ankra reads the line only when it starts a line, so ordinary prose mentioning "depends on" cannot hold anything. It accepts the short `owner/repository#number` form or a full pull request URL, up to five per pull request. Order is declared rather than inferred on purpose: inferring which side is the producer means guessing whether the change is additive or breaking, a judgement the author has already made, and two halves each waiting for the other is a deadlock.

The line does two things. The review reads it on every turn and shows the declared pull request as [the other half of the change](#the-other-half-of-the-change), so the finding that suggested it is answered by the next review rather than by you. And merge-when-green holds this merge until the declared pull request has merged.

> [!NOTE]
>
> **The merge hold needs Merge when green on the installation**, off by default and switched on next to the AI mode control on the installation's row, or over the API - see [Merge when green](/integrations/github#merge-when-green). With it off, the line holds nothing and you sequence the merges yourself; the review still reads it either way.

## Next

Switch the review on and choose what it posts in [AI code review](/platform/ai-code-review).


# AI Connections
Source: https://docs.ankra.ai/platform/ai-connections

Where Ankra's AI meets the outside world - connecting Slack and Microsoft Teams, Git providers, MCP tool servers, ticket sync, webhook destinations, and notification routes.

You want to ask Ankra's AI about a failing deploy from the chat tool your team already uses, and have its approvals and findings reach people there. The **Connections** section under **AI** → **Settings** → **Connections** gathers every integration the AI communicates through, in five groups.

## Chat & Notifications

* **Slack** - install the Ankra app into your workspace. See [Connecting Slack](#connecting-slack) below.
* **Microsoft Teams** - connect your tenant and add the Ankra bot to the teams that should reach the AI. See [Connecting Microsoft Teams](#connecting-microsoft-teams) below.

Each connection carries its own **AI mode** - what the AI may do when talked to from that surface. A Slack or Teams connection with no mode of its own follows the organisation-wide **Default AI mode** on the **Workspaces** settings page, which is **Ask** unless an admin changes it. Source-control connections do not follow it: they start with every capability off, see [AI code review](/platform/ai-code-review#ai-mode-ask-or-agent).

### Connecting Slack

Slack takes one Ankra organisation admin to install the app, then each person links their own Ankra account the first time they use it.

**1. An Ankra organisation admin installs the app**

Under **AI** → **Settings** → **Connections** → **Chat & notifications**, press **Add to Slack** on the **Slack** card (**Add workspace** once one is connected). Slack asks you to authorise the app for your workspace and sends you back to Ankra, which confirms **Slack workspace connected**.

The install link lasts 10 minutes from the moment you press **Add to Slack**. Start the install from Ankra, not from Slack: that is what tells Ankra which organisation's clusters the workspace may see. One Slack workspace links to one Ankra organisation, and installing it from a different organisation revokes every account link in it.

**2. Each person links their own Ankra account**

The first time someone mentions **@Ankra**, sends it a direct message, runs `/ankra`, or presses one of its buttons, Ankra replies to them alone with **Connect Ankra account**. They sign in with their normal Ankra login and confirm the Slack user and workspace shown, and Ankra then answers the question they asked.

This is per person on purpose: the bot answers with *that* person's Ankra permissions, and their name - never the bot's - is what lands in the audit log.

**3. Set the AI mode**

Each workspace row carries an **AI mode** control. **Ask** is read-only, plus low-risk creations. **Agent** lets the AI act, and marks the row **Can act**. A workspace with no mode of its own follows the organisation's **Default AI mode** on the **Workspaces** settings page, which is **Ask** unless an admin changes it. In Ask mode, the buttons that change something - acknowledging an alert, approving a remediation, working a ticket - are refused.

**4. Optionally, choose a home channel**

See [Ankra's home channel](#ankras-home-channel) below.

The app requests the Slack permissions it needs to answer mentions and direct messages, post replies and cards, run `/ankra`, look up the Slack user who asks, and list channels for the home channel picker. It receives messages that mention it, direct messages, and its App Home - it does not receive the rest of a channel. When it is mentioned inside an existing thread, it reads that thread's replies as context.

### What the bot can do in Slack

* **Ask it anything** - mention **@Ankra** in a channel, message it directly, or open it in Slack's assistant pane. Say `use cluster <name>` to scope the thread to one cluster. An answer in a channel is visible to that channel.
* **`/ankra`** - on its own it links your account. `/ankra status` shows whether you are linked, `/ankra logout` disconnects you, and `/ankra help` shows what it can do.
* **Act on alerts** - alert cards carry **Acknowledge** and **Snooze 1h** buttons, and AI remediation approvals carry **Approve** and **Deny** (**Approve all** and **Deny all** for a batch). A decided card is replaced by its outcome.
* **Approve the AI's writes** - when a turn proposes a change that needs confirmation, the bot posts a **Confirmation needed** card with **Confirm** and **Deny**. Only the person who asked can decide it, and if the cluster changed in the meantime the card shows what moved and offers **Confirm anyway**.
* **Work tickets from the thread** - an escalated ticket's thread carries **Assign to me** and, while a plan is awaiting a verdict, **Approve plan** and **Request changes**. A reply in a ticket's thread is added to the ticket as a comment.

Every button runs as *your* Ankra user through your own linked account, so your role decides what it may do and the audit log records your name.

### Ankra's home channel

The home channel is the Slack channel Ankra posts to when something important happens and no [notification route](/guides/notification-routing) matches: failures, agents going offline, security findings. Only critical and warning notifications fall back to it.

Set it under **AI** → **Settings** → **Workspaces**, on the **Ankra's home** card: pick a channel and press **Save home channel**, or **Clear** to remove it. The card needs a connected Slack workspace, and changing it needs organisation **admin**; everyone else sees the current channel.

### Disconnecting Slack

* **For the whole workspace** - an Ankra organisation admin presses **Disconnect** on the workspace row. Every linked user in that workspace loses their connection and stops receiving notifications. Uninstalling the app from Slack has the same effect.
* **For yourself** - run `/ankra logout`, or press **Disconnect** in the app's Home tab in Slack.

### If Slack does not work

| What you see | What it means |
| - | - |
| The bot never answers a mention | Run `/ankra status`. If it says the workspace is not connected to an Ankra organisation yet, an Ankra organisation admin needs to press **Add to Slack** from Ankra. |
| **Install link no longer valid** after authorising | The install took longer than 10 minutes. Press **Add to Slack** in Ankra again - you do not need to remove the app from Slack first. |
| **Almost there** after authorising | The install did not start from Ankra, or linking it to your organisation failed. Retry **Add to Slack** from Ankra. |
| **Link expired** when connecting your account | The connect link is short-lived. Mention the bot again for a fresh one. |
| **Your Ankra connection has expired** | Run `/ankra` to link your account again. |
| **Alert actions are disabled for this workspace** (or AI actions, or ticket actions) | The workspace's AI mode is **Ask**, which refuses buttons that change something. An admin can switch it to **Agent**. |
| **Your Ankra role cannot confirm AI actions in this organisation** | Your Ankra role does not allow the change. Ask an admin, or someone whose role does, to confirm it. |
| The home channel picker says some channels are not listed | The app is missing a Slack permission. Reinstall it from Ankra with **Add to Slack**. |

### Connecting Microsoft Teams

Teams setup involves up to three people. Agree who is who before you start: most delays come from one person waiting on another without knowing it.

| Who | What they do | How often | Ankra login |
| - | - | - | - |
| **Microsoft 365 / Teams administrator** | Allows Ankra AI in your tenant, only needed if it restricts Store apps or requires approval | Once | Not needed |
| **Ankra organisation admin** | Connects the tenant to your Ankra organisation | Once per tenant | Admin role |
| **Everyone else** | Links their own Ankra account | Once per person | Any role |

> [!TIP]
>
> If your tenant restricts Teams Store apps and your Teams administrator is someone else, send them the [ready-made message](#what-to-send-your-teams-administrator) below. It covers everything they need to do.

**1. Install Ankra AI from the Microsoft Teams Store**

Ankra AI is published on the [Microsoft Teams Store](https://marketplace.microsoft.com/en-us/product/teams-app/WA200012870):

1. In Teams, open **Apps**.
2. Search for **Ankra AI**.
3. Press **Add**.

In the Ankra portal, **AI** → **Settings** → **Connections** → **Microsoft Teams** has **Get it from the Teams Store** and **Open in Teams** buttons that take you to the same listing.

> [!NOTE]
>
> If **Ankra AI** does not appear in the search, or Teams says it needs approval, your tenant restricts Store apps. A Teams administrator allows it once in the **Teams admin center** under **Teams apps** → **Manage apps**: search for **Ankra AI** and press **Allow**. Under **Teams apps** → **Permission policies**, they also check that the people who should use it are allowed to. The [ready-made message](#what-to-send-your-teams-administrator) covers both steps.

**2. An Ankra organisation admin connects the tenant**

1. In Teams, add **Ankra AI** to a team, group chat, or personal chat.
2. The bot sends you a welcome card. Press **Connect to Ankra**.
3. The Ankra portal opens with the claim code already filled in. Press **Connect**.

That's it. This tells Ankra which organisation's clusters this Teams tenant may see.

Good to know:

* **The card arrives in a personal chat.** Whoever redeems the claim code connects the whole tenant, so the code is never posted in a channel. If you add the bot to a team or group chat, it messages you privately and tells the channel who got the code. Anyone else can get it by opening a personal chat with **Ankra AI** and saying hi.
* **Pasting the code by hand also works.** The card shows the code. In the portal, open **AI** → **Settings** → **Connections** → **Microsoft Teams**, press **I already have a claim code**, and paste it.
* **The code lasts up to 24 hours.** Asking the bot again returns the same code until it is close to expiring, so a colleague talking to the bot won't invalidate yours.
* **One tenant, one organisation.** A Microsoft tenant connects to exactly one Ankra organisation, while one organisation can connect several tenants. If a tenant was connected to the wrong organisation, disconnect it there and message the bot for a new code.

**3. Each person links their own Ankra account**

Message the bot, or mention **@Ankra AI** in a channel, then press **Connect Ankra account** and sign in with your normal Ankra login. You only do this once.

This is per person on purpose: the bot answers with *your* Ankra permissions, and your name, never the bot's, is what appears in the audit log.

**4. Optionally, set the AI mode**

The Teams card carries an **AI mode** control. **Ask** is read-only, and **Agent** lets the AI act. With no mode of its own, the tenant follows the organisation's **Default AI mode**, which is **Ask** unless an admin changes it.

**5. Optionally, send alerts to a Teams channel**

Once the bot is in a team, alert **Destinations** let you pick a *Team / Channel*, the same way as for Slack. The bot posts the alert card itself, so you don't need a Power Automate URL. Add the bot to every team whose channels should receive alerts.

### What to send your Teams administrator

Copy this as is:

```text theme={null}
We are rolling out Ankra AI, a Kubernetes operations assistant, in Microsoft Teams.
It is a bot-only app on the Microsoft Teams Store: no tab, no Graph API permissions,
and nothing to consent to.

Store listing:
  https://marketplace.microsoft.com/en-us/product/teams-app/WA200012870

Please allow it in our tenant:

  1. Teams admin center -> Teams apps -> Manage apps -> search "Ankra AI" -> Allow
  2. Teams apps -> Permission policies -> make sure the policy covering our team allows it

If our tenant blocks all Store apps, upload the app package instead:
  Download https://ankra-gateway.ankra.app/teams/app-package  (a small .zip - no login needed)
  Teams admin center -> Teams apps -> Manage apps -> Upload new app -> select the .zip

If you are asked:
  - It requests no Microsoft Graph permissions, so there is no admin consent prompt.
  - It cannot read channel history. It only receives messages that @mention it,
    replies in a thread it is already part of, and direct messages sent to it.
  - It opens no inbound connection to our network. It only talks outbound to
    Microsoft's Bot Framework.
  - To remove it later: Manage apps -> Ankra AI -> Block.
```

> [!NOTE]
>
> The app package is only for tenants that block Store apps. It installs the same Ankra AI bot as the Store listing, and the portal still offers it as a fallback under **AI** → **Settings** → **Connections** → **Microsoft Teams**.

### What your Teams administrator will want to know

> [accordion] Does it need admin consent or Graph permissions?
>
> No. Ankra AI is a bot-only app. Its manifest declares no `webApplicationInfo`, no resource-specific consent (RSC), and no device permissions, so there is no Microsoft Graph scope and no consent prompt. Allowing it in **Manage apps** and in a permission policy is the whole approval.

> [accordion] Can it read our channel history?
>
> No. The bot only receives messages addressed to it: an `@Ankra AI` mention, a reply in a thread it is already part of, or a direct message. It does not request the resource-specific consent that would grant access to channel messages.

> [accordion] What data leaves Microsoft Teams?
>
> Only the messages people send to the bot, plus the IDs needed to reply (tenant, conversation and user). These reach the Ankra platform so the assistant can answer, and the conversation is stored against your Ankra organisation. Nothing else is read or exported.

> [accordion] Does it need a firewall or network change?
>
> No. The bot runs in Ankra's platform and talks outbound to Microsoft's Bot Framework, which relays to Teams. Nothing connects inbound to your network, and there is no IP range to allow-list.

> [accordion] Who does it act as?
>
> The person using it. Every answer and button runs with that person's own Ankra permissions and is recorded under their name in your organisation's audit log. Someone who has not linked an account gets a connect prompt instead of an answer. An Ankra organisation admin can also limit what the integration may do with the **AI mode** control on the Teams card (*Ask* for read-only, *Agent* to let it act).

> [accordion] How do we remove it?
>
> In the Teams admin center: **Manage apps** → **Ankra AI** → **Block**. If you uploaded the app package instead of using the Store, delete it from your org's catalog. In Ankra: **AI** → **Settings** → **Connections** → **Microsoft Teams** → **Disconnect**, which revokes every linked user's access for that tenant.

### What the bot can do in Teams

The same as [in Slack](#what-the-bot-can-do-in-slack):

* Answer questions. Say `use cluster <name>` to scope a conversation to one cluster.
* Act on alert cards.
* Confirm or deny the AI's proposed changes.
* Work tickets from their thread.

Every button runs as your own linked Ankra user. Instead of `/ankra`, type `help`, `status` or `logout` to the bot.

### If something does not work

| What you see | What to do |
| - | - |
| **Ankra AI** is missing from the Teams app search, or needs approval | Your tenant restricts Store apps. A Teams administrator allows it under **Teams apps** → **Manage apps** (see [what to send them](#what-to-send-your-teams-administrator)). |
| **Invalid Bot** when adding the app | The app is fine, but the bot registration behind it can't be reached. Contact Ankra support: this can't be fixed from your tenant. |
| The bot doesn't answer | Mention **@Ankra AI**. In a channel, it ignores plain messages unless they reply in a thread it is already part of. |
| **This Teams workspace is not linked to an Ankra organisation yet** | The tenant isn't connected. An Ankra organisation admin needs to [connect it](#connecting-microsoft-teams) with the claim code from the welcome card. |
| The channel says the setup code was sent privately | Check your personal chats for one from **Ankra AI**. If the channel names someone else, open a personal chat with **Ankra AI** and say hi to get the code yourself. |
| The claim code is rejected | It has expired (codes last up to 24 hours, and the card shows when) or another organisation already used it. Message the bot for a new one. |
| You get a connect prompt every time | Your own account isn't linked yet. Press **Connect Ankra account** and sign in once. |

> [!NOTE]
>
> To post alert cards to Teams **without** the bot, use a webhook destination with the Adaptive Card template instead. See [Microsoft Teams webhooks](/guides/webhooks#microsoft-teams).

## Source Control & AI Review

Connect [GitHub](/integrations/github) (via the Ankra GitHub App), [GitLab](/integrations/gitlab), or [Bitbucket Cloud](/integrations/bitbucket-cloud) so the AI can read repositories, review pull requests, answer `@ankraai` mentions, and power [PR preview environments](/guides/pr-preview-environments).

Every capability is off on a new connection: connecting a provider grants access and nothing else. What each switch does, how per-repository rules override the connection-wide defaults, what a review posts, and when one is skipped are all covered in [AI code review](/platform/ai-code-review).

## MCP Tool Servers

Register your own MCP servers to give Ankra's agent runs extra tools. Each server exposes its tools after a health probe, and every tool needs an explicit **role grant** before runs can call it - registering a server grants nothing by itself. The same steps are available as tools in the [Agent MCP Tool Servers](/platform/mcp-tools#agent-mcp-tool-servers) reference.

This is the opposite direction from Ankra's own [MCP Server](/platform/mcp-server), which lets your MCP client - Claude, Cursor, or your own agent - call Ankra. To have your own agent pick up and work board tickets, see [Work the AI board with your own agent](/guides/board-own-agent).

## Ticket Sync

Mirror [AI board](/platform/ai-board) tickets into a Jira project, a Linear team, or your own webhook endpoint. The external issue is created once per ticket and timeline events follow as comments. Each connection carries its own filters for ticket kind, minimum priority, and whether timeline events are relayed at all. Sync is one-way: edits and comments made in the tracker do not come back to the board.

See [Sync board tickets to Jira, Linear, or a webhook](/guides/ticket-sync) for where each provider value comes from, the webhook payload contract, and troubleshooting.

## Outbound Delivery

* **Destinations** - webhook endpoints that receive platform events, with ready-made templates for Slack, Teams, Discord, and PagerDuty, or a custom JSON payload template. Send a test delivery from the destination's menu to verify the wiring. See the [webhook guide](/guides/webhooks) for payloads and templates.
* **Notification routes** - rules that decide which events (alerts, security findings, agent status, GitOps) go to which destination. Events with no matching route fall back to the home channel. See [Notification routing](/guides/notification-routing) for matching, ordering, and the one-delivery-per-destination guarantee.

### A Slack or Teams channel per project

A route in a [project](/concepts/projects) delivers only that project's notifications; an organisation-wide route delivers every project's and the organisation's own. With projects `core` and `tools` and channels `#ankra-core` and `#ankra-tools`:

1. Create one catch-all route in each project, **This project**, sending to that project's channel.
2. Bind the same channels under the AI board's [Project channels](/platform/ai-board#project-channels), so ticket threads with their approval, plan sign-off and decision buttons land there too.

The organisation's channel stays the fallback for anything not tied to a project. The walkthrough is [one channel per project](/guides/notification-routing#example-one-channel-per-project).

> [!NOTE]
>
> The bot's answers in a project channel still come from your default project, and remediation approval cards still go to the organisation's Slack remediation destination.

## Permissions

Connecting, disconnecting, and changing destinations, routes, or ticket sync connections requires organisation **admin**. Members can see the ticket sync connection list, but never the credentials, which are write-only and stored in Vault.


# Guided Setup
Source: https://docs.ankra.ai/platform/ai-guided-setup

The checklist that wires up Ankra's AI for an organisation - model, guardrails, connections, who works the board, who reviews its plans, proactive monitoring, and launch.

**Guided setup** walks an organisation admin from nothing to a working AI team. Open it from **AI** → **Home** - the first-run hero links to it, and until setup is complete the page footer shows how far along you are.

Progress is read live from your organisation's settings, not stored per user: a step is complete because the thing it configures is actually configured, any admin sees the same state, and every step can be redone later. Members who are not admins get a read-only tour of the same checklist.

## The steps

The checklist has seven steps, or five when [AI Agents](/platform/ai-agents) is switched off for your organisation - the two board steps need it.

**1. Connect a model**

Pick the LLM the AI runs on - the Ankra default works out of the box, or bring your own key. Complete once an active provider is configured. See [Models and Cost](/platform/ai-provider) and [Use your own OpenRouter API key](/guides/openrouter-api-key).

**2. Autonomy & guardrails**

Decide how far the AI may go on its own when an alert fires. Complete once the auto-remediation policy is enabled. See [AI Autonomy](/platform/ai-autonomy).

**3. Connections**

Bind Slack or a delivery webhook so approvals and findings reach your team. Complete once Slack is connected or at least one delivery webhook is enabled. See [AI Connections](/platform/ai-connections).

**4. Staff the board**

Designate the agent that works tickets. Nothing is staffed by default: until an agent is designated, every ticket the AI files is escalated straight to a person, and no agent works it. Complete once at least one enabled agent that can act is designated as a board worker. See [AI Autonomy](/platform/ai-autonomy#board-staffing).

**5. Plan review**

Bind the agent that reviews drafted plans, or turn the review requirement off. Out of the box plans require a review and no reviewer is bound, so every drafted plan waits in review. Complete once a reviewer is bound or the requirement is off.

**6. Proactive insights**

Let the AI scan clusters continuously and raise findings before they page you - a single toggle, right in the checklist. See [AI Insights](/platform/ai-insights).

**7. Review & launch**

A recap of every step, then straight to AI Home or the Inbox. You can launch with steps incomplete; the AI just does less on its own.

Each step links to the settings page that owns it, and expands in place with a **Configure** or **Redo** action - the checklist is a launcher, the settings pages stay the source of truth.

## Recipes

Below the steps, admins get shortcuts for the most common next moves: teach the AI your runbooks, add an integration tool, set up a nightly cluster health agent, or build an on-alert workflow in [Automations](/platform/ai-automations). The last two appear only when AI Agents and Automations are enabled for your organisation.

## Next

Once setup is done, read [What it can change without asking](/platform/ai-overview#what-it-can-change-without-asking) to check the limits you have set.


# AI Insights
Source: https://docs.ankra.ai/platform/ai-insights

Proactive AI cluster health analysis with root cause and remediation, and the AI analysis attached to every firing alert.

Most cluster problems start small - a pod restarting, a node filling up - and are noticed only when they page someone. AI Insights scans your clusters on a schedule, spots those problems early, and gives each one a root cause and a fix. When an alert does fire, the same kind of analysis is attached to the firing, so the first person to look starts with an explanation instead of a blank log view.

> [!NOTE]
>
> Proactive AI Insights is switched on from **AI** → **Settings** → **Autonomy**. Until it is on, a cluster's **AI Insights** page reads **AI Insights generation is disabled** and no new issues are detected. The [alert-triggered analysis](#alert-triggered-analysis) below works without it.

Each insight carries:

* **Root cause analysis** - what went wrong and why.
* **Remediation commands** - `kubectl` commands you can copy.
* **Platform actions** - fixes through Ankra, such as a Stack change or an add-on configuration change.
* **Conversation starters** - prompts that open the [AI Assistant](/platform/ai-assistant) with the insight loaded.

## Turn it on

**1. Open the Autonomy settings**

Go to **AI** → **Settings** → **Autonomy**. Changing it needs organisation **admin**.

**2. Enable proactive insights**

In the **Proactive insights** section, turn on **Analyse cluster health issues automatically**. It is off by default. The same section holds the detection thresholds and notification routing.

Each cluster also has an **Enable AI Insights** switch in its **Settings** → **General**, on by default; turn it off to leave one cluster out of the scans. With proactive insights off, you can still ask the AI Assistant about a cluster at any time with `⌘J`.

## Scan frequency

Scans adapt to cluster health:

| Cluster state | Scan interval |
| - | - |
| Critical issues active | Every 60 seconds |
| Active non-critical issues | Every 3 minutes |
| Healthy (no active issues) | Every 10 minutes |

## The insights list

Open a cluster and click **AI Insights** in the sidebar. The page has two tabs.

**Insights** lists the cluster's insights. Filter by status (**All**, **Open**, **Acknowledged**, **Resolved**) and severity (critical, warning, info), sort by **Most Recent**, **By Severity**, **Oldest First** or **Most Recurring**, and search titles and root causes. Select several insights to **Acknowledge** or **Dismiss** them together.

**Analytics** summarises the last 7, 30 or 90 days: new and resolved issues, the net change, mean time to resolve, a severity trend, breakdowns by namespace and category, the top recurring issues, and whether cluster health is improving, degrading or stable.

## An insight's detail page

Click an insight to open it. The page has four tabs:

* **Overview** - severity, the AI's confidence in its diagnosis (a warning appears when it is low), the root cause analysis, affected resources with links to them, recent changes that may have triggered it, and conversation starters.
* **Remediation** - remediation commands, recommended actions, and platform actions you can apply from the page.
* **Health** - the cluster's health, pod and node state, and container logs captured when the insight was detected.
* **History** - earlier resolutions if the issue has come back, each with its resolution type, notes, and whether the fix held.

The page also lists **Related Issues**: other open insights in the same namespace or category, since several issues in one namespace often share a cause.

### Status and resolution

| Status | Meaning |
| - | - |
| **Open** | Newly detected, needs attention |
| **Acknowledged** | Seen by someone and being investigated |
| **Resolved** | Fixed |
| **Dismissed** | Not actionable, or a false positive |

**Mark as Resolved** asks for a resolution type (**Manual fix**, **Configuration change**, **Rollback**, **Scale up**, **Restart**) and optional notes. Ankra also keeps a health snapshot from the moment of resolution, so you can compare the cluster before and after the fix.

Under **Was this analysis helpful?**, rate the analysis. A helpful rating makes Ankra reuse the analysis as a reference for similar issues later.

### Keyboard shortcuts

On the insights list, `1` and `2` switch between the **Insights** and **Analytics** tabs and `/` focuses search. On a detail page, `a` acknowledges, `i` asks the AI, `o`, `r`, `e` and `h` open the **Overview**, **Remediation**, **Health** and **History** tabs, and `[` goes back to the list. Shortcuts are off while the command palette, a dialog, or an input field has focus.

Scripts and agents read insights with the `get_cluster_insights` [MCP tool](/platform/mcp-tools).

## Alert-triggered analysis

When an [alert](/guides/alerts) fires, Ankra collects the state of the affected resources from the cluster - pod status and restarts, warning events, recent container logs, job results and node conditions - and asks the AI for an analysis. The analysis is attached to the firing.

To read it, open the alert and its **Firings** tab, and view the analysis on the firing's row. It contains:

* **Quick Summary** - what happened, in a few lines.
* **Root Cause** - the underlying problem, not just the symptom.
* **Key Insights** - observations about the resources involved, performance, timing, and the errors found.
* **Affected Resources** - each with a link to the resource.
* **Recommended Actions** - a checklist you can tick off as you work through it.
* **Full Analysis** - the complete write-up.

**Start Conversation with AI** opens the AI Assistant with the analysis loaded, to ask follow-up questions or have it carry out a recommended action. A cluster's overview also lists its recent **AI Analyses**.

Alert analyses also appear as incidents in **AI** → **Inbox**, one stream for approvals, incidents, insights and activity, and a firing can start auto-remediation under the [remediation policy](/platform/ai-autonomy#auto-remediation-policy).

## Next

Decide what the AI may do on its own when an alert fires: [AI Autonomy](/platform/ai-autonomy).


# AI Memory and Feedback
Source: https://docs.ankra.ai/platform/ai-memory

What Ankra's AI remembers about you across conversations, how your team's ratings of its answers are collected, and how to review or delete both.

The AI gets better at working with you in two ways: it remembers what you tell it, so you don't repeat yourself, and it records how your team rates its answers, so you can see where it falls short. This page covers both, and how to review or delete what is kept.

## Memory

Ankra's AI keeps a small personal memory: a **learned profile** (how you like answers delivered) and **saved memories** (facts worth keeping across conversations). Review both under **AI** → **Settings** → **Memory**.

> [!NOTE]
>
> Memory is **personal**. It only shapes your own conversations - nobody else in your organisation can read your profile or memories, and organisation admins have no special access to them.

### Learned profile

As you chat, the AI picks up preferences - communication style, preferred level of detail, other notes - and applies them to future answers. The **Learning** switch pauses that: turn it off and the profile stays as it is until you turn learning back on.

**Reset profile** wipes the learned traits and starts over. This can't be undone.

### Saved memories

Memories are short facts saved during conversations - either because you asked the AI to remember something or because it judged a detail worth keeping. In chat, the AI can also recall them on demand (the `save_memory` and `search_memories` [MCP tools](/platform/mcp-tools) expose the same store to connected editors).

From the settings page you can delete any single memory or **Clear all**. Deletion is immediate and permanent.

From the CLI, `ankra ai memories list` shows your saved memories newest first, and `ankra ai memories clear` deletes all of them in the current organisation:

```bash theme={null}
ankra ai memories list --limit 100
ankra ai memories clear
```

`list` shows 50 by default (`--limit` takes 1 to 200) and says when there may be more. `clear` asks for confirmation first: `--yes` skips the question, and answering no deletes nothing and exits with code 4. Both act on your own memories only, and both take `-o json` or `-o yaml`. The [CLI reference](/reference/cli/ai#ankra-ai-memories) lists every flag.

### Scope

Memory is scoped per user, per organisation: what the AI learns about you in one organisation does not follow you into another.

## Feedback analytics

Every AI response can be rated with a thumbs up or down, optionally with a comment. **AI** → **Settings** → **Usage & feedback** turns those ratings into a signal for how the AI performs on your clusters. Unlike memory, feedback is organisation-wide: admins see every rating.

### Overview tab

* Totals, positive/negative counts, and positive percentage for the selected period (default: last 30 days)
* Daily trend chart
* Per-cluster breakdown showing where the AI performs well or struggles
* Count of feedback entries that include comments

### Feedback list tab

A paginated table of individual entries. Each row carries full context: the feedback type and comment, the cluster, the AI's response, and the user question that prompted it.

Filter by date range, cluster, feedback type, free-text search, or "with comments only". Admins can **Export** the filtered list as CSV.

### Who sees what

* **Organisation admins** see all feedback across the organisation and can export CSV.
* **Members** see only their own feedback entries and analytics.
* One rating per AI message - submitting twice is rejected.

### Leaving feedback

Rate any AI Assistant response with the thumbs buttons under the message. Ratings with a short comment ("wrong namespace", "fixed it first try") are the most useful signal.

## Next

Teach the AI your organisation's conventions, rather than one person's, with [AI Skills](/platform/ai-skills).


# Ankra AI
Source: https://docs.ankra.ai/platform/ai-overview

What Ankra's AI does for you, what it may change without asking, where you can use it, and what it costs.

Ankra's AI investigates problems across your clusters, drafts fixes, and, where you allow it, applies them. Out of the box, nothing that is already running changes until a person approves it: every write the AI proposes stops for confirmation, and you decide how much more it may do on its own - per person, per connection, per agent, and when an alert fires. It runs on Ankra's default models within a free monthly allowance, or on your own provider key.

## What the AI does for you

* **Investigate a problem** - open the failing resource, press `⌘J`, and ask why. The assistant reads its logs, events, manifest and Stack history. See [AI Assistant](/platform/ai-assistant).
* **Build or change a Stack** - describe what you need and it proposes the add-ons, their order and starting values. See [Building a Stack](/concepts/stacks#building-a-stack).
* **Explain a firing alert** - an alert firing gets an AI analysis with the root cause and recommended actions. See [Alert-triggered analysis](/platform/ai-insights#alert-triggered-analysis).
* **Find problems before they page you** - scheduled scans raise findings with a root cause and a fix. See [AI Insights](/platform/ai-insights).
* **Review pull requests** - a verdict and findings on every pull request, and answers to `@ankraai` mentions. See [AI code review](/platform/ai-code-review).
* **Work tickets** - agents pick up tickets, draft a plan, and execute it once a person approves. See [AI Board](/platform/ai-board), [AI Agents](/platform/ai-agents) and [AI Automations](/platform/ai-automations).

## What it can change without asking

Five controls bound what the AI may do, each with a safe default. A chat write that runs without a confirmation card is recorded in the [audit log](/guides/audit-log) with the autonomy setting that allowed it.

| Control | Default | Options | Where it is set |
| - | - | - | - |
| **Chat mode** - what the AI Assistant may do in your own conversations | **Agent**: runs tools and asks before every cluster write | **Ask**: read-only, plus throwaway AI workspaces and PR demos. **Agent**: can act, asks first. **Plan**: you approve a plan before any write (web chat only) | The chat's **AI settings** → **Interaction mode**, or `ankra chat --mode`. Each person sets their own |
| **Chat autonomy** - whether Agent-mode writes stop for your confirmation | **Manual**: every write asks | **Auto**: low-risk, reversible writes and Stack deploys that remove nothing run at once with a receipt; everything else still asks | The chat's **AI settings** → **Autonomy**. Each person sets their own |
| **Connection AI mode** - what the AI may do when talked to from Slack, Teams, or a pull request | **Ask** for Slack and Teams. Source-control connections start with every capability off | **Ask**: read-only, plus throwaway workspaces and PR demos. **Agent**: can act and open fix pull requests; other destructive changes still ask | **AI** → **Settings** → **Connections**, per connection; the default under **Workspaces**. Admins only |
| **Agent autonomy** - what a standing AI agent may do when it runs | **Propose** | **Observe**: never proposes or makes changes. **Propose**: suggests actions, a person approves each. **Autonomous**: low-risk reversible actions run at once, riskier ones wait for approval | **AI** → **Agents**, per agent. Admins only |
| **Remediation policy** - what happens when an alert fires | **Off**. Switched on, it starts at **Propose**, 5 actions per incident, and a 30-minute cooldown before the same alert on the same cluster is picked up again | **Observe only**, **Propose** (every action goes to Slack for approval), **Autonomous** (low-risk reversible actions run, the rest ask). Per-action rules: **Run automatically**, **Ask on Slack**, **Never run** | **AI** → **Settings** → **Autonomy**. Admins only |

Whatever **Auto** or **Autonomous** allows, these always wait for a person:

* **Cluster lifecycle** - creating, scaling, upgrading, stopping, moving or deleting a cluster, its node pools or its control plane.
* **Removals** - a Stack change that would remove or replace a deployed add-on or manifest, or delete a Stack.
* **High-risk and irreversible writes**, and a Stack change whose validation failed.
* **Alert silences** - muting an alert always needs a person.

Writes into protected namespaces (`kube-*`, `ankra-*`, and system namespaces such as `cert-manager` and `vault`) are refused outright in every mode, and Kubernetes Secret values are withheld from the model. The exception to all of this is a remediation per-action rule set to **Run automatically**: that action runs with no approval card, so set it only for an action you would approve every time.

### Stopping the AI

Two organisation-wide stops, from least to most disruptive. Both take effect immediately and need organisation **admin**.

1. **Pause autonomous actions** - chat, diagnosis and read-only investigation keep working, but nothing changes without a person approving it. It switches off the remediation policy and pauses every running agent; resuming restores exactly what it switched off.
2. **Stop all AI** - the emergency stop. It cancels every running AI session and agent run, expires pending approvals, and blocks chat for everyone until an admin resumes it.

Both are on **AI** → **Settings** → **Autonomy**, and in the CLI:

```bash theme={null}
ankra ai autonomy pause --reason "investigating a bad deploy"
ankra ai autonomy stop-all --reason "incident in progress"
```

`ankra ai autonomy resume` and `ankra ai autonomy start-all` undo them. See [AI Autonomy](/platform/ai-autonomy).

## Where you can use it

| Where | How | Page |
| - | - | - |
| **Ankra web** | Press `⌘J` (`Ctrl+J` on Windows and Linux) on any page. The assistant starts from what you are looking at | [AI Assistant](/platform/ai-assistant) |
| **Slack** | Mention **@Ankra** in a channel or message it directly | [Connecting Slack](/platform/ai-connections#connecting-slack) |
| **Microsoft Teams** | Mention **@Ankra AI** in a channel or chat | [Connecting Microsoft Teams](/platform/ai-connections#connecting-microsoft-teams) |
| **Pull requests** | Mention `@ankraai` in a GitHub, GitLab or Bitbucket comment | [AI code review](/platform/ai-code-review) |
| **Your editor** | Connect Claude, Cursor or another MCP client to Ankra's MCP server | [MCP Server](/platform/mcp-server) |
| **Terminal** | `ankra chat --mode ask "why is my-app crashing?"` | [`ankra chat`](/reference/cli/chat) |

`ankra chat` accepts `--mode ask` or `--mode agent`; without it, the chat runs in Agent mode. Every surface uses the same tools and the same permission checks, and answers with the permissions of the person asking.

## Models and cost

On Ankra's default models, chat routes each question to one of three tiers: **Expert** (Kimi K3), **Think** (GLM 5.3) and **Quick** (Claude Haiku 4.5). Usage is priced per request and counted against a free monthly allowance per organisation - USD 10 on Free, USD 50 on Startup, USD 200 on Enterprise - and an optional daily spend cap you set yourself under **Billing** → **Overview**. When the allowance runs out, platform-funded AI pauses until the next month, and the rest of Ankra keeps working.

With your own OpenRouter, Anthropic or OpenAI-compatible key, usage bills to your account and never draws on the allowance. See [Models and Cost](/platform/ai-provider) and [Bring your own OpenRouter API key](/guides/openrouter-api-key).

## How work flows

Everything the AI does in the AI section converges on the [Board](/platform/ai-board). Work arrives from four directions: a firing alert spawns remediation, a proactive insight is filed, an [automation](/platform/ai-automations) reaches an approval gate, or a person files a ticket by hand.

```mermaid theme={null}
flowchart LR
    A[Alert fires] --> T[Board ticket]
    I[Proactive insight] --> T
    H[You file a ticket] --> T
    T --> W[Designated agent investigates and drafts a plan]
    W --> R[Peer review]
    R --> P[Your approval]
    P --> E[Agent executes and verifies]
    E --> D[Done]
```

Nothing works a ticket until an admin designates a board worker under **AI** → **Settings** → **Autonomy**: until then, every ticket the AI files is escalated straight to a person. Once one is designated, it investigates and drafts a plan. The plan waits for a reviewer agent - bind one, or turn the review requirement off, on the same page - and then for a person to approve it. Risky individual actions still ask in the Inbox as they happen.

| Surface | It answers | You go there to |
| - | - | - |
| **Board** | What is the AI working on? | Follow a ticket, review a plan, reassign or close work |
| **Inbox** | What needs a person right now? | Approve or deny actions, unblock tickets, scan incidents and insights |
| **Alerts** | What conditions page us? | Create alert rules and route notifications |

## Get started

Press `⌘J` on a cluster page and ask what needs attention. To set up the rest of the AI section, an admin opens [Guided setup](/platform/ai-guided-setup) from **AI** → **Home**.


# Models and Cost
Source: https://docs.ankra.ai/platform/ai-provider

Which models Ankra's AI runs on, how to use your own OpenRouter, Anthropic or OpenAI-compatible provider, and how AI usage is metered against the free monthly allowance and the daily spend cap.

Every AI answer runs on a model, and every model call costs money. This page covers which models Ankra uses out of the box, how to run on your own provider key instead, and how usage is metered against the free monthly allowance and the daily spend cap.

Organisation admins choose the provider for all AI features (the AI Assistant, AI Insights, alert analysis, CI/CD file generation, summaries) under **AI** → **Settings** → **Models**.

## Provider modes

| Mode | What it is | When to use it |
| - | - | - |
| **Ankra default** | Ankra's managed model access, served through OpenRouter. No configuration | Getting started. Usage counts against the [free monthly allowance](#usage-and-the-free-allowance) |
| **Custom Anthropic key** | Your own Anthropic API key | Your own billing and data agreement, with every tier served by Claude |
| **OpenRouter (your own key)** | Your own OpenRouter API key | The same default models and failover chain on your own billing - the recommended way past the free allowance |
| **Self-hosted / OpenAI-compatible** | Any OpenAI v1 endpoint: LiteLLM, vLLM, TGI, Ollama, Together, and similar | Self-hosted or third-party models behind an OpenAI-style API |

Credentials are stored independently, and more than one can be saved at once. A saved credential starts serving the calls only it can serve as soon as it is saved. **Prefer this credential** decides which key runs where two of them could serve the same call, such as an Anthropic key and an OpenRouter key. The top of the settings page states which credential runs what, and who pays for it.

## Default models

On the Ankra default, every organisation is served the same three tiers. The chat model picker selects between them, and **Auto** routes each question to the right one - short questions to Quick, everyday work to the default, and architecture, security, or image questions to Expert.

| Tier | Model | Context | Notes |
| - | - | - | - |
| **Expert** (default) | Kimi K3 | 1M tokens | Reasoning and image input. What Auto escalates to |
| **Think** | GLM 5.3 | 1M tokens | Reasoning at high effort, text only |
| **Quick** | Claude Haiku 4.5 | 200k tokens | Fastest and cheapest, for simple questions |

Because GLM 5.3 does not accept images, Auto sends any question with an attachment to Expert.

### The DevOps AI model by Ankra

Beside the three tiers, every catalog carries **DevOps AI**: Ankra's own model, served on Ankra's own servers and preloaded with the Ankra CLI skills, so it answers in Ankra's terms - the `ankra` CLI, stacks, GitOps, applications on Ankra Pipelines - without being told about them. It is text only, keeps a 128k-token context, and calls tools like the other models. Pick it in the chat model picker, or set it as a function's model; Auto never routes to it on its own.

It comes with an allowance of its own. Every plan, the free tier included, has **\$50 a month on the DevOps AI model**, separate from the [free monthly allowance](#usage-and-the-free-allowance). Past that it bills per token, like any model Ankra serves. The DevOps AI model is also what answers once your organisation runs out: when the free monthly allowance is spent, or the organisation's credit is gone, AI features switch to the DevOps AI model while its own allowance has room instead of stopping, and the conversation shows a notice when they do. Add your own model key to run on your own account instead.

These are defaults, not limits. Under **AI** → **Settings** → **Models** you can edit any tier, point it at a different model, add your own, or reset the catalog back to the Ankra defaults. With your own Anthropic key, every tier is served by Claude instead.

## Models per function

AI work that runs outside chat has its own model setting per function under **AI** → **Settings** → **Models** → **Models per function**. A function with nothing selected follows its default tier, so it moves with your catalog: point a tier at a different model and every function on that tier follows it.

| Function | Lane | What it does | Default tier |
| - | - | - | - |
| **Deploy analysis** | `deploy_analysis` | Inspects a repository and proposes how the application should be built and deployed | Expert |
| **Troubleshooting** | `troubleshoot` | Answers the one-shot troubleshooting analysis for a cluster | Expert |
| **CI/CD generation** | `cicd_generation` | Tailors the CI/CD pipeline and writes the Dockerfile when an application is onboarded | Expert |
| **Stack README** | `stack_description` | Writes the README that describes what a resource stack deploys | Think |
| **AI code review** | `pr_review` | Reviews pull requests, code, workflow runs and skills when no repository or connection picks a model | Think |

On the Ankra default the Think tier is GLM 5.3, so an organisation that has changed nothing writes stack READMEs and reviews code on GLM 5.3. On your own Anthropic key, Think is served by Claude.

Pick any model in your catalog for a function, or clear the selection to return it to its default tier. Only organisation admins can change a function's model. From the terminal, `ankra ai lanes list` shows what each function runs on, and `ankra ai lanes set <lane> <model>` changes it - it also accepts an exact OpenRouter model id.

## Change the provider

```bash theme={null}
ankra ai status                      # the active provider and the stored keys
ankra ai openrouter set              # store your OpenRouter key (prompts for it)
ankra ai anthropic set --api-key <your-key>
ankra ai openai set --base-url https://my-litellm.internal/v1 --model <model-id> --api-key <your-key>
ankra ai provider openrouter         # ankra | anthropic | openai_compatible | openrouter
```

`ankra ai models` edits the model catalog and `ankra ai lanes` the models per function. The sections below describe the same steps in the portal.

### Configure Anthropic

**1. Save the key**

Expand **Custom Anthropic key** and paste an API key (it starts with `sk-ant-`). Ankra validates it with a one-token health check before saving.

**2. Prefer it where keys overlap**

If you also hold an OpenRouter key, press **Prefer this credential** on the Anthropic row to decide which of the two runs the calls both could serve. The button is disabled until a valid key is saved.

Keys are stored in Ankra's secret store (HashiCorp Vault or OpenBao); the UI only ever shows a masked preview (`sk-ant-...XXXX`). Removing the key sends AI features back to the Ankra default key.

### Configure OpenRouter

With your organisation's own OpenRouter API key active, Ankra serves the same default models and automatic failover chain through your OpenRouter account - including background and autonomous AI sessions - and your usage never draws on the [free monthly allowance](#usage-and-the-free-allowance). The key is validated live against OpenRouter at save time and stored only in the secret store. Follow the step-by-step guide: [Bring Your Own OpenRouter API Key](/guides/openrouter-api-key).

### Configure an OpenAI-compatible endpoint

**1. Save the configuration**

Expand **Self-hosted / OpenAI-compatible** and provide:

* **Base URL** - the endpoint's OpenAI `/v1` root, `http(s)://` (e.g. `https://my-litellm.internal/v1`)
* **Model** - the model identifier your endpoint serves
* **API key** - the endpoint's key

Ankra probes `GET {'{base_url}'}/models` on save to verify the endpoint responds. An incorrect model id only surfaces at the first AI call.

**2. Point models at it**

Under **Chat models**, add the endpoint's models or point a tier at them. The endpoint serves only the chat models listed under it.

> [!NOTE]
>
> The endpoint serves the chat models you list under it, plus Stack summaries. The built-in Expert and Think tiers stay on their own models unless you point them at your endpoint under **Chat models**, and AI Insights, CI/CD pipeline generation and deploy analysis fall back to the Ankra default for tool-using steps. The settings page names which credential runs each model.

## Usage and the free allowance

Ankra meters every AI request - chats, agent sessions, AI Insights, alert analysis, CI/CD file generation, code reviews - per organisation, priced in USD from the tokens each model used. **Billing** → **Overview** shows month-to-date AI usage and how much of the free monthly allowance remains.

The allowance covers usage on **Ankra's managed model access**: the default when your organisation has no provider of its own, and anything your own key cannot serve. Usage on your own OpenRouter, Anthropic or OpenAI-compatible key never draws on it.

| Plan | Default monthly allowance |
| - | :-: |
| Free | \$10 |
| Startup | \$50 |
| Enterprise | \$200 |
| Custom | \$200, unless agreed otherwise |

Defaults can change; **Billing** → **Overview** always shows your organisation's live allowance. For more headroom, [contact support](/platform/support).

### When the allowance runs out

AI features that would spend Ankra's key pause for the rest of the calendar month (UTC). Those requests fail with the stable error code `AI_ALLOWANCE_EXHAUSTED`, which you can match on in automation. The rest of the platform, and AI on your own key, keep working. To resume before the reset, [bring your own OpenRouter API key](/guides/openrouter-api-key) or another [provider](#provider-modes).

### Daily spend cap vs monthly allowance

The **daily AI spend cap** is a separate brake you set yourself on **Billing** → **Overview**:

| | Monthly allowance | Daily spend cap |
| - | - | - |
| **What it limits** | Platform-funded AI spend only | Total AI spend, whoever's key funds it |
| **Who sets it** | Ankra, per plan | Your organisation (USD per day) |
| **Resets** | Start of each calendar month (UTC) | Daily |

## Permissions

Only organisation **admins** can view previews, save credentials, switch providers, or change a function's model. Other members see the settings read-only.

## Other AI settings

**AI** → **Settings** has these sections besides **Models**:

* **Connections** - Slack, Teams, source control, MCP tool servers and delivery; see [AI Connections](/platform/ai-connections)
* **Workspaces** - see [AI Workspaces](/platform/ai-workspaces)
* **Autonomy** - the stops, auto-remediation and [Proactive AI Insights](/platform/ai-insights); see [AI Autonomy](/platform/ai-autonomy)
* **Capabilities** - skills and custom tools; see [AI Skills and Custom Tools](/platform/ai-skills)
* **Usage & feedback** - response ratings; see [AI Memory and Feedback](/platform/ai-memory#feedback-analytics)
* **Memory** - see [AI Memory and Feedback](/platform/ai-memory)

## Next

Past the free allowance, [bring your own OpenRouter API key](/guides/openrouter-api-key) to keep the same models on your own billing.


# AI Skills and Custom Tools
Source: https://docs.ankra.ai/platform/ai-skills

Teach Ankra's AI your conventions with organisation skills, and give it organisation-specific capabilities with sandboxed custom tools.

The AI does not know your runbooks, your conventions, or your internal APIs. **Capabilities** is where you teach it: **skills** are reusable markdown instructions it follows, and **custom tools** are sandboxed scripts it can call. Both live under **AI** → **Settings** → **Capabilities**.

> [!NOTE]
>
> This page covers what **Ankra's own AI** uses inside the platform. To teach *your* editor
> or assistant (Claude Code, Cursor, Copilot and others) Ankra's conventions, install the
> [Agent Skills](/integrations/agent-skills) instead.

## Skills

Skills are reusable markdown instructions the AI draws on during conversations - runbooks, add-on configuration templates, CI/CD pipeline conventions. Ankra ships a set of platform skills, and organisation admins can add their own or override the built-ins.

### How skills resolve

Skills come in two tiers:

* **Platform skills** - built-in, read-only, maintained by Ankra.
* **Organisation skills** - created by your admins, scoped to your organisation.

An organisation skill with the **same name** as a platform skill shadows it - the AI uses your version instead. The skills page shows an **Override** badge on shadowing skills and a line-level diff against the platform original, with a one-click **Discard override** to restore the built-in.

### Creating a skill

**1. Open the editor**

Go to **AI** → **Settings** → **Capabilities** and click **New skill** - or select a platform skill and click **Override** to start from its content.

**2. Fill in the fields**

* **Name** - lowercase letters, digits, hyphens/underscores (max 100 chars); matching a platform skill's name overrides it
* **Description** - what the skill teaches (max 500 chars)
* **Content** - the markdown instructions (max 200,000 chars); YAML frontmatter at the top marks add-on and CI/CD skills
* **Kind** - `core`, `cicd`, or `addon`
* **Add-on charts** - for `addon` skills, the chart names the skill applies to
* **Always active** - inject the skill into every conversation instead of on demand, and into every [Org skills review](/platform/application-ai#which-skills-the-org-skills-review-uses) on repositories where that lane is on

**3. Save**

The skill takes effect immediately - the AI's skill cache is refreshed on every change.

### Who can change skills

All members can browse skills; creating, editing, and deleting requires organisation **admin**. Platform skills cannot be edited or deleted - only overridden.

## Custom tools

Custom tools extend what the AI can do with capabilities specific to your organisation: a security scan, an internal API call, a report generator. Each tool is a script with a typed input schema; once enabled, the AI can call it like any built-in tool.

### The sandbox model

Tool runs execute as one-shot sandbox jobs on your [staging cluster](/platform/ai-workspaces), isolated from the rest of the platform:

* Runs use a signed runner image with **no Kubernetes API access**.
* Network egress is limited to DNS and HTTPS.
* CPU, memory, and execution time are capped.
* The AI's arguments arrive as JSON in the `TOOL_INPUT` environment variable, validated against your input schema first.

### Creating a tool

**1. Define the interface**

Name the tool (lowercase, digits, underscores), describe what it does and when the AI should use it, and provide a JSON Schema for its input. The description is what the AI reads when deciding to call it - make it concrete.

**2. Write the script**

Pick a runner and write the script. Read `TOOL_INPUT` for arguments; whatever the script prints is returned to the AI.

**3. Set the guardrails**

Choose a **risk level** (low, medium, high), optionally mark the tool **trusted**, and scope it to all clusters or named clusters only. Secret values come from AI chat secret slots mounted as files - never hardcode credentials in the script.

Every save creates a new version; the version history on each tool shows what changed and when. Tools can be disabled without deleting them - a disabled tool is not offered to the AI.

### Who can change tools

Creating, editing, enabling, and deleting custom tools requires organisation **admin**. All members can see the tool list and version history.

## Next

Per-component learnings that travel with one add-on or manifest belong in [AGENTS.md](/platform/agents-md), not in a skill.


# AI Workspaces
Source: https://docs.ankra.ai/platform/ai-workspaces

The staging cluster where Ankra's AI runs short-lived workloads - workspaces, agent runs, and PR demos - and the time-to-live rules that clean them up.

AI workspaces are short-lived workloads Ankra's AI runs for you: code-search workspaces, agent and subagent pods, and time-limited PR demos of your applications. They all run on a **staging cluster** you designate, never on your production clusters. Configure everything under **AI** → **Settings** → **Workspaces**.

## Staging Cluster

Pick one of your connected clusters as the staging cluster. Its agent must be online for workspaces to start - the page shows the agent status for the saved cluster.

The same card sets the **default AI mode** new integrations start in (for example **Ask**, which allows read-only operations plus low-risk creates) - individual Slack, Teams, and Git connections can override it.

## Custom Ankra Domain

Every hostname Ankra generates for the organisation - its delegated DNS zone, each cluster's domain, and the preview URLs built from them - nests under a root domain. That root is `ankra.cc` unless you register your own in the **Custom Ankra domain** field on this page. The domain must be a bare domain you own, delegated to Ankra's nameservers before you save; the write is refused otherwise and names the nameservers to point at. A domain your connected Avura organisation shares with Ankra is the exception: it needs no delegation, and Ankra provisions the zones in your Avura account instead (see [use Avura domains with Ankra](/guides/avura-domains#root-generated-cluster-domains-on-an-avura-domain)).

Registering a domain creates one subzone in it - `<org_short_id>.<domain>` - and Ankra works only inside that subzone. Records already published at the apex or under any other name are never read, written or deleted, so a domain that already serves your production hostnames is safe to register on that count.

Changing the domain is refused while cluster domains or DNS records still live under the old root, and the refusal lists exactly which ones. It also separates the records you clear yourself from the ones the platform publishes and re-asserts, naming what to remove instead - deleting a reconciled record only lasts until the lane that owns it runs again. See [the preview URL](/concepts/applications#the-preview-url) for the full switch procedure and [what a switch does and does not touch](/concepts/applications#what-a-root-domain-switch-does-and-does-not-touch), and `ankra org domain get|set` for the CLI equivalent.

## Preview Domain

PR demos can get a public URL. Point a wildcard DNS zone at the staging cluster's ingress, then set the preview domain, ingress class, and TLS secret here. Without a preview domain, demos stay in-cluster only.

> [!NOTE]
>
> The **Preview domain** and the **Custom Ankra domain** above it are different settings with very different blast radius. The preview domain decides only where demos are published: Ankra writes nothing in that zone, and changing it is one field write with no blockers. The custom Ankra domain re-roots every hostname Ankra generates, and the switch is refused while cluster domains or DNS records still live under the old root. If you only want demos on your own domain, the preview domain is the one you want.

### DNS on your own preview domain

Publishing the records is the one prerequisite, and there are two ways to meet it. Ankra mints each demo a hostname under the preview domain, but the external-dns credential it provisions for a cluster is scoped to that cluster's own Ankra subzone and nothing else, so on its own the platform creates no record on your domain.

**Declare the domain as a custom DNS zone** (`ankra org dns credentials create`, then `ankra org custom-dns-zones add --zone <preview domain> --credential <name>`; see [serving a zone in your own DNS account from every cluster](/concepts/applications#serving-a-zone-in-your-own-dns-account-from-every-cluster)). Ankra then runs a second external-dns on every cluster with your credential, and each preview host is published as its Ingress lands - the same way the Ankra subzone works. The preview domain also becomes every cluster's **cluster domain**: `${{ ankra.cluster_domain }}` in stacks and profiles, Ankra AI's hostname advice, the deploy wizard's default hostname and `ankra cluster domain` all report it instead of the generated Ankra domain. This is the route for a domain that lives in your own DNS account and so cannot be registered as the Custom Ankra domain.

**Or point a wildcard at the staging cluster.** A wildcard `*.<preview domain>` pointing at the staging cluster's ingress address covers every demo without further work. Per-host records do not: each demo gets a fresh hostname nobody has published yet. The wildcard reaches only the staging cluster, so it does not make the preview domain the cluster domain elsewhere.

Without either, a demo still deploys and still reports ready, and its URL does not load. The certificate goes the same way, because an HTTP-01 challenge is answered over the hostname being certified: if the name does not resolve, Let's Encrypt cannot reach the solver and no certificate is ever issued. So an unpublished preview domain costs you the URL and the TLS together.

The settings screen and `ankra org ai-environment get` say so when the domain answers nothing and no custom DNS zone covers it, naming both routes and the cluster's ingress address to point a wildcard at. On the Ankra subzone none of this applies: the platform provisions the zone and the in-cluster external-dns publishes each preview record itself.

### TLS on your own preview domain

Demos get a certificate on both paths. Ankra requests one per preview hostname from the staging cluster's `letsencrypt-prod` ClusterIssuer, the one the cloud networking stack installs, and the preview URL is `https`.

Setting a preview domain does not change that. Each demo's hostname is concrete when Ankra writes the ingress and it resolves publicly, so an HTTP-01 challenge answers for it exactly as it does on the Ankra subzone. No wildcard certificate is involved, and none is needed.

> [!NOTE]
>
> A wildcard would in fact be hard to obtain: ACME issues wildcards only through DNS-01, and the ClusterIssuer the networking stack installs is HTTP-01 only. Per-preview certificates avoid the question entirely.

Two fields change the default:

| Field | Use when |
| - | - |
| **TLS secret** | You already hold a certificate for the preview domain in a secret on the staging cluster. Ankra serves it and requests nothing. |
| **Certificate issuer** | Your cluster's ClusterIssuer is not the one the networking stack installs. Ankra asks the one you name instead. |

The two are alternatives, and setting both is refused: cert-manager issues into whichever secret the ingress names, so a certificate ordered alongside your own would be written straight over it.

Ankra only requests a certificate when the staging cluster actually carries an ACME HTTP-01 ClusterIssuer. On a cluster without one, demo ingresses carry no TLS and previews are served over plain `http` - claiming TLS against a certificate nothing will issue would be worse. The settings screen and `ankra org ai-environment get` both say so when that is the case, so it is never something you discover by opening a preview.

Naming a certificate issuer without a preview domain is refused: on the Ankra subzone Ankra picks the issuer itself, from the networking stack it can verify.

From the CLI:

```bash theme={null}
ankra org ai-environment get
ankra org ai-environment set --demo-base-domain previews.example.com
ankra org ai-environment set --demo-cert-issuer letsencrypt-prod
```

Only the flags you pass are written; pass one with an empty value to clear that field.

See [PR preview environments](/guides/pr-preview-environments) for the full flow from pull request to running demo.

## Time-to-Live

Workspaces clean themselves up:

* **Workspace TTL** - how long code-search and agent workspaces live.
* **Demo TTL** - the default lifetime of a PR demo.
* **Per-role caps** - the longest a member of each role (admins and owners, operators, members) can keep a demo running.

## Active Workspaces

The bottom of the page lists every running workspace and PR demo with its cluster, namespace, and expiry. Admins can terminate any of them; the workspace's namespace on the staging cluster is deleted shortly after.

## Permissions

Changing the staging cluster, custom Ankra domain, preview domain, or TTLs requires organisation **admin**. All members can see the active workspace list.


# Publishing Applications as Add-ons
Source: https://docs.ankra.ai/platform/application-addons

Snapshot an application's manifests as a versioned add-on your organisation can install onto any cluster.

> [!NOTE]
>
> Publishing an application to the add-on catalog snapshots its committed manifests and its deploy options as one immutable version. The add-on installs independently of the application afterwards - it keeps working even if the source application is later deleted.

## What publishing does

An application in Ankra is a repository Ankra generates Kubernetes manifests for. Publishing turns the current state of those manifests into a catalog entry your organisation can install onto any of its clusters, without going back to the application.

A publish captures three things at that moment:

* the committed manifests under the application's `manifests/` directory, plus its [`.ankra/ankra.yaml`](/reference/application-descriptor) descriptor
* the **deploy options** the application declares, which become the add-on's install-time inputs
* the metadata shown in the catalog: display name, description, category

Everything is a snapshot. Later changes to the application only reach the catalog through another publish, and published versions are immutable - a version number, once used, cannot be reused.

> [!NOTE]
>
> This is different from [publishing an add-on to the Ankra Catalog](/platform/addon-publishing). That proposes a curation manifest to the *global* catalog every organisation sees, through a reviewed pull request. Publishing an application stays inside your organisation and takes effect immediately.

## Before you publish

Ankra checks whether the application is publishable at all and shows the result as the first step of the publish flow. Each check reports one of:

| Status | Meaning |
| - | - |
| **ok** | Nothing to do. |
| **warning** | Publishing works, but something is worth knowing first. |
| **blocked** | Publishing cannot proceed until this is resolved. |
| **unknown** | The check could not be evaluated. |

A **blocked** check stops the flow. A **warning** does not - it is a judgement call you are allowed to make, and it is repeated on the confirmation step so it is not lost along the way.

Where Ankra can resolve a check itself - most often a missing image registry declaration - the step offers **Fix automatically** rather than instructions. Checks that need an application admin say so instead.

## Publishing

1. Open the application and select **Publish to catalog**.
2. **Readiness** - resolve anything blocked, then continue.
3. **Details** - the version, display name, description, category, and a changelog.
   * Leave the version blank to bump the patch automatically. The field suggests the next one.
   * A version that is already published is refused here, before anything is snapshotted.
   * The changelog is shown against the version in the add-on's history. It is optional.
4. **Review** - what changed in the most recent published version, so you can see the shape of a typical change before adding another.
5. **Confirm** - a recap, any carried warnings, and what the snapshot means.

The first publish creates the add-on. Later publishes add versions to it.

## Version history

The add-on's detail page lists every published version, newest first, with its changelog, who published it, and how many files and options it carries.

**Compare** on any version shows what changed against the version published before it:

* **files** added, removed or modified, with the before and after contents side by side
* **options** added, removed or modified

A changed option is worth attention: options are the add-on's install-time input contract, so changing one is a breaking change for anyone who already installed the add-on. A version that starts or stops referencing an environment `Secret` is called out for the same reason.

> [!NOTE]
>
> There is no rollback and no "current version" control. An installation pins the version it was installed at, so there is nothing to roll back *to* - installing an earlier version explicitly is the equivalent, and existing installations are unaffected by later publishes.

## Installing a published add-on

Published applications appear in **Add-ons** alongside Helm add-ons. Installing one asks for a cluster, a namespace, and values for whichever deploy options the version declares, then deploys that snapshot.

Because the snapshot is self-contained, the add-on installs even when the source application has been deleted. The catalog says so on the entry, and no new versions can be published once the source is gone.

## Unpublishing

**Unpublish** hides the add-on from the catalog without touching anything already installed. Existing installations keep running and keep reconciling; the entry simply stops being installable. Publishing a new version makes it visible again.

Deleting the add-on outright is a separate, destructive action: it tears down the installations that came from it.

## Limits

An add-on holds at most 500 published versions. Snapshots are never pruned, because installations pin the version they were installed at and removing an old snapshot would break them.


# Application AI Settings
Source: https://docs.ankra.ai/platform/application-ai

Per-application control of the Ankra AI lanes that run on its repository - which lanes run, on which model, and within which branch scope and daily budget.

Every [application](/concepts/applications) carries an **Ankra AI** panel that decides which AI lanes run on that application's repository. Open the application, then **⋯** → **Settings** → **Ankra AI**.

Each lane follows your organisation's source-control defaults until this application overrides it. The panel is a view onto the same per-repository settings the review lanes read when an event arrives, so what you set here and what your organisation's [source-control connection](/platform/ai-connections) sets can never disagree.

> [!NOTE]
>
> The panel needs an application linked to a GitHub repository with the [Ankra GitHub App](/integrations/github) installed on that repository's owner. Without one it renders the reason instead of the lanes: the application has no repository yet, the App is not installed for the owner (install it under **AI** → **Settings** → **Connections**), or the application is on a provider the lanes cannot mint a repository token for - AI lanes are available for GitHub App repositories today.

## The lanes

| Lane | What it does | Runs when |
| - | - | - |
| **Pull request review** | Reviews the diff and posts a verdict with its findings as one comment that updates in place | A pull request is opened or updated |
| **Code review** | A deeper pass over the branch itself, with no pull request involved | A push to a branch in scope |
| **Actions review** | Reads the failed job logs of a red pipeline and explains what broke | A workflow run fails |
| **Org skills review** | Checks the change against your organisation's [skills](/platform/ai-skills) and conventions | Alongside the pull request review, in the same comment |
| **Demo URL** | Deploys a [preview environment](/guides/pr-preview-environments) per pull request and comments its public URL | A pull request is opened or updated |

Every lane is off for a repository nobody has configured. A fresh source-control connection must never start reviewing, replying, or deploying on its own, so each lane is switched on deliberately - here, or for the whole connection under [AI code review](/platform/ai-code-review).

> [!WARNING]
>
> **Code review** and **Actions review** are labelled **Not available yet** and their switches are disabled. Their cards describe what the lanes will do; nothing runs. On **Pull request review**, the **When it finds something** choice is stored but not acted on yet - that lane comments today whichever option you pick, and the card says so.

## Inherit or override

Every card is labelled either **Inherited** - it follows your organisation's default for this connection - or **Overridden**, meaning this repository pins its own value. Edits stage locally until you press **Save AI settings**, and only the lanes you touched are sent. A lane you never touch keeps inheriting, which is what lets an organisation admin go on steering every application that has not opted out.

Overriding a lane pins the whole lane: the values on the card when you save become this repository's settings for it, and later changes to the organisation default stop reaching that lane. Two controls undo it:

* **Reset to organisation default** on a card returns that one lane to the organisation, and says which way the organisation has it (on or off).
* **Follow organisation for everything**, at the top of the panel, drops this repository's override entirely so every lane inherits again.

## What you can set per lane

| Control | Lanes | What it does |
| - | - | - |
| **Model** | Every lane except Demo URL | Which model from your organisation's catalogue the lane runs on. **Ankra default** lets Ankra choose. The catalogue's **Auto** routing is deliberately not offered here: a lane that changed model between runs would make its findings impossible to compare. |
| **When it finds something** | Pull request review, Code review, Actions review | **Comment only** reports and stops. **Propose a fix** also opens a pull request with a suggested change - automatic source-control events run read-only, so the fix is a separate run that proposes a change for you to review, never an in-place edit. |
| **Target branches** / **Branches** | Pull request review, Code review | Comma-separated branch patterns with `*` and `?` wildcards. Leave it empty to put every branch in scope. |
| **Ignore paths** | Pull request review, Code review, Org skills review | Comma-separated globs, matched against each changed file's path after the change. Matching files leave the diff *before* the character budget is measured, so a lockfile or a generated bundle can no longer crowd the real change out of a review. `**` crosses directory separators, `*` and `?` do not, and a pattern with no wildcard also matches everything beneath it - `vendor` covers `vendor/lib/thing.go`. |
| **Skip draft pull requests** | Pull request review | On by default. Draft pull requests are reviewed once they are marked ready. |
| **Max runs per day** | Every lane except Demo URL | A cap on the lane's runs for this repository, counted since midnight UTC across every pull request, requested reviews included. Leave it blank, or set `0`, for no cap. On the pull request review it is checked before the per-pull-request cap, so a brand-new pull request can be declined on its first push once the repository is over it - see [the two budgets](/platform/ai-code-review#the-two-budgets). |
| **Max input characters** | Every lane except Demo URL | The most characters of diff one run may read. Leave it blank to use the built-in 120,000-character budget. |

**Demo URL** has no settings of its own here - it is on or off. What a preview deploys comes from the application's demo defaults; see [environment variables and a throwaway database](/concepts/applications#environment-variables-and-a-throwaway-database). Turning the lane off stops the automatic pull-request previews for this repository without touching manually launched [preview demos](/concepts/applications#preview-demos).

> [!NOTE]
>
> Mentioning Ankra in a pull request comment always gets an answer: a mention reply is a direct request from a human, so it is never filtered by branch scope, draft state, or either review budget. The run still counts toward the budgets.

## Which skills the Org skills review uses

The Org skills review is a second pass that rides on the pull request review and appends an **Organisation skills** section to the same comment, so it runs only when **Pull request review** runs too. It judges the change against:

* every skill marked **Always active**, and
* the skills pinned in this lane's `skill_ids`.

Skills of every kind count: core, CI/CD and add-on alike. One review uses at most 12 skills, always-active ones first, with at most 24,000 characters of skill text. With no always-active or pinned skill, the lane posts nothing.

Only the Org skills review reads `skill_ids` (the `skills` lane in [`ankra application ai-config`](/reference/cli/application)). The field also appears on the other lanes in the CLI and API output, but no review reads it there. The panel has no skill picker yet, so marking a skill **Always active** is how to put it in front of the review today. That also adds it to every AI conversation; see [AI Skills](/platform/ai-skills#creating-a-skill).

To steer the pull request review itself, use its review instructions: per connection under [AI code review](/platform/ai-code-review), or per repository as the pull request lane's `custom_instructions` (at most 4,000 characters). A repository override pins the whole lane, as described under [Inherit or override](#inherit-or-override).

## Settings are per repository, not per application

> [!WARNING]
>
> These settings are keyed by the repository, not by the application. Two applications connected to the same repository share one set of lane settings - turning a lane off on one turns it off for the other, and each application's panel renders the other's edits as its own. The preview lane also fires once per matching application, so such a repository collects one preview comment per application on every pull request. Keep one application per repository until per-application keying ships.

## Related

* [Applications](/concepts/applications) - connecting a repository, components, demos, and registries
* [PR preview environments](/guides/pr-preview-environments) - what the Demo URL lane deploys, and its status comment
* [AI Skills](/platform/ai-skills) - the skills the Org skills review lane checks a change against
* [AI code review](/platform/ai-code-review) - the organisation-wide switches, review model, and review instructions these lanes inherit from
* [AI Connections](/platform/ai-connections) - every integration the AI communicates through
* [`ankra application pull-request-reviews`](/reference/cli/application) - read the reviews a lane has posted, from the CLI


# Billing & Usage
Source: https://docs.ankra.ai/platform/billing

Understand your usage, estimates, invoices, and subscription plans in Ankra.

> [!NOTE]
>
> Ankra billing is based on **worker vCPU usage**. Each plan includes a free vCPU allowance - you only pay for usage above that threshold, billed monthly. [Playground environments](#playground-environments) are the exception: they are billed outside the vCPU metering. Pay-as-you-go organisations pay from [credit](#credit-and-payment-method), and saving a payment method unlocks €59 of welcome credit.

***

## Plans

Ankra offers three standard plans. Organisations on a custom agreement see a dedicated plan view.

| | Free | Startup | Enterprise |
| - | :-: | :-: | :-: |
| **Price** | €0 | €0.01/vCPU/hr | €0.03/vCPU/hr |
| **Annual price** | - | €0.008/vCPU/hr | €0.024/vCPU/hr |
| **Free vCPU allowance** | 30 | 30 | 30 |
| **Clusters** | Unlimited | Unlimited | Unlimited |
| **Team members** | Unlimited | Unlimited | Unlimited |
| **AI Assistant** | Yes | Yes | Yes |
| **SSO** | - | - | Yes |
| **Audit log export** ([CSV, JSON, API](/security/audit-export)) | Yes | Yes | Yes |
| **Support** | Community | Priority email | Dedicated |

> [!TIP]
>
> Annual commitment saves 20% on per-vCPU pricing. You can switch between monthly and annual on the Plan page.

***

## Credit and payment method

Pay-as-you-go organisations pay for resources from credit. A payment method is required to use resources, but credit is always spent first, and **you will never be charged without a top-up**: your card is only charged when you add credit.

### Welcome credit

Saving a payment method unlocks **€59 of welcome credit, valid for 60 days**. The credit is no longer granted when the organisation is created - it is added when the card is saved, from [guided setup](/get-started/guided-setup) or from **Billing**. It is granted at most once per card and once per person: a card that already unlocked it for another organisation, or an owner who already received it there, does not unlock it again, and an organisation that already holds Ankra Cloud's sign-up credit does not receive it either. Credit you have not spent when the 60 days end expires. Welcome credit granted before the change on 24 October 2026 keeps its original amount and expiry date.

Until a payment method is saved, a new organisation can run its free [playground](/guides/cluster-sandbox), but cannot create or import other clusters. It can also spend a small allowance of pipeline minutes and AI each calendar month (UTC), and once that is spent its pipeline runs and AI pause until a payment method is saved. A playground on an Ankra Cloud dev cluster lasts 24 hours without a card.

### Top-ups

Add credit from **Billing → Wallet**. Each top-up charges your card for the amount you choose and adds it to your balance.

**Automatic top-ups** are off unless you turn them on. Set the balance to top up at, the amount to add, and daily and monthly caps, and Ankra adds credit when your balance drops below the threshold. We recommend turning them on for anything you need to keep running, so your services are never paused for lack of credit.

### When credit runs out

What happens when your balance reaches zero and nothing tops it up depends on what you are running:

* **On the Ankra platform, nothing that is running is stopped.** Creating new clusters and AI usage are paused until you top up. Your running clusters are unaffected.
* **On Ankra Cloud servers**, including a playground that runs as an Ankra Cloud dev cluster, new resources are refused. You are notified first, and after a grace period running servers are stopped. They stay stopped until you top up.

Adding credit restores access.

***

## Playground environments

A [Playground](/guides/cluster-sandbox) is a development and evaluation Kubernetes environment on Ankra-hosted infrastructure.

Playgrounds are moving to **Ankra Cloud dev clusters** - a single-node Kubernetes cluster managed by Ankra. This is rolling out, so your organisation may still get a playground on the shared infrastructure described below. An Ankra Cloud dev cluster is one server with 2 vCPU / 4 GB. Without a payment method the free cluster lasts 24 hours. Once a [payment method is saved](#credit-and-payment-method) it keeps running, paid from your credit. It is billed as Ankra Cloud usage and is not counted toward your plan's worker-vCPU metering.

The sizes below apply to playgrounds on Ankra's shared playground infrastructure. They are sold as flat monthly list prices per size, in EUR excluding VAT, on every plan. Storage is bundled into the size.

| Size | vCPU / RAM | Storage | Max pods | PVCs | Monthly price | Hourly equivalent |
| - | - | - | - | - | - | - |
| **Trial** | 1 vCPU / 2 GB | 20 GB | 30 | 5 | Free - expires when the organisation goes idle | - |
| Small | 2 vCPU / 4 GB | 50 GB | 40 | 10 | €5.21 | €0.007 |
| Medium | 4 vCPU / 8 GB | 100 GB | 60 | 20 | €8.06 | €0.011 |
| Large | 8 vCPU / 16 GB | 200 GB | 100 | 30 | €15.19 | €0.021 |
| Extra large | 16 vCPU / 32 GB | 400 GB | 150 | 50 | €28.01 | €0.038 |

The hourly equivalent is the monthly price over a 730-hour month, for comparison only - billing is per second, not per hour.

How playground charges work:

* **Pro-rata by the second.** Billing runs from the moment the environment is ready (its `ready_at` time) until you destroy it. Nothing accrues while it is provisioning.
* **The price you order at is the price of record.** Later catalogue changes apply to new orders only, never to an environment you are already running. A resize bills the old price until the resize completes and the new price after.
* **Flat price, nothing else metered.** There are no per-vCPU, per-GB, egress, IP or GPU charges for playgrounds. Playground clusters are excluded from the plan's worker-vCPU metering: they are never billed per vCPU, and they do not consume the 30 free vCPU either.
* **Own invoice line.** Playground spend appears as its own line on the invoice, separate from worker-vCPU usage.
* **One free Trial per organisation.** The Trial costs nothing and needs no billing plan or card. On shared playground infrastructure it expires when the organisation goes idle; as an Ankra Cloud dev cluster it lasts 24 hours unless a payment method is saved.
* **An organisation memory budget of 8 GB.** Paid playgrounds share a budget of 8 GB of advertised RAM per organisation unless a limit increase has been approved. Request one from the size picker or from the **Playground memory budget** card on the billing page.

Ordering a paid size requires billing permissions in your organisation, a billing plan and a payment card on file. New paid orders refuse while an invoice is overdue.

> [!WARNING]
>
> Playgrounds are for development and evaluation only: no production workloads, no personal data, no backups, and they are excluded from the SLA (Terms of Service clauses 6.2 to 6.4 and 9.9).

See [Sizes and Pricing](/guides/cluster-sandbox#sizes-and-pricing) on the Playground page for what each size includes and how to order, resize and destroy one.

***

## Billing Overview

Navigate to **Billing** from the organisation sidebar to see an at-a-glance summary:

* **Current Plan** - your active plan, billing cycle, commitment period, and Stripe connection status.
* **Stat cards** - total vCPU, worker vCPU, billable vCPU (above free allowance), estimated monthly cost, and cost so far.
* **Cluster vCPU Summary** - per-cluster breakdown of worker and total vCPU, grouped by activity. Reporting clusters show their vCPU counts with a bar indicating each cluster's share of worker vCPU. Clusters that stopped sending node data within the last 7 days (for example because their agent is disconnected) stay listed with a **Last seen** status - they do not accrue usage while silent. Clusters with no node data for more than 7 days are collapsed behind a **Show N inactive clusters** toggle so long-gone machines don't crowd the list.

### Estimated Monthly Cost

The overview and analytics pages show two cost figures:

| Metric | Meaning |
| - | - |
| **Est. Monthly Cost** | What you'll likely pay this billing cycle - actual cost so far plus a projection of the remaining days based on your current usage. |
| **Full month avg.** | What every month would cost if your average usage stayed the same. Calculated from the average hourly cost during active hours, extrapolated across the full month. |

The "so far" subtitle shows how much has accrued and what percentage of the month has elapsed.

### AI Usage and Free Allowance

The overview also meters your organisation's AI activity. Every AI request is tracked (tokens per model, priced in USD), and each plan includes a free monthly AI allowance that covers usage served on Ankra's platform key. The overview shows month-to-date AI usage, the allowance meter, and a self-serve **daily AI spend cap** (USD/day) you can set as a brake on total AI activity.

Every plan also includes **\$50 a month on the DevOps AI model by Ankra**, Ankra's own model, metered separately: the overview shows that allowance beside the ordinary one. Past it the model bills per token, and once the ordinary allowance or your credit is used up, AI features run on the DevOps AI model while it has room instead of stopping.

See [Models and Cost](/platform/ai-provider#usage-and-the-free-allowance) for what the allowance covers, what pauses when it is exhausted, and how to keep unlimited AI with [your own OpenRouter key](/guides/openrouter-api-key).

***

## Usage of every meter

Worker vCPU is one of several things Ankra measures. [Usage](/platform/usage) reports every meter in one place - worker vCPU-hours, playgrounds, managed services, Ankra hosted logs and metrics, and AI - per month or day, split by cluster, application or managed service, with how completely each was measured and what it costs. Managed services and hosted logs and metrics are included during the pilot.

***

## Showback by project

The invoice is one per organisation and never splits by [project](/concepts/projects). For charging teams back internally, **Billing → By project** reports, per project, the clusters it holds, their current worker vCPU, the worker vCPU-hours over the window and each project's share of the total, plus the hours no project could claim. The same figures are served at `GET /api/v1/org/billing/analytics/by-project?hours=720` and by `ankra org usage --group-by project`. Hours are attributed to the project a cluster was in when they were metered, so a cluster that moved mid-month is split between the two projects rather than rewritten. Nothing here changes what you are charged: it is a view of the one invoice, not a second one.

## Usage Analytics

Go to **Billing → Usage Analytics** for detailed usage data:

* **Time range picker** - view the last 24 hours, 7 days, 30 days, or a custom range.
* **Metric cards** - current, peak, and average worker vCPU; active cluster count; estimated monthly cost with full-month average.
* **vCPU chart** - area chart of worker vCPU over time with a dashed line for the free allowance.
* **Cost breakdown chart** - hourly cost bar chart showing estimated billable cost per hour (only appears when usage exceeds the free tier).
* **Cluster breakdown table** - per-cluster worker vCPU, total vCPU, and percentage share.

> [!NOTE]
>
> If all your usage is within the free vCPU allowance, the cost breakdown shows a "Within free tier" message instead of a chart.

***

## Invoices

Go to **Billing → Invoices** to view your billing history:

* **Search and filter** - find invoices by text or filter by status (all, paid, open, draft).
* **Summary cards** - total invoices, combined amount and vCPU-hours for the current page, outstanding balance, and average invoice.
* **Invoice table** - billing period, amount, billable vCPU-hours, status, PDF download, and a Pay Now link for open invoices.
* **Stripe portal** - click "Manage in Stripe" to access Stripe's hosted billing portal for payment methods and invoice history.

***

## Changing Your Plan

Navigate to **Billing → Plan & Subscription** to upgrade, downgrade, or adjust your billing cycle.

**1. Choose a billing cycle**

Toggle between **No commitment** (monthly) and **Annual commitment** (20% discount).

**2. Select a plan**

Click the button on the plan you want. If the plan requires payment, you'll be redirected to Stripe Checkout.

**3. Complete payment**

Enter your payment details in Stripe. After checkout you're redirected back to Ankra and your subscription syncs automatically.

> [!WARNING]
>
> If your organisation doesn't have Stripe connected and you select a paid plan, you'll be prompted to set up billing first.

***

## How Billing Is Calculated

Ankra tracks vCPU usage through periodic snapshots of your clusters:

1. **Snapshots** are taken hourly per cluster, recording worker vCPU and total vCPU.
2. **Billable vCPU** = worker vCPU minus the free allowance (per hour bucket, aggregated across clusters).
3. **Cost per hour** = billable vCPU × effective rate (plan rate adjusted for any annual discount).
4. **Monthly cost** = sum of hourly costs for the billing period.

Only **worker node vCPU** counts toward billing. Control plane nodes are not billed.

***

## FAQ

> [accordion] What counts as a worker vCPU?
>
> Worker vCPU is the total vCPU count across all worker nodes in your clusters. Control plane / master nodes are excluded from billing.

> [accordion] When does billing start?
>
> Billing starts when your clusters report worker vCPU usage above the free allowance. If you stay within the free tier, there is no charge.

> [accordion] Can I switch plans mid-month?
>
> Yes. Plan changes take effect immediately. Your invoice for the month will reflect the prorated usage under each plan.

> [accordion] How do annual commitments work?
>
> Annual billing locks in a 20% discount on the per-vCPU rate. You commit for 12 months and are billed monthly at the discounted rate. Your commitment end date is shown on the billing overview.

> [accordion] What happens if I exceed the free allowance?
>
> Usage above the free vCPU allowance is billed at your plan's per-vCPU/hr rate. The estimated monthly cost on the overview page updates in near real-time.

> [accordion] Why does my cluster show 'Last seen' instead of vCPU counts?
>
> The Ankra agent on that cluster has not synced node data recently, so Ankra cannot see its capacity. This usually means the agent is disconnected, the cluster was deleted outside Ankra, or node syncing is failing. A silent cluster accrues no usage. Reconnect the agent to resume metering, or delete the cluster from Ankra if it no longer exists. After 7 days without node data the cluster moves into the collapsed **inactive clusters** section of the summary table.

***

## Next Steps

> [card] [Usage Analytics](/platform/billing)
>
> Dive deeper into vCPU trends and cost breakdowns.

> [card] [Organisations](/concepts/organisations)
>
> Manage teams and resources across organisations.


# Cloud Cost
Source: https://docs.ankra.ai/platform/cloud-cost

See what every cluster costs, split the money down to namespaces and stacks, and find the idle capacity worth cutting - without a separate cost tool.

Your cloud bill tells you what you spent last month, not which cluster or team caused it or what you could turn off tonight. Cloud Cost prices every cluster from the machines and volumes Ankra already sees, splits the money down to namespaces and stacks, and points at the idle capacity worth cutting. It needs no extra cost tool.

> [!NOTE]
>
> All figures are **estimates** built from list prices for the resources Ankra can see. Use them for trends, right-sizing and chargeback, not for reconciling an invoice to the cent.

***

## Get a number for every cluster

Ankra prices a cluster once two things are in place:

1. **A price source for its capacity.** For a public provider, a [cloud credential](/platform/credentials) for that provider. For Proxmox VE, VMware, HPE Morpheus or your own hardware, a [rate card](#private-capacity-rate-cards).
2. **The cluster online**, so the [agent](/concepts/cluster-agent) can sync its nodes and volumes.

Until then, the cost panel on the cluster's **Overview** page says what is missing, such as no credential, no rate card, cluster offline or pricing still resolving. A cluster that cannot be priced is shown as **not priced**, never as free. The state values are listed in the [Cost API reference](/reference/cost-api#readiness-states).

Open **Cost** in the main sidebar. It has six tabs:

| Tab | What it answers |
| - | - |
| **Overview** | Projected month end, month to date, run rate and priced clusters, then the money by provider, by credential and by costliest cluster |
| **Clusters** | Every cluster's run rate, projection, confidence and paying credential. Each row opens the cluster's [drill-down](#per-cluster-drill-down) |
| **Credentials** | Spend grouped the way the bill arrives: provider, then credential, then the clusters it built |
| **Workloads** | Which stacks, add-ons and applications the money runs |
| **Savings** | Recommendations with an estimated monthly saving, and orphaned resources |
| **Settings** | Display currency, discount and network egress estimate |

The fleet totals also appear on the [Dashboard](/platform/dashboard).

***

## Where the prices come from

| Provider | Price source |
| - | - |
| AWS, Google Cloud, Azure | Each provider's public price catalogue, per region |
| Hetzner | Hetzner's own price list, read every hour with the organisation's Hetzner credential, per location |
| OVHcloud, UpCloud, DigitalOcean, Scaleway | Ankra's built-in book of published list prices |
| Proxmox VE, VMware, HPE Morpheus, imported hardware | Your [rate card](#private-capacity-rate-cards) |

> [!NOTE]
>
> **Hetzner.** A server ordered before the 2026-06-15 price increase is priced from the earlier list. Without a Hetzner credential, Ankra uses its built-in copy of the list and reports `medium` confidence instead of `high`. A server that ran for only part of the month reads slightly low, and servers outside the cluster, such as CI runners in the same project, are not in any cluster's estimate.

***

## Private capacity: rate cards

Proxmox, VMware, Morpheus and imported hardware have no published price, so you state what the capacity costs. A **rate card** is three monthly rates in your own currency: per vCPU, per GB of memory and per GB of provisioned storage. Ankra multiplies them by what each cluster holds.

The card lives on the **credential** that provisions the capacity, so every cluster built from one Proxmox datacentre inherits the same rates. Set it under **Credentials** → your credential → **Pricing**.

* **Proxmox ships with defaults** of EUR 3.00 per vCPU, 0.75 per GB of memory and 0.02 per GB of storage per month, labelled **Ankra defaults**. Saving the form makes them your own; clearing it returns to the defaults.
* **Other private providers have no defaults**, so their clusters stay **not priced** until you set rates.
* **Imported clusters with no provider credential** use the organisation's own rate card, if you set one.

A rate change applies from the next hourly pass. It does not rewrite past figures.

***

## Read the fleet by credential

A cloud bill arrives per account, and an account is what a credential holds. The **Credentials** tab groups spend by provider, then by the credential that actually built each cluster. Each live credential opens its own page with its clusters and, for private capacity, its rate card. A deleted credential keeps its name in the list while its clusters still cost money, and clusters with no recorded credential, such as imported ones, collect into one **No credential recorded** row per provider.

***

## Attribute spend to teams

Every hour Ankra allocates each cluster's cost to its namespaces by their share of CPU and memory. The **Workloads** tab joins that allocation to names you recognise: the **stack** a namespace belongs to, the **add-ons** in it and the **applications** installed into it. Rows are ranked by monthly cost and can be filtered by cluster, which gives you a chargeback view per team. The tab shows the 500 costliest rows.

### By project

Every cost read is per [project](/concepts/projects). The Cost pages show the project you are working in, with a project filter to read another one or the whole organisation, and the organisation-wide view carries a **By project** breakdown: each project's run rate and cluster count, with an **unattributed** bucket for spend no project can claim, such as waste found on an organisation-wide credential rather than a cluster, so the projects reconcile to the fleet total only together with that bucket.

On the API, a read without a project is your current project; `project_id=all` on `GET /api/v1/org/cloud-cost/summary` and the other cost routes reads the whole organisation, and a project id reads that project. The organisation-wide summary carries `by_project`, and every response carries a `scope` block saying which project it describes and whether it is a floor because some clusters are hidden from you. Cost is stamped with the cluster's project every hour, so a cluster that moves projects mid-month shows up in both, each for the hours it was there, and a project's history is not rewritten by a move.

***

## Cut waste

**Savings** turns the same data into actions, each with an estimated monthly saving:

* **Right-size idle capacity.** When a large share of a cluster's run rate sits idle, **Right-size with AI** opens Ankra's AI on that cluster. It proposes scaling changes and applies nothing until you confirm.
* **Stop non-production clusters off-hours.** A non-production cluster running around the clock on a provider with [power schedule](/platform/cluster-power-schedules) support gets **Add off-hours schedule**. It creates two schedules in UTC: weekdays at 19:00 the worker servers are deleted, at 07:00 new ones are created, and weekends stay down. The control plane, etcd, cloud volumes and addresses are kept and keep billing. Data on the workers' own disks is lost at every stop. A cluster without a known environment label is never offered this.
* **Reduce unallocated spend.** Raised when a quarter or more of a cluster's run rate is not allocated to any workload.

### Orphaned and idle resources

A waste scan runs every six hours and lists resources that bill while doing no work:

| Finding | What it means |
| - | - |
| Stopped server (still billed) | A switched-off Hetzner server. Hetzner bills it in full for as long as it exists |
| Unattached volume | A block volume attached to no server |
| Unassigned IP address | A primary IPv4 or floating IP assigned to nothing |
| Load balancer with no targets | A load balancer that forwards to nothing |
| Released persistent volume | A Kubernetes volume stuck in `Released`, still billing while no claim can bind it |

Each finding shows its monthly cost, or "price unknown", and **Resolve with AI** opens a chat naming the exact resource. The provider-side scan covers Hetzner accounts; the released-volume check covers every cluster. A credential that could not be listed is shown as a partial scan, not as "no waste".

***

## Per-cluster drill-down

Open a cluster from **Clusters**, **Savings** or the Overview to see what to change on it and why it is safe:

* **Cost trend** over the last 30 days, and **where the money goes**: compute (on-demand and spot), storage, network, control plane, and Bastion and VMs, with idle and unallocated portions.
* **Node evidence**: for every node, the measured average, p95 and peak CPU and memory over 24 hours, 7 days or 30 days, against what the scheduler reserved. Each node gets a verdict: *underutilised* (p95 fits well under the reservation on both CPU and memory, with the saving from sizing to 1.5 times p95), *spiky - keep headroom* (never called safe to downsize), *well sized*, or *no metrics*.
* **Recommendations** with that evidence attached, **namespace costs**, and the cluster's **waste findings**.

Node evidence needs the platform metrics pipeline. Without it, recommendations are based on resource requests and the page says so.

### What if the node groups changed?

Under the breakdown, a **what-if draft** lists the cluster's node groups (node count, vCPU, memory, disk and GPUs per node) and its load balancers. Change a count, resize or add a group, or add a load balancer, and the panel shows **today's bill**, the **predicted bill** and the **change**. Nothing is saved or applied; **Discard draft** or a reload clears it.

The prediction is today's bill plus the priced difference between the draft and today, so only what you changed moves the number. A resized group lands on the cheapest published size that holds its vCPU, memory and GPUs, keeping its CPU architecture, and the panel names the size. Private capacity is priced from the cluster's rate card. Pick another provider to price the same draft there, including from private capacity.

A group with GPUs is placed only on a GPU size and keeps its card where a size carrying it fits; a group without GPUs is never placed on one. On UpCloud every GPU plan in the price book is a size, and a GPU group marked **Spot** lands on the matching spot plan. Where a provider's price book records no GPU sizes, the group reads **Not priced** instead of taking a CPU size of the same shape.

A group nothing can price reads **Not priced** with the reason. Scripts can use the same estimate: see [What-if estimate](/reference/cost-api#what-if-estimate).

***

## Compare providers

**Compare providers**, a button on the cluster's cost page, prices the whole bill (node groups, the control plane Ankra provisioned, volumes and load balancers) on every provider Ankra can build on, side by side.

[Ankra Compare Providers: your cluster, priced on every cloud](https://www.youtube-nocookie.com/embed/cZWsyu1vUaU?rel=0)

* **DigitalOcean, Hetzner, OVHcloud, Scaleway and UpCloud** price from Ankra's list-price book.
* **AWS, Google Cloud and Azure** price from their per-region catalogues, and each column names the region it used. AWS offers every current-generation EC2 type except Apple Mac hosts, burstable T instances included. Google Cloud and Azure offer only the families whose shape can be read from the size name: general-purpose and compute-optimised, plus Azure's memory-optimised E series. [Which sizes each hyperscaler offers](/reference/cost-api#hyperscaler-sizes).
* **Proxmox VE and HPE Morpheus** price per unit of capacity from a rate card, and the column says which card.

Each column shows the predicted monthly bill and the difference against today. Tiles name the **cheapest full match**, the **closest to today**, and a **break-even**: two weeks of running both clusters during the move, against what the move saves per day.

Pick a matching rule at the top:

* **Like-for-like** (the default) keeps each group on the same vCPU class, shared or dedicated, where the target sells one. The [class of each provider's sizes](/reference/cost-api#vcpu-classes) is listed in the reference.
* **Cheapest size that fits** ignores class. Under like-for-like it stays as a footnote on each column.

A node group with GPUs is priced only where the target's price book records GPU sizes, which today is UpCloud. On every other target the group is unpriced, so the column shows a "from" figure and names it.

A **Stay** column prices the same fleet re-sized on the cluster's own provider. Select any column to see it line by line and group by group. A target with an unpriced line shows a "from" figure, names what is missing, and never sorts as cheapest.

Latency, storage class, availability zones, load-balancer features, egress terms and negotiated discounts are not priced. Weigh them next to the number.

***

## Settings

Each member can set **Your display currency** under **Cost** → **Settings**, and every cost figure they see, including provider quotes in the cluster-create wizards, renders in it. Organisation admins set the defaults:

* **Currency** - the organisation default: EUR (the default), USD, GBP, SEK, NOK, DKK, CHF, PLN, CZK, JPY, CAD, AUD or INR.
* **Effective discount** - a flat 0-100% discount on list prices, to approximate committed-use or enterprise agreements.
* **Network egress estimate** - whether figures should include a network egress estimate once egress is metered. The setting is stored, not metered yet: no figure includes network egress today, whichever way it is set.

***

## From the CLI and Ankra AI

```bash theme={null}
ankra cost summary
ankra cost cluster my-cluster
ankra cost settings set --currency eur --discount 10
```

Each read is your current [project](/concepts/projects). The global `--project <name>` reads another project; `--all-projects` on `cost summary`, `savings`, `ledger`, `trend`, `events`, `reconcile` and `cost budgets list` reads the whole organisation, and `cost summary` then shows the **By project** table; `ankra cost object project <name>` prices one project:

```bash theme={null}
ankra cost summary --all-projects
ankra cost summary --project payments
ankra cost object project payments
```

Every command takes `-o json`. See the [`ankra cost` reference](/reference/cli/cost) for savings, the ledger and per-object cost, and the [Cost API reference](/reference/cost-api) for field meanings.

In chat and over MCP, Ankra's AI reads the same figures with `get_fleet_cloud_cost`, `get_cluster_cost`, `get_stack_cost`, `get_cloud_savings` and `get_cost_settings`. Changes need an `mcp:write` token and the same permissions as in the portal.

***

## Budgets and the cost autopilot

A **budget** is a monthly amount for the organisation, one project, one cluster, one environment label or one application. It shows spend so far, the projected month end and the hour it would cross the budget. Ankra sends a **Budget crossing** notification when the projection reaches the alert threshold (80% unless you set another). Route it with [notification routing](/guides/notification-routing).

The **cost autopilot** decides how much Ankra may do about cost without asking. Each environment kind (production, staging, development, preview, unknown) takes a tier: hands-off, scheduled, managed or ephemeral. An organisation that never set a policy is hands-off everywhere, so every change waits for a person. You can override one cluster's tier and set daily quiet hours, and give a project its own defaults, which sit between the organisation's policy and a cluster's override.

```bash theme={null}
ankra cost budgets set --scope cluster --scope-id my-cluster --name "my-cluster" --amount 1500 --currency eur
ankra cost budgets list
ankra cost autopilot get
```

```bash theme={null}
ankra cost budgets set --scope project --scope-id payments --name "payments" --amount 4000 --currency eur
```

Every member can read budgets and the autopilot policy. Changing a budget needs the `billing.manage` permission; changing the autopilot also needs `clusters.write`. Ankra's AI uses `get_cost_budgets`, `set_cost_budget`, `get_cost_autopilot` and `update_cost_autopilot`.

> [!WARNING]
>
> **Closed beta.** The portal Cost tabs do not show budgets or the autopilot yet; use the CLI, the API or Ankra's AI. A new Cost page that shows them (under **Autopilot** and **Signals & policy**) is in closed beta and enabled per organisation on request. When it is on, a banner on the Overview, Savings and Clusters tabs links to it. [Contact support](/platform/support) to have it turned on for your organisation.

**Next:** stop idle clusters on a schedule with [power schedules](/platform/cluster-power-schedules).


# Cluster Mesh
Source: https://docs.ankra.ai/platform/cluster-mesh

Connect Kubernetes clusters with Cilium ClusterMesh over the Ankra WireGuard overlay

When a service runs in one cluster and its callers run in another - a second region, a second provider, an on-prem site - you normally have to expose it publicly or build your own VPN between the clusters. Cluster Mesh connects two or more of your clusters into one Cilium ClusterMesh instead: pods reach pods across clusters, and a global service resolves to healthy backends wherever they run, over an encrypted WireGuard overlay Ankra manages.

## Overview

A mesh is an organisation-level object with clusters as members. When a cluster joins, Ankra handles the whole configuration: it creates the mesh's shared certificate authority on the first join and hands it to every member, updates each member's Cilium with its mesh identity and peer list, deploys the `clustermesh-apiserver`, and gives every node a WireGuard peer, and a route, for every node of every other member. Nothing about the mesh requires exposing your Kubernetes API or pod network to the internet: peers talk through the platform overlay.

What you can do with a connected mesh:

* **Global services**: annotate the same Service in two clusters with `service.cilium.io/global: "true"` and requests resolve to healthy backends in either cluster.
* **Cross-cluster pod traffic**: pods reach pod IPs in other members directly.
* **Network policy across clusters**: Cilium policies can select peers in other members by cluster name.

Watch two clusters in two countries joined into one network.

[Cilium ClusterMesh on Ankra: two clusters, two countries, one network](https://www.youtube-nocookie.com/embed/WWZU-NhHwXs?rel=0)

## Requirements

Mesh requirements fall into three groups, and the group a requirement is in tells you what to do about it: one group is settled when the cluster is built, one is fixable on a running cluster, and one is about the clusters you mesh *together* rather than any one of them.

### Settled when the cluster is built

These four are baked into a cluster and no operation changes them. A cluster that fails any of them can only mesh if you rebuild it.

| Requirement | Accepted today | Why |
| - | - | - |
| **Provider** | UpCloud, Proxmox | The clouds wired to the platform WireGuard overlay. |
| **Distribution** | kubeadm | Only kubeadm renders the mesh identity into the control plane. |
| **CNI** | Cilium | ClusterMesh is a Cilium feature. |
| **Networking** | Created with networking on (the default) | The platform's networking stack is what renders the mesh into the cluster's Cilium release. A cluster created with `--include-networking=false` has no Cilium release the platform manages, so the mesh values have nowhere to land. |

Readiness reports the provider and distribution under its `platform` check, the CNI under `cni`, and the managed Cilium release under `cilium_stack`, each marked not remediable.

### Fixable on a running cluster

A cluster that clears the four above is *mesh-capable*, which is not the same as ready. Two more things must be true, and both can be arranged in place with [make-ready](#make-an-existing-cluster-mesh-capable):

* **A Cilium cluster identity.** An id in the range 1 to 255, and a name unique across the mesh. Clusters created while the WireGuard overlay was enabled for your organisation already have one. Anything older gets one allocated by `make-ready` on the running cluster.
* **A routable node network.** A mesh forwards pod traffic to remote node addresses, so nodes on a per-cluster private network nothing else reaches can never carry it. One of three networks qualifies: the platform WireGuard overlay (`--network-mode wireguard_mesh`), Proxmox's EVPN network, or a tailnet the nodes advertise.

`make-ready` itself needs the cluster to be **online**. A cluster still provisioning would race its own create jobs, and one mid-update could interleave with the update in flight, so wait for it to settle. Proxmox clusters additionally need `--site-public-ip` (see [Proxmox sites](#proxmox-and-on-prem-sites)).

> [!NOTE]
>
> One case `make-ready` cannot serve: an older cluster whose network identity was allocated without an overlay range. `make-ready` refuses it with that reason rather than half-preparing it. [Contact support](/platform/support) if you need such a cluster in a mesh.

### Requirements across the members

These are properties of a mesh, not of a cluster, so they can only fail once you try to put two particular clusters together.

* **No overlapping pod ranges.** The pod CIDR of every member must be disjoint from every other member's: a mesh routes pod traffic between members by pod address. Service ranges may overlap - a ClusterIP is resolved inside the cluster that owns it and never crosses to a peer - so the kubeadm default service range is fine. Clusters created while the overlay is enabled draw disjoint pod ranges from your organisation's pools automatically, and the platform keeps pod ranges unique across the organisation. Two clusters built before the overlay both run the kubeadm default pod range, so `make-ready` on the second one is refused by name, and moving a running cluster onto a fresh range is disabled for now (see [Moving a cluster onto a fresh pod range](#moving-a-cluster-onto-a-fresh-pod-range)) - so that pair cannot mesh with each other yet.
* **Unique Cilium cluster ids.** Every member holds a different one, which caps a mesh at **255 members**.
* **A routable path per pair.** Connecting two apiservers is not enough. Ankra resolves each pair to one address family and refuses pairs with no route (see [How members connect](#how-members-connect)). In short: two clusters in *different* provider accounts must **both** be on the WireGuard overlay, and a Proxmox EVPN cluster meshes only with clusters on the same Proxmox credential.
* **Each member publishes an apiserver address.** A member publishes one once the platform has recorded its nodes, so this is not checked before a join (it would refuse a cluster that is minutes from ready). It is checked afterwards, and a member nobody can reach is reported rather than left silently unconnected.
* **One mesh per cluster.** A cluster belongs to at most one mesh; joining a second is refused.

### On the platform side

* **Permissions.** Reading meshes and running readiness needs `clusters.read`; creating a mesh, joining, leaving and `make-ready` need `clusters.write`. Both are checked at *organisation* scope, because admitting a cluster changes the configuration every other member runs with.
* **A fixed NodePort.** Every member publishes its `clustermesh-apiserver` on NodePort **32379**, the same across the fleet so a peer needs only an address to dial one. Keep it free, and let it through any firewall between members.
* **MTU is pinned to 1420** on mesh members, matching the overlay. Cilium's VXLAN rides inside the overlay's WireGuard frame, and a member configured above that black-holes pod traffic *between* clusters while everything inside each cluster keeps working.
* **Cilium's own encryption is off** on mesh members, deliberately. Every transport the mesh uses already carries packets encrypted, so Cilium's WireGuard layer would encrypt a second time and shrink the MTU again for no gain.
* **The shared trust root comes first.** A member's mesh configuration is held back until its agent confirms the mesh certificate authority is installed. Without that, Cilium would create a certificate authority of its own, and the member would present a certificate no peer trusts while reporting a healthy mesh.

### Where the Cluster Mesh section appears

A cluster's sidebar carries a **Cluster Mesh** entry when Cluster Mesh is enabled for the organisation **and** that cluster can actually use it: it is already a mesh member, or it is *eligible*, meaning it can join now or after a `make-ready`. A cluster that fails one of the settled-at-build requirements has no entry, because nothing you could do from that page would change the answer. The organisation-level **Cluster Meshes** page lists every mesh regardless and stays reachable from the main menu.

Eligibility is exactly what readiness reports, so the API and the CLI answer the same question the sidebar does:

```bash theme={null}
ankra cluster mesh readiness <cluster-id>
```

## Connect two clusters

**1. Check readiness**

```bash theme={null}
ankra cluster mesh readiness <cluster-a> <cluster-b>
```

Each cluster is reported `ready`, or every failing check is spelled out, including which failures are fixable on a running cluster and which are settled when the cluster is built.

**2. Create the mesh and join both clusters**

```bash theme={null}
ankra cluster mesh create production-mesh
ankra cluster mesh join <mesh-id> <cluster-a>
ankra cluster mesh join <mesh-id> <cluster-b>
```

**3. Watch it converge**

```bash theme={null}
ankra cluster mesh show <mesh-id>
```

The mesh and its members move `pending → configuring → ready` as the agents prove each step: identity installed, shared trust root in place, every expected peer connected. A healthy pair usually converges within 5 to 15 minutes.

### What the statuses mean

| Status | Meaning |
| - | - |
| `pending` | Nothing dispatched to the cluster yet. |
| `configuring` | Mid-flight: the resource is rolling out, the trust root is not yet confirmed, or the peer list has not reached every member. Not an error. |
| `ready` | The member's agent verified a connection to every expected peer. |
| `degraded` | The member verified fewer connections than it expects, so a peer is unreachable. |

Statuses are derived from what each cluster's agent actually reported, never from what the platform intended, so `ready` means the connection was proven from inside the cluster.

## Make an existing cluster mesh-capable

A cluster created without `--network-mode wireguard_mesh` (or before the overlay existed) can be made mesh-capable in place, with nothing deleted or recreated:

```bash theme={null}
ankra cluster mesh make-ready <cluster-id>
# Proxmox clusters:
ankra cluster mesh make-ready <cluster-id> --site-public-ip <address>
```

`make-ready` allocates the cluster's Cilium identity and an overlay range, keeps the pod and service ranges the cluster already runs, and sets its nodes converging onto the overlay: each node installs WireGuard and joins the overlay through its own update job, the node IP switches to the overlay address, and Cilium re-renders with the identity. A cluster's status view carries an `overlay_nodes` item while nodes are still joining, naming how many are left.

> [!WARNING]
>
> Zero disruption is not possible: switching node IPs restarts each kubelet once. Plan it like a rolling node operation. Everything else stays: workloads, data, and the addresses your Services expose.

### Moving a cluster onto a fresh pod range

> [!WARNING]
>
> Moving a running cluster onto a different pod range is **disabled**. `make-ready` refuses it: kube-controller-manager exits at start while any node still holds a range outside `--cluster-cidr`, so the move takes the cluster's controllers down instead of renumbering it. Two clusters that both run the kubeadm default pod range cannot mesh with each other yet.

Two clusters built before the overlay both run the kubeadm default pod range, and pod ranges must be disjoint across a mesh, so the platform keeps them unique per organisation: `make-ready` on the second such cluster is refused by name, and there is no renumber to fall back on for now.

The one range `--pod-cidr` still accepts is the kubeadm default `10.244.0.0/16`, which puts a cluster an earlier renumber moved off it back onto the range its nodes run:

```bash theme={null}
ankra cluster mesh make-ready <cluster-id> --pod-cidr 10.244.0.0/16
```

That records the range on the identity and stamps it onto every node, and each control plane updates the settings that carry the range in place (the kubeadm configuration, the controller-manager's `--cluster-cidr`, kube-proxy's `clusterCIDR`). No node is drained, because every node already runs the range. A node whose range lags the definition reads as `network=pod_cidr_drift` until its update job has converged it.

`make-ready` refuses, with the reason, clusters it cannot serve: providers not yet wired to the overlay, non-kubeadm distributions, non-Cilium CNIs, Proxmox clusters without a site address, a default pod range another cluster of the organisation already recorded, and any pod range that would move a running cluster off the one it runs.

### The whole path in one command

`ankra cluster mesh up` runs the path above for a set of clusters: it reads their readiness, runs `make-ready` on every cluster that only lacks its identity or the overlay, joins every cluster that is ready, creates the mesh when none of that name exists, and keeps passing until every member reports `ready` or `--wait` runs out. It changes nothing with `--plan`.

```bash theme={null}
ankra cluster mesh up my-mesh <cluster-a> <cluster-b> <cluster-c> --plan
ankra cluster mesh up my-mesh <cluster-a> <cluster-b> <cluster-c>
```

`--renumber-pods` asks `up` to move every colliding cluster after the first onto a fresh pod range. That move is disabled for now, so the request is refused: a set whose clusters share a pod range cannot be brought up as one mesh yet.

## How members connect

Ankra resolves each *pair* of members to one address family, taking the first that fits:

| Family | When it applies | Routes pod traffic? |
| - | - | - |
| **Overlay** | Both members are on the platform WireGuard overlay and advertise overlay addresses. | Always. The mesh peering installs a WireGuard peer, and a route, for every remote node. |
| **Utility** | Both members were created from the same provider credential, so they share the provider's account-wide network (UpCloud's utility network, Proxmox's EVPN vnet). | Yes, as long as both have a routable node network. |
| **Tailnet** | Both members advertise tailnet addresses. | Only if both really are on the tailnet. |
| **Public** | Nothing else fits. | Only if both members are on the WireGuard overlay, which is what turns a public endpoint into a routable node address. |

The overlay wins over the others on purpose: it is the one network the mesh itself makes routable between two members, so it works across accounts, providers and sites alike.

Two consequences worth knowing before you plan a mesh:

* Two clusters in **different provider accounts** mesh only if **both** are on the WireGuard overlay. Otherwise their apiservers might connect while pod traffic has nowhere to go, which is why Ankra refuses the pair outright instead.
* A **Proxmox** cluster on the EVPN network has nothing that turns a public endpoint into a routable node address, so it meshes only with clusters on the **same Proxmox credential**.

The `clustermesh-apiserver` is reached inside the tunnel on the peer's overlay address, so nothing about a mesh requires exposing your Kubernetes API or pod network to the internet.

## Proxmox and on-prem sites

Proxmox nodes sit on a private SDN with no public addresses, so a Proxmox cluster publishes one **site gateway**: its bastion, reached through the site's public address on a mapped UDP port range.

A Proxmox site needs, once:

1. **A public address** for the site, passed as `--site-public-ip` at create or make-ready.
2. **A UDP port-range forward** on the site's edge to the Proxmox host, and on the host to the cluster's bastion: `51820-52074`. The platform maintains the per-node port mapping on the bastion itself.
3. **Jump access for the platform**: the credential's jumphost must allow TCP forwarding to the bastion's dial address (the `permitopen` list of the platform's key).

One reachable side is enough to bring tunnels up, because the unreachable site initiates outbound and the tunnel is held open with keepalives, but forwarding both sites is more robust.

> [!NOTE]
>
> Sites behind NAT in both directions still mesh, as long as at least one site's UDP range is reachable from the other.

## Try it: a global service

Deploy the same Service in both clusters, backends wherever you like:

```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: echo
  namespace: demo
  annotations:
    service.cilium.io/global: "true"
spec:
  selector:
    app: echo
  ports:
    - port: 80
```

A pod in either cluster that resolves `echo.demo` is served by healthy backends from both. Remove the deployment on one side and traffic shifts to the other. To prove cross-cluster traffic step by step before you rely on it, follow [Verify a Cluster Mesh](/guides/cluster-mesh-verification).

## Leaving and deleting

```bash theme={null}
ankra cluster mesh leave <mesh-id> <cluster-id>   # tears down the member's mesh config, re-renders the rest
ankra cluster mesh delete <mesh-id>               # only when empty
```

A mesh with members cannot be deleted out from under them. Remove the members first so their configuration is torn down deliberately.

## Network ranges and their limits

Every cluster Ankra builds for your organisation - on Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, AWS EC2, Proxmox, HPE Morpheus or Ankra Cloud - gets its own network identity from your organisation's address pools when it is created: a Cilium cluster id, a pod range, a service range and an overlay range. Because no two of your clusters share a range, any two of them can join a mesh later without being renumbered. Whether or not you ever build a mesh, the identity sets two limits:

| Limit | Default | Why |
| - | - | - |
| Ankra-built clusters in the organisation at once | 32 | The pod pool, `10.216.0.0/13`, is carved into one `/18` per cluster. |
| Nodes in one cluster, control planes included | 64 | Kubernetes gives every node a `/24` out of its cluster's pod range, and a `/18` holds 64 of them. |

Imported clusters and provider-managed clusters (DOKS, GKE, AKS, EKS and the others) take no identity and do not count. Deleting a cluster returns its ranges to the pool. A cluster created before your organisation had a network identity keeps its distribution's default `/16` pod range and holds 256 nodes.

What happens at a limit:

* **A create past the cluster limit** is refused with `409` and "No cluster network range is free in this organisation", naming the pool. Deprovisioning a cluster you no longer need frees a range.
* **A create that plans more nodes than its range holds** is refused with `409` before anything is provisioned. The count is the control planes plus every node group's count, or its autoscaling maximum where autoscaling is on. The message names the range, the limit and the count you asked for.
* **A scale-up past the node limit** is refused the same way: adding a node group, scaling one up, raising an autoscaling maximum, and a scale-up the [cluster autoscaler](/guides/cluster-autoscaling) asks for. No server is created, and the autoscaler backs off. Without this, a node past the limit would join the cluster and never become Ready.

**Raising the limits.** A running cluster's pod range cannot be widened in place (see [Moving a cluster onto a fresh pod range](#moving-a-cluster-onto-a-fresh-pod-range)). If you need a cluster with more than 64 nodes, or more than 32 Ankra-built clusters at once, [contact support](/platform/support) before you create them. Ankra can change how your organisation's pool is divided for clusters created from then on: larger ranges for fewer clusters (128 nodes each, 16 clusters) or smaller ranges for more clusters (32 nodes each, 64 clusters). Clusters you already run keep their ranges.

## Troubleshooting

* **A member sits in `configuring`**: the agent has not yet confirmed the trust root or a verify has not run; check the cluster is online and its operations list for the mesh resource. Ankra retries every five minutes, and sends the trust root again to a member whose agent has not confirmed it within fifteen minutes. A cluster created with networking off can never leave `configuring` - readiness refuses it under `cilium_stack` before the join, and the fix is a cluster created with networking on.
* **A member goes `degraded`**: it verified fewer peers than expected. Check the peer cluster's health first, then the site path (UDP forward, site address) if the pair crosses sites.
* **A readiness check is marked not remediable**: for the provider, the distribution and the CNI that is final, and a new cluster is the only fix. For the identity and the node network, `make-ready` is the fix and readiness marks them remediable. A pod range that overlaps a member's is not remediable either while moving a running cluster onto a fresh range is disabled.
* **`make-ready` says the pod range is already recorded by another cluster**: another cluster of the organisation was prepared from the same kubeadm default first. Moving this one onto a fresh range is disabled for now, so the two cannot mesh with each other yet.
* **A member's status view shows `overlay_nodes` not ready**: some nodes have not joined the WireGuard overlay yet. Their update jobs put them on it - retry a failed one from the cluster's operations, or run `make-ready` again to set them converging.
* **A node reads `network=pod_cidr_drift`**: the range recorded for the cluster and the range the node runs differ. While the move is disabled, the node's update job converges a control plane's pod-range settings onto the range the nodes already run and refuses to move a node off the range it holds, naming the node and its range in the job's output. The output also says when a control plane has not converged the range yet.
* **LoadBalancer Services on a meshed UpCloud cluster**: node addressing changes on the overlay; see the [UpCloud guide](/guides/upcloud-clusters) for the current behaviour of provider load balancers on meshed clusters.

## Next steps

* [Verify a Cluster Mesh end to end](/guides/cluster-mesh-verification): a five-minute test that serves one cluster's pods to a client in the other.
* [`ankra cluster mesh` CLI reference](/reference/cli/cluster#ankra-cluster-mesh)


# Cluster Metrics
Source: https://docs.ankra.ai/platform/cluster-metrics

Visualize real-time CPU, memory, network, and disk metrics for your Kubernetes clusters.

> [!NOTE]
>
> The Cluster Metrics page provides real-time visualization of your cluster's resource usage. Metrics work out of the box: the Ankra agent ships node and pod metrics to the platform. Connecting your own Prometheus is optional, for deeper queries.

## Overview

Ankra's metrics visualization helps you understand your cluster's health and resource consumption at a glance. View CPU usage, memory consumption, network throughput, disk I/O, and pod restart patterns, all from a single dashboard.

***

## Accessing Cluster Metrics

1. Navigate to your cluster from the sidebar.
2. Click **Metrics** in the cluster navigation.
3. View real-time charts and summary cards.

> [!NOTE]
>
> Built-in platform metrics need no setup and take precedence while they are healthy for the cluster. A connected Prometheus stays available as the deep-dive path - see [Prometheus Integration](/integrations/prometheus).

***

## Summary Cards

At the top of the metrics page, summary cards show current resource utilization:

| Card | Description |
| - | - |
| **CPU Usage** | Current CPU utilization vs total capacity |
| **Memory Usage** | Current memory consumption vs total capacity |
| **Network Rate** | Combined inbound and outbound network throughput |
| **Pod Status** | Running pods vs total pod count |

These cards provide instant visibility into cluster health without scrolling through detailed charts.

***

## Metrics Charts

### CPU Usage

Visualize CPU consumption across your cluster nodes over time.

**What it shows:**

* Per-node CPU usage lines
* Total cluster CPU trend
* Usage patterns over the selected time range

**Use cases:**

* Identify nodes with consistently high CPU usage
* Spot CPU spikes that correlate with deployments or traffic
* Plan capacity based on usage trends

### Memory Usage

Track memory consumption across your cluster.

**What it shows:**

* Per-node memory usage
* Memory pressure indicators
* Historical memory trends

**Use cases:**

* Detect memory leaks in applications
* Identify nodes approaching memory limits
* Plan memory allocation for new workloads

### Network I/O

Monitor network traffic flowing in and out of your cluster.

**What it shows:**

* **Receive**: Inbound network traffic per node
* **Transmit**: Outbound network traffic per node
* Throughput rates in bytes/second

**Use cases:**

* Identify network-intensive workloads
* Detect unusual traffic patterns
* Monitor data transfer costs

### Disk I/O

Track disk read and write operations across nodes.

**What it shows:**

* Disk read throughput
* Disk write throughput
* I/O patterns per node

**Use cases:**

* Identify storage bottlenecks
* Monitor database disk activity
* Plan storage capacity

### Pod Restarts

Monitor pod restart frequency to detect stability issues.

**What it shows:**

* Pod restart counts over time
* Restart patterns by namespace or workload
* Correlation with other events

**Use cases:**

* Detect crashlooping pods
* Identify unstable deployments
* Troubleshoot OOMKilled containers

***

## Time Range Selection

Control the time window for metrics data:

| Range | Use Case |
| - | - |
| **Last 15 minutes** | Real-time monitoring |
| **Last hour** | Recent activity review |
| **Last 6 hours** | Shift-based monitoring |
| **Last 24 hours** | Daily patterns |
| **Last 7 days** | Weekly trends |
| **Custom** | Specific time windows |

### Changing Time Range

1. Click the **Time Range** picker in the top-right corner
2. Select a preset range or define a custom window
3. Charts automatically update to show the selected period

***

## Auto-Refresh

Keep metrics up-to-date with automatic refresh:

| Interval | Description |
| - | - |
| **Off** | Manual refresh only |
| **10 seconds** | Near real-time updates |
| **30 seconds** | Balanced refresh rate |
| **1 minute** | Low-overhead monitoring |
| **5 minutes** | Background monitoring |

### Manual Refresh

Click the **Refresh** button at any time to fetch the latest data immediately.

***

## Connecting your own Prometheus (optional)

Connect a Prometheus you already run when you want queries beyond the built-in metrics.

**1. Have a Prometheus to connect**

Use an existing Prometheus, or deploy one to your cluster with a stack using the `kube-prometheus-stack` add-on.

**2. Configure the data source**

Go to cluster **Settings** → **Integrations** → **Metrics** and enter your Prometheus URL.

**3. Test Connection**

Verify the connection is successful before saving.

### Default Prometheus URL

If using `kube-prometheus-stack` deployed via Ankra:

```
http://kube-prometheus-stack-prometheus.prometheus.svc:9090
```

***

## Troubleshooting

### No metrics shown

**Cause:** Built-in metrics come from the Ankra agent, so they stop when the agent is offline or its metrics collection has been turned off (`metrics_collect.enabled` in the [agent Helm values](/reference/agent-helm-values)).

**Solution:**

1. Check the agent is online in cluster **Settings** → **General**
2. Or connect your own Prometheus under **Settings** → **Integrations** → **Metrics**

### "Unable to Load Metrics"

**Cause:** Connection to Prometheus failed.

**Solutions:**

* Verify Prometheus is running in your cluster
* Check the Prometheus URL is correct
* Ensure network connectivity between the Ankra agent and Prometheus
* Review Prometheus service account permissions

### Missing Data for Some Metrics

**Cause:** Prometheus may not be scraping all required metrics.

**Solutions:**

* Verify `node-exporter` is deployed for node metrics
* Check `kube-state-metrics` is running for Kubernetes metrics
* Review Prometheus scrape configurations

***

## Related

> [card] [Prometheus Integration](/integrations/prometheus)
>
> Set up Prometheus for your cluster.

> [card] [Alerts](/guides/alerts)
>
> Configure alerts based on metrics.

> [card] [Cluster Settings](/platform/cluster-settings)
>
> Configure metrics data sources.

> [card] [AI Assistant](/platform/ai-assistant)
>
> Use AI to analyze performance issues.


# Nodes
Source: https://docs.ankra.ai/platform/cluster-nodes

Every machine behind a cluster - what the provider runs and what Kubernetes reports - with node groups, the control plane and the bastion, and the controls for each

> [!NOTE]
>
> The Nodes section answers "what machines is this cluster made of, and what can I do to each of them?" - the infrastructure view. **Kubernetes → Nodes** stays the view of the node *objects* Kubernetes keeps; the two link to each other.

## Accessing the section

Open a cluster and click **Nodes** in the sidebar, directly above **Kubernetes**. The section has up to four tabs, depending on what Ankra manages for the cluster:

| Cluster | Tabs |
| - | - |
| Provisioned by Ankra on a cloud account (Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, AWS EC2, Proxmox VE, HPE Morpheus) | Overview · Node groups · Control plane · Bastion & VMs |
| Managed Kubernetes (EKS, AKS, GKE, DOKS, UKS, OVH MKS, Kapsule) | Overview · Node pools |
| Imported, or a playground | Overview |

Node management used to live under **Settings → Nodes**; that tab is gone and its address now opens the **Node groups** tab, so older links keep working.

***

## Overview

### Stat tiles

**Machines** counts every server Ankra runs for the cluster by role - control plane, workers, bastion. **Kubernetes ready** is ready over total nodes as the kubelets report them, with the cordoned count beside it. **vCPU** and **Memory** sum node capacity; **GPUs** counts what device plugins advertise. **Run rate** is the projected monthly cost from the cluster's cost read, with how many nodes it covers.

A figure the platform cannot read says so - *No nodes reporting*, *Not priced* - rather than showing zero. A cluster whose agent is offline is not an empty cluster.

### The Machines table

One row per machine, joining what the cloud provider knows about the VM with what Kubernetes knows about the node. The join is by name (Ankra names the VM and the kubelet the same), with the private address as the fallback.

* **Machine** - name and role.
* **Group** - the node group the machine scales in.
* **Instance** - the instance type, with vCPU, memory, disk and list price from the provider's live catalog, and a **GPU** chip when the node carries GPU feature-discovery labels (`1 × NVIDIA H100 80GB HBM3`).
* **Kubernetes** - `Ready`, `Cordoned` or `Not ready` from the node object, with the kubelet version. A VM without a node object reads **Not joined** (a worker that has not registered yet) or **Not a node** (the bastion). Neither is rendered as a failure: a machine Kubernetes has never seen is not a machine Kubernetes reports as broken.
* **VM** - the provider's state and power state.
* **Location** and **Addresses** - private and public.

The **⋯** menu on a row holds what applies to that machine:

* **Cordon** / **Uncordon** and **Drain** - on any machine with a node object. Drain cordons the node and evicts its pods, with progress shown until it completes; pods without a controller are not recreated.
* **Restart VM** - reboots the server at the provider (an operation you can follow under **Operations**). Workloads on the node are briefly unavailable.
* **Resize bastion** - on the bastion row.
* **Open in Kubernetes** - the node's page under **Kubernetes → Nodes**, with capacity, conditions, pods, GPU telemetry and the manifest.
* **Machine details** - the provider record, resource definition and reconciler data.

On an imported cluster the table shows the Kubernetes side only - Ankra does not provision those machines - and cordon, uncordon and drain still apply.

***

## Node groups

Each card is one node group: instance type, count, autoscaling bounds, labels and taints, with the same controls the settings tab offered - scale, switch autoscaling on or off and set its range, move to an equal-or-larger instance type, edit labels and taints, delete the group. **Add node group** opens the size picker with live availability and prices. On UpCloud the picker reads the cluster's own plan catalog, so GPU plans appear with their accelerator fit (`1x L40S`) and the price of the cluster's zone; discontinued plans stay selectable but are labelled **Legacy**.

On UpCloud a node group's plan is changed in place only within its plan family: STARTER, DEV, PREMIUM, GPU, or the unprefixed general-purpose plans such as `4xCPU-8GB`. Moving a group to a plan from another family replaces each node instead - it is drained, deleted and re-provisioned with the new plan, and its workloads run elsewhere until the replacement joins - and the resize says so in its result. The control plane cannot be replaced that way, so a cross-family change there is refused with the alternative named.

### Max out

Under each group that is not autoscaled, **Max out** sizes the group to the most your cloud account still has room for. Ankra reads the account's quota through the cluster's credential and takes the tightest of three bounds:

* remaining **servers** in the account,
* remaining **vCPUs** divided by the instance type's vCPUs,
* remaining **memory** divided by the instance type's memory,

capped at the 100-node group limit. The control names the bound and the added cost at list price before you confirm, and the scale itself is an operation you can follow. The answer has three states and all three are shown: a known maximum, **at max** when the quota is spent, and **unavailable** when the provider does not expose its limits or the instance type's specs are not known - it never offers 100 on a guess.

For an autoscaled group the autoscaler owns the count; raise its maximum on the card instead.

The same report is available on the API as `GET /org/clusters/{provider}/{cluster_id}/quotas` (and under `/api/v1`), alongside the credential-scoped `GET /org/credentials/{provider}/{credential_id}/quotas`.

***

## Control plane

The controller count (1 or 3, and 1, 3 or 5 on Proxmox VE - etcd needs an odd number of voting members) and the controllers' instance type, each with what a change involves for the running cluster (offline, rolling, or live with API downtime) or why it is refused right now.

Growing the count happens **live**: the new controllers provision and join the running cluster without downtime, and a cluster that reaches three controllers can change its instance type live as well, one controller at a time. Reducing the count is applied **offline** - stop the cluster (the stop preserves its state and the start restores it, see [Stop cluster](/platform/cluster-settings#stop-cluster)), apply the change, then start it.

The instance type of a single controller on a running Hetzner cluster can be changed in place: the Kubernetes API is down for a few minutes while the server reboots on the new type, workloads on the workers keep running, and the review dialog asks you to accept the downtime with **Resize with API downtime**. On other providers a single controller is resized offline: stop the cluster, change the type, then start it. See [Change the control plane instance type](/guides/operate-ankra-managed-clusters#change-the-control-plane-instance-type) for the three modes and the CLI and API equivalents.

***

## Bastion & VMs

The bastion is the one machine with a public address: every SSH hop into the cluster and the private network's egress go through it. The tab shows its name, instance type, addresses, location, VM state, and the health verdict the scheduler last recorded, with:

* **Diagnose over SSH** - runs the bastion diagnosis and shows the report inline.
* **Restart VM** and **Resize** - the same controls as the machines table.

### Standalone VMs

A standalone VM is a machine on the cluster's network that is not a Kubernetes node - a database host, a build box, a jump host of your own. Ankra provisions it the way it provisions the bastion: on the cluster's private network, with the cluster's SSH keys, and it is reachable the moment it is reported **up**. It is never joined to Kubernetes, never made a gateway, and - unlike the nodes and the bastion - it **keeps running when the cluster is stopped**, because it carries your own state.

**Add VM** takes a name (lowercase letters, digits and hyphens), a size from the provider's live catalog with its price, a location (the bastion's unless you change it), and whether the machine gets a **public address**. Without one it is private-network only: reach it over the bastion, exactly like a node (`ssh -J` with the material under **Settings → Access**). With one it has its own address and key-only SSH. The provider-side server is named `<cluster>-vm-<name>`.

Each VM row shows its size, addresses and state, and its menu offers **Restart VM**, **Resize** (powered off, moved to the new size, started again - the disk is kept) and **Remove** (deletes the server and its disk; there is no undo). The machines table on the overview lists VMs too, with the role **VM** and the Kubernetes column reading *Not a node*.

Standalone VMs are available on Hetzner, UpCloud, DigitalOcean, OVH and Proxmox clusters. Addressing follows each provider's rules: on DigitalOcean a cluster without a NAT gateway gives a private VM a public address anyway, because a private droplet there would have no path to the internet; on OVH a private VM routes out through the gateway exactly like a node; on Proxmox every VM lives on the cluster's SDN fabric and its private address is its address. On other providers the tab says so rather than offering a control that does nothing.

The bastion and every standalone VM are metered into the cluster's cost. The run rate on the overview includes them, and the breakdown shows them as **Bastion & VMs** - a row that belongs to the whole cluster, so it lands under *unallocated* rather than in any namespace.

On the API: `GET`/`POST /org/clusters/{provider}/{cluster_id}/vms`, `DELETE .../vms/{vm_id}`, `PUT .../vms/{vm_id}/instance-type`, and the same under `/api/v1` with `?wait=false` for asynchronous writes.

***

## Playground size

On a playground the overview carries the **Playground size** card. A paid playground picks a new size from the list; the card names the direction and the monthly difference before anything changes - *Upgrade to Medium: +€2.85/mo* - and the button reads **Upgrade** or **Downgrade**. The resize changes the namespace quota and the price, billed pro-rata across the change, and touches nothing you deployed. The free trial has one fixed size; its card offers **Upgrade to a paid size**, which orders a second, paid playground at the size you pick.

***

## CLI

`ankra cluster get nodes` lists the Kubernetes nodes and `ankra cluster describe node <name>` describes one. The CLI commands for node groups, the control plane, restarts and the bastion are on [Operate an Ankra Managed Cluster](/guides/operate-ankra-managed-clusters).


# Stop, Start and Power Schedules
Source: https://docs.ankra.ai/platform/cluster-power-schedules

Stop a cluster Ankra provisioned to stop paying for its compute, start it again with its state, and schedule both so idle environments park themselves.

A development or test cluster that runs all night and all weekend costs money while nobody uses it. You can stop it to release its compute, start it again when you need it, and let power schedules do both on a timetable - for example stop at 19:00 on weekdays and start again at 07:00.

Stop, start and power schedules are available for clusters Ankra provisions on Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, AWS EC2, Proxmox VE and HPE Morpheus. Plain imported clusters cannot be stopped. Managed Kubernetes clusters that support it have their own stop and start at the provider, without schedules - see [Managed Kubernetes](/guides/managed-kubernetes#stopping-and-starting).

***

## Stop and start a cluster

**Stop cluster** and **Start cluster** are in the **Danger Zone** of the cluster's **Settings** → **General**, and in the cluster's **⋯** menu on the clusters list and the cluster overview. Stop is offered while the cluster is running and Start while it is stopped. Both open a dialog where you type the cluster name to confirm.

### What a stop does

It depends on the provider:

| Provider | Default stop | What survives |
| - | - | - |
| Hetzner, OVHcloud, UpCloud, DigitalOcean, Proxmox VE, HPE Morpheus | Captures the cluster's state, then terminates the virtual machines | The state snapshot, cloud block volumes, and everything Ankra holds (cluster record, credentials, stacks, configuration history) |
| Scaleway, AWS EC2 | Powers the servers off and keeps them with their volumes | Everything on the servers; retained storage, gateways and addresses keep billing |

**The state snapshot.** On the terminating providers Ankra first captures an encrypted etcd snapshot, for k3s and kubeadm clusters, and stores it in your [backup vault](/concepts/backup-vaults), or in an Ankra-managed default vault when you have registered none. The virtual machines are terminated only once the snapshot is stored. The capture runs as a **Cluster State Snapshot** operation; if it fails, the cluster stays running and nothing is torn down.

**Preserve cluster state (recommended)** is ticked in the dialog. Untick it (CLI `--preserve-state=false`) to tear down without a snapshot: Secrets, ConfigMaps, custom resources and the bindings between claims and volumes are then lost, and only what Ankra deploys from its own configuration comes back. A forced stop (CLI `--force`) never captures.

**Pause instead of tearing down.** On k3s clusters on Hetzner, UpCloud and DigitalOcean, choose **Pause** instead of **Tear down (default)** (CLI `--mode pause`). The servers are powered off and kept with their disks, so etcd, local data and node identities survive, and a start powers them back on. The trade-off is cost: these providers bill a powered-off server in full, so a pause saves no compute cost. Pause takes no snapshot and cannot be combined with `--force`.

A stop never deletes the cloud block volumes behind PersistentVolumes, forced or not; they keep billing while the cluster is stopped. Only terminating the cluster deletes them - see [Persistent volumes](/platform/cluster-settings#persistent-volumes).

### What a start does

**Start cluster** re-provisions the saved topology: **Everything** (control plane and workers) or **Control plane only**. Ankra creates fresh virtual machines with new IPs and installs Kubernetes. When a snapshot was captured, **Restore the cluster state captured at stop** is ticked: the first control plane resets etcd from it, so your Secrets, ConfigMaps, custom resources and persistent volume claims come back, and StatefulSets reattach their existing cloud disks. A kubeadm control plane also gets its certificate authorities back, so existing tokens and kubeconfigs stay valid. Untick it (CLI `--restore-state=false`) to start a fresh cluster.

Stacks and add-ons configured in Ankra are reconciled either way. The snapshot is kept for as long as the cluster stays stopped. Once the cluster runs again, a restored snapshot is kept for 7 more days. One that was never restored is kept for 90 days from its capture, or for as long as it is the cluster's newest such snapshot from before its last start, its last power outage or the last time Ankra saw one of its control planes stop responding, whichever is longer. The [scheduled snapshots](/guides/kubernetes-upgrades#set-the-retention-window) Ankra takes while the cluster runs follow their own retention window, 7 days unless you set another for the cluster.

On Scaleway and AWS EC2, and after a pause, a start powers the existing servers back on - see [AWS clusters](/guides/aws-clusters#stopping-and-starting-a-cluster).

### From the CLI

Stop and start are per-provider commands:

```bash theme={null}
ankra cluster hetzner stop my-cluster                      # capture state, then tear down
ankra cluster hetzner stop my-cluster --mode pause         # k3s: power off and keep the servers
ankra cluster hetzner start my-cluster                     # restore the captured state
ankra cluster hetzner start my-cluster --scope control_plane
```

The same commands exist under `ovh`, `upcloud`, `digitalocean`, `scaleway`, `aws`, `proxmox` and `morpheus`. See the [CLI reference](/reference/cli/cluster).

***

## Schedule stops and starts

### Park a cluster overnight

The **Power schedules** card on **Settings** → **General** has a **Park overnight** button. Choose the days (**Weekdays (Mon-Fri)** or **Every day**), the **Stop at** and **Start at** times (19:00 and 07:00 by default), the timezone and what happens **When stopping**, then **Create schedules**. It creates one stop schedule and one start schedule.

### Add a schedule

**1. Open the dialog**

On the **Power schedules** card, click **Add schedule**.

**2. Choose the action**

Pick **Stop** or **Start**. Each schedule does one thing; create a pair to stop and start the cluster.

**3. Choose what a stop does**

For a stop, pick under **When stopping**:

* **Delete resources** - deletes the cloud instances, as a manual stop does. On the providers that capture state, keep **Preserve cluster state (recommended)** ticked so the next start restores it.
* **Scale down to 0** - deletes only the worker servers and creates new ones at the next start. The control plane and etcd, cloud volumes and addresses are kept and keep billing. Data on the workers' own disks is lost at every stop, so if the cluster has volumes that keep data there (local-path, hostPath, local PVs) you must tick the acknowledgement.
* **Pause** - k3s on Hetzner, UpCloud and DigitalOcean only. Powers the servers off and keeps them; they keep billing.

**4. Choose when**

Under **Schedule type**, choose **One-off** and set **Run at**, or **Repeated** and pick a **Cadence**: **Every day**, **Weekdays (Mon-Fri)**, **Weekends (Sat-Sun)** with a **Time**, or **Custom cron** with a 5-field cron expression. Repeated schedules run in the **Timezone** you pick, which defaults to your browser's.

**5. Save**

Leave **Schedule enabled** on and click **Add schedule**. The card shows the next run.

A cluster can hold up to 20 schedules. A one-off schedule disables itself after it fires and stays in the list as a record. A repeated schedule re-arms for its next occurrence. For a custom cron, `0 19 * * 1-5` in `Europe/Stockholm` fires at 19:00 Stockholm time, Monday to Friday.

Ankra AI (a card you confirm in chat included), an MCP client or a service-account token can schedule or switch on a **Scale down to 0** stop only on a cluster a person has confirmed is not production: someone chose its **Environment** (when creating the cluster, or later on its **Overview** page) and neither that label nor the cluster's criticality says production; otherwise the write is refused and says why. Schedules you create yourself in the portal, or with the CLI or API on your own token, are not checked.

### Read the schedule list

Each row shows the action, its next run, when it last fired and the outcome of the last run, with a toggle, **Edit** and **Delete**:

| Outcome | Meaning |
| - | - |
| `completed` | The action ran |
| `skipped` | The action was not needed, for example the cluster was already stopped; the reason is shown |
| `deferred` | The cluster was busy or the action failed transiently; the schedule is retrying |
| `failed` | The action did not succeed within the retry window |

### How schedules run

* A scheduled stop behaves like **Stop cluster**, with the mode and state choice the schedule carries.
* A stop is skipped if the cluster is already stopped or being deprovisioned. A start fires only when the cluster is stopped.
* If the cluster is busy or the action fails transiently, the schedule retries every 5 minutes for up to 24 hours, then records `failed`. A repeated schedule still fires at its next occurrence.
* Turning off the toggle keeps the schedule but it never fires; turning it on again arms it for its next occurrence. Disabling or editing a schedule always wins over a retry in flight.

### Manage schedules from the CLI

`ankra cluster power-schedules` works on the active cluster (`ankra cluster select`):

```bash theme={null}
# Park on weekday evenings, back before the morning
ankra cluster power-schedules create --action stop --cron '0 19 * * 1-5' --timezone Europe/Stockholm
ankra cluster power-schedules create --action start --cron '0 7 * * 1-5' --timezone Europe/Stockholm

# One-off stop that only removes the workers
ankra cluster power-schedules create --action stop --at 2026-01-02T19:00:00Z --stop-mode scale_to_zero

ankra cluster power-schedules list
ankra cluster power-schedules update <schedule-id> --action stop --cron '0 20 * * 1-5' --timezone Europe/Stockholm --enabled=false
ankra cluster power-schedules delete <schedule-id>
```

`update` replaces the schedule's action, timing and enabled flag, so restate them; omitting `--stop-mode` or `--preserve-state` keeps the current choice. A `scale_to_zero` stop on a cluster with node-local volumes needs `--accept-node-local-data-loss` when you are not answering the prompt. See the [CLI reference](/reference/cli/cluster).

***

## Next steps

* [Cloud Cost](/platform/cloud-cost) - see what your clusters cost and what parking them saves.
* [Cluster Settings](/platform/cluster-settings) - the rest of the cluster's lifecycle, including terminating it.


# Cluster Settings
Source: https://docs.ankra.ai/platform/cluster-settings

Change how Ankra manages one cluster after it is running - its agent, GitOps repository, data sources, access, audit trail, and moving, disconnecting or deleting it.

Once a cluster is running you still need to keep its agent current, connect its repository and data sources, decide who can reach it, and eventually stop, move or delete it. Cluster Settings is where you do that for one cluster. Open the cluster and choose **Settings** in the cluster sidebar. The sections below follow its tabs: **General**, **GitOps**, **Kubernetes**, **Variables**, **Integrations**, **AI Context**, **Access** and **Audit**.

Node groups, control planes and the bastion are not in Settings: see [Nodes](/platform/cluster-nodes).

***

## General

### Cluster Health

The **Cluster Health** card shows whether the agent is **Online** or **Offline**, when it was last seen, and its version. When a newer agent is available, **Upgrade to \<version>** upgrades it now. Next to it, **Kubernetes Watch** shows whether Ankra's copy of the cluster's resources is **Synced**, **Syncing**, **Stale** or in **Error**; **View Details** opens the per-resource breakdown on the [Kubernetes](#kubernetes) tab. For what the agent does, see [Cluster Agent](/concepts/cluster-agent).

### Agent Settings

Whether Ankra upgrades this cluster's agent for you depends on two switches, and both must allow it:

* **Auto-upgrade Agents** in **Organisation Settings** → **General**. It is on by default for organisations created since 7 September 2026; older organisations turn it on there. While it is off, no cluster in the organisation is upgraded automatically.
* **Disable Auto-upgrade** on this card. Off by default; turn it on to keep this one cluster at its current agent version while the rest of the organisation upgrades.

### Maintenance

* **Generate command** creates a fresh agent installation command. Run it on the cluster to reinstall the agent, or to reconnect it when the agent is offline.
* **Sync All Resources** triggers a full reconciliation: Ankra re-applies the cluster's stacks, add-ons and manifests. Use it after a network outage or after changes made outside Ankra.

### What this cluster is for

Sets how loudly the cluster reports. The scan finds the same issues either way; the level decides how large a problem must be before it opens a ticket and reaches Slack:

| Level | Behaviour |
| - | - |
| **Production** | Reports everything the scan finds |
| **Staging** | Needs a moderately wider blast radius before an issue is treated as critical |
| **Development** | Only issues affecting a substantial share of the cluster are critical |
| **Disposable** | Effectively silent; for demo and throwaway clusters |

The environment picker on the cluster overview sets the same value. When the organisation has proactive AI Insights on, an **AI Insights** card here turns them off or on for this cluster - see [AI Insights](/platform/ai-insights).

### Power schedules

Stops and starts the cluster on a timetable, on the providers that support stop and start. See [Stop, Start and Power Schedules](/platform/cluster-power-schedules).

### Kubernetes Version

Shown for clusters Ankra provisions and for managed Kubernetes. Pick a newer version and confirm. On a cluster Ankra provisioned, Ankra upgrades one node at a time, control plane first, draining each node while respecting PodDisruptionBudgets, and takes an etcd snapshot before the control plane moves; on managed Kubernetes the provider runs the rollout. Downgrades are not supported. **Auto upgrade patch versions** keeps the cluster on the newest patch release of its current minor version; minor versions are never upgraded automatically. See [Upgrade Kubernetes on a Cluster](/guides/kubernetes-upgrades) for clusters Ankra provisioned and [managed Kubernetes](/guides/managed-kubernetes#kubernetes-upgrades) for the rest.

### Archive

**Archive this cluster** parks a cluster that is expected to be offline without disconnecting it: it sends no offline notifications, triggers no offline alerts, and is ignored by fleet health. Unarchive it to resume monitoring.

***

## GitOps

Connect the cluster to a Git repository so its stacks are stored as code: choose a GitHub or [Bitbucket Cloud](/integrations/bitbucket-cloud) credential, then a repository and branch, or create a new repository from the tab. The **Webhook** status shows whether pushes reach Ankra (**Active**, **Pending**, **Failed** or **Not Configured**), with **Retry** when it failed. See [GitOps](/concepts/gitops).

***

## Kubernetes

A table of every Kubernetes resource type Ankra syncs from the cluster, with its status, count, last sync and errors, refreshed every 10 seconds. Search by resource type or status. **Full Sync** re-reads every resource from the cluster, which is what to run when the console shows something that no longer matches the cluster.

***

## Variables

Values that every stack on this cluster can reference. See [Variables](/concepts/variables).

***

## Integrations

Connects the cluster's data sources: **Metrics** (your own Prometheus, see [Prometheus Integration](/integrations/prometheus)), **External Log Viewer**, **Cloud Cost**, **Trivy Operator**, and **Log Source** (see [Log Sources](/integrations/log-sources)). Built-in metrics need none of them - see [Cluster Metrics](/platform/cluster-metrics). SOPS encryption is configured for the whole organisation, not per cluster; see [SOPS Encryption](/guides/sops).

***

## AI Context

Tag repositories that matter to this cluster, each with a short note on why, so Ankra's AI reads them when it works on the cluster. The same tags feed [AI code review](/platform/ai-code-review#what-the-review-reads-beyond-the-diff).

***

## Access

* **Access grants** give organisation members access to this cluster, cluster-wide or to one namespace, enforced by Kubernetes RBAC within about a minute. See [Cluster Access](/guides/cluster-access).
* **Generate kubeconfig** gives you a kubeconfig that reaches the cluster through the Ankra gateway. See [Kubeconfig](/guides/kubeconfig).
* **SSH Access** manages the SSH keys installed on the nodes of clusters Ankra provisions, and shows the commands to reach them through the jump host.

***

## Audit

The **Audit** tab lists every manual action performed on this cluster: lifecycle (create, import, start, stop, upgrade, terminate), scaling and node group changes, node restarts, stack changes, and Helm upgrades and rollbacks. Each entry shows who did it, what it touched, when, and the structured details; when an edit produced a commit in the cluster's GitOps repository, the entry links to it. A change that qualifies as a [pre-approved standard change](/security/change-management) shows **Pre-approved SC-01** (or the matching ID) beside its action; hover over it to see why it qualified.

**View in organisation audit log** opens the organisation [Audit Log](/guides/audit-log) filtered to this cluster. **Export CSV** and **Export JSON** download this cluster's entries, honouring the search on screen. The tab needs the audit read permission, held by owners and admins by default and grantable to [custom roles](/guides/roles-and-access). Entries cannot be edited or deleted.

***

## Danger Zone

The **Danger Zone** card at the bottom of **General** holds the actions that cannot be undone. Which ones appear depends on the kind of cluster.

### Move to another organisation

Imported clusters only. **Move cluster** moves the cluster into another organisation; you must be an admin of both. It keeps its agent, executions, stacks, resources, findings, DNS records and variables. Access grants, role assignments, kube tokens, notification routes, group memberships, links to this organisation's registries and credentials, AI context repositories and the GitOps connection are detached; recreate them in the destination. Billing, the audit trail and support tickets stay with the old organisation.

The move is refused while operations are running, while the cluster is in a cluster mesh or has DNS zones bound to the organisation, and when the destination already has a cluster with that name. The dialog gives the reason. The CLI equivalent is `ankra cluster move <cluster> --organisation <id|slug|name>`.

### Stop cluster

**Stop cluster** and **Start cluster** release and restore the compute of a cluster Ankra provisioned. What a stop keeps depends on the provider; see [Stop and start a cluster](/platform/cluster-power-schedules#stop-and-start-a-cluster). The CLI commands for each provider are in [Operate an Ankra Managed Cluster](/guides/operate-ankra-managed-clusters#stop-and-start).

### Switch the deployment engine

On a cluster still deploying with ArgoCD, **Switch default deployment engine** and **Decommission ArgoCD** move it to the native engine. See [Decommissioning ArgoCD](/concepts/deployment-engines#decommissioning-argocd).

### Disconnect Cluster

Imported clusters only. **Disconnect** removes the cluster from Ankra; running workloads and installed components stay, GitOps sync stops, and the agent is not removed from the cluster, so uninstall it yourself. To bring the cluster back, import it again. A managed Kubernetes cluster offers **Disconnect from Ankra**, which leaves the provider cluster running, and a separate action that deletes it at the provider - see [Managed Kubernetes](/guides/managed-kubernetes#deleting).

### Terminate cluster

For clusters Ankra provisioned, **Terminate** destroys the cloud infrastructure and removes the cluster from Ankra. It cannot be undone. First clean up provider resources that Ankra does not track. For a cluster already terminated whose record remains, **Delete Cluster** removes the record.

#### Persistent volumes

On Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway and AWS EC2, terminating a cluster also deletes the cloud volumes its CSI driver created for `PersistentVolumeClaim`s, and the data on them. Ankra does this only once you accept it:

* **Dashboard.** The **Terminate** and **Delete cluster** dialogs list the volumes by claim and size, and the delete button stays disabled until you tick *I understand that these volumes and their data are deleted*.
* **CLI.** `ankra cluster deprovision` names the volumes and asks. In a script, pass `--accept-volume-data-loss`; `--yes` never stands in for it, and without it the command stops with exit code 2.
* **API.** The delete needs `?accept_volume_data_loss=true` and answers `409` naming the volumes without it.
* **Ankra's AI.** The `delete_cluster` tool names the volumes and asks you first.

`--force` tolerates unreachable infrastructure but never replaces the acknowledgement. When Ankra cannot list a cluster's volumes it asks anyway. A cluster whose `retention_policy` is `retain` (the default on AWS EC2 and Scaleway) keeps its volumes, which keep billing in your cloud account until you delete them.

```bash theme={null}
ankra cluster deprovision <cluster>                            # names the volumes and asks
ankra cluster deprovision <cluster> --accept-volume-data-loss  # for scripts
```

***

## Next steps

* [Stop, Start and Power Schedules](/platform/cluster-power-schedules) - park a cluster when nobody uses it.
* [Nodes](/platform/cluster-nodes) - scale node groups and the control plane.
* [Operate an Ankra Managed Cluster](/guides/operate-ankra-managed-clusters) - node groups, upgrades, stop, start and terminate for clusters Ankra provisioned.
* [Organisation Settings](/platform/organisation-settings) - settings that apply to every cluster.


# Command Palette
Source: https://docs.ankra.ai/platform/command-palette

Jump to any page, cluster or Kubernetes resource and run common actions from one search box

Clicking through menus to reach a pod in a cluster three levels down is slow. The command palette is one search box that takes you to any page, cluster, add-on or Kubernetes resource, and runs common actions without leaving the keyboard.

## Open it

* Press `⌘ K` on macOS or `Ctrl K` on Windows and Linux, from any page.
* Or select **Search** in the sidebar.

Use `↑` and `↓` to move through results, `Enter` to open or run the selected item, and `Escape` to close the palette.

## Search

Type part of what you want. Matching is fuzzy and also checks each command's keywords, so `dep` finds **Deployments** and `registry` finds **Chart Repositories**. Results mix commands with live matches from your organisation: clusters, add-ons, manifests, Stacks and pods. Items you opened recently appear under **Recent** before you type anything.

When a cluster is open, the palette adds that cluster's pages (Stacks, Logs, Metrics, Operations, cluster settings) and every Kubernetes resource list, so you can jump straight to **Pods** or **Ingresses** in the current cluster.

## Examples

| Type | Command | What it does |
| - | - | - |
| `kubeconfig` | **Download Kubeconfig** | Downloads a kubeconfig for the open cluster |
| `reconcile` | **Reconcile Cluster** | Opens the reconcile dialog for the open cluster |
| `ticket` | **Create Support Ticket** | Opens a new ticket for the Ankra team |
| `pdf` | **Export this page as a PDF report** | Saves the current page as a PDF |
| `password` | **Generate random password** | Opens a random password generator |
| `org` | **Switch Organisation** | Moves you to another organisation you belong to |

The palette also opens the AI chat (**AI Chat**) and a cheat sheet of every shortcut (**Keyboard Shortcuts**). For the full list of shortcuts, see [Keyboard shortcuts](/platform/keyboard-shortcuts).


# Credentials
Source: https://docs.ankra.ai/platform/credentials

Securely manage authentication credentials for registries, Git providers, and cloud platforms.

Credentials in Ankra store authentication information for connecting to external services - Helm and container registries, Git providers, and cloud platforms used for cluster provisioning and cost estimation. Credentials are stored securely in a Vault-compatible secret store (HashiCorp Vault or OpenBao) and referenced by name when configuring integrations and clusters.

## Choose a credential type

> [card] [Registry](/platform/credentials/registry)
>
> Helm chart and container registries (HTTP and OCI).

> [card] [Git](/platform/credentials/git)
>
> GitHub, GitLab, and other Git providers for GitOps.

> [card] [Hetzner](/platform/credentials/hetzner)
>
> Hetzner Cloud API token for cluster provisioning.

> [card] [OVH](/platform/credentials/ovh)
>
> OVHcloud application keys and Public Cloud project.

> [card] [DigitalOcean](/platform/credentials/digitalocean)
>
> DigitalOcean personal access token for droplets and DOKS.

> [card] [UpCloud](/platform/credentials/upcloud)
>
> UpCloud subaccount API access for servers and UKS.

> [card] [Scaleway (Closed Beta)](/platform/credentials/scaleway)
>
> Project-scoped API key for Scaleway Instances clusters and Kapsule.

> [card] [AWS](/platform/credentials/aws)
>
> IAM role or access keys for cost, inventory, EKS, and self-managed clusters on EC2.

> [card] [Google Cloud (GCP)](/platform/credentials/gcp)
>
> Service account - read-only for cost and discovery, or with provisioning roles for GKE.

> [card] [Azure](/platform/credentials/azure)
>
> Service principal for provisioning AKS.

> [card] [Proxmox VE](/platform/credentials/proxmox)
>
> Proxmox API URL and token for self-managed clusters.

> [card] [Morpheus](/platform/credentials/morpheus)
>
> Morpheus appliance URL and access token.

> [card] [Ankra Cloud (Closed Beta)](/platform/credentials/ankra-cloud)
>
> Ankra Cloud API token for self-managed clusters and Ankra Cloud Kubernetes.

> [card] [SSH Key](/platform/credentials/ssh-key)
>
> SSH keys for server access on self-managed clusters.

## Compare credential types

| Credential | Used for | CLI command | Guide |
| - | - | - | - |
| Registry | Sync Helm charts / images from private registries | UI/API only | [Registry](/platform/credentials/registry) |
| Git | GitOps configuration sync | Via the GitHub App | [Git](/platform/credentials/git) |
| Hetzner | Provision Hetzner clusters | `ankra credentials hetzner` | [Hetzner](/platform/credentials/hetzner) |
| OVH | Provision OVH clusters and OVHcloud MKS | `ankra credentials ovh` | [OVH](/platform/credentials/ovh) |
| DigitalOcean | Provision droplet clusters and DOKS | `ankra credentials digitalocean` | [DigitalOcean](/platform/credentials/digitalocean) |
| UpCloud | Provision UpCloud clusters and UKS | `ankra credentials upcloud` | [UpCloud](/platform/credentials/upcloud) |
| Scaleway (Closed Beta) | Provision Scaleway Instances clusters and Kapsule | `ankra credentials scaleway` (v0.14.0+) | [Scaleway](/platform/credentials/scaleway) |
| AWS | Cost, inventory, EKS, and self-managed clusters on EC2 | `ankra credentials aws` | [AWS](/platform/credentials/aws) |
| Google Cloud (GCP) | Cost, discovery, and GKE | UI/API only | [GCP](/platform/credentials/gcp) |
| Azure | Provision AKS | `ankra credentials azure` (v0.14.0+) | [Azure](/platform/credentials/azure) |
| Proxmox VE | Provision self-managed Proxmox clusters | `ankra credentials proxmox` (v0.9.0+) | [Proxmox VE](/platform/credentials/proxmox) |
| Morpheus | Provision self-managed Morpheus clusters | `ankra credentials morpheus` (v0.9.0+) | [Morpheus](/platform/credentials/morpheus) |
| Ankra Cloud (Closed Beta) | Provision self-managed Ankra Cloud clusters and Ankra Cloud Kubernetes | UI/API only | [Ankra Cloud](/platform/credentials/ankra-cloud) |
| SSH Key | Server access on self-managed clusters | `ankra credentials <provider> ssh-key` (Hetzner, OVH, DigitalOcean, UpCloud, Proxmox, Morpheus, Scaleway) | [SSH Key](/platform/credentials/ssh-key) |

***

## Using credentials

Credentials are selected by name where they're needed:

* **Registries**: when adding a Helm registry, pick the [registry credential](/platform/credentials/registry) from the dropdown.
* **Clusters**: when provisioning or importing a cluster, pick the matching cloud credential (and an [SSH key](/platform/credentials/ssh-key) for self-managed clusters).
* **GitOps**: the [Git connection](/platform/credentials/git) is used automatically when syncing configuration.

***

## Managing credentials

### View credentials

Go to **Credentials** to see all stored credentials as cards - each card shows the provider, credential type, health, and when it was last updated. Filter by name or provider, sort, and select multiple cards for bulk deletion.

The title and the search, filter and sort row stay in place while the cards scroll. Before you have added a credential, the page offers a shortcut to each kind (source control, cloud providers, container registries, access keys) that opens the provider list at that group. Credentials Ankra manages for the organisation, such as registry robot logins, stay hidden until you choose to show them. When a search or filter matches nothing, **Clear filters** resets both.

Opening a credential shows its identity - provider, availability, whether it is in use, and when it was created - with the rest organised into tabs:

* **Overview** - the identity fields the credential authenticates with (secret values stay masked or in the platform's secret store) and a **Verify connection** check that probes the provider API with the stored credential.
* **Capacity** - the live capacity and usage report, for cloud providers (see below).
* **Used by** - the clusters running on this credential and any operations currently holding it.
* **Rotation** - in-place secret rotation, for providers that support it.

### Capacity and usage

Open any cloud provider credential and switch to the **Capacity** tab for a live capacity report read from the provider with that credential:

* **Hetzner** shows project usage: servers with their combined vCPUs, memory, and disk, volumes, load balancers, floating and primary IPs, networks, firewalls, and SSH keys. Hetzner does not expose project limits through its API, so the view shows usage only.
* **Proxmox VE** shows the total resources of the cluster behind the credential: each node with used and total CPU and memory, storage pools (shared pools counted once), and how many guests are running with the vCPUs and memory allocated to them.
* **UpCloud** shows the account's resource limits (CPU cores, memory, storage, IPs, networks, load balancers) as usage bars, plus remaining credits.
* **DigitalOcean** shows account limits (droplets, floating and reserved IPs) with usage against them, droplet resource sums, volumes, and load balancers.
* **OVHcloud** shows the project's per-region quotas: vCPUs, instances, memory, and volume storage as usage bars per region and in total, plus volume and load balancer counts.
* **Scaleway** shows project usage swept across zones: servers with real vCPU and memory sums, storage, and load balancers. Scaleway does not expose quota headroom through its APIs, so the view shows usage only.
* **HPE Morpheus** shows each cloud on the appliance with used and total memory and storage plus CPU load, and the appliance's instance and host counts.
* **Azure** shows the subscription's virtual machine and AKS cluster counts, with regional vCPU and VM quota bars for the regions currently in use.

The report is read from the provider API when you open the credential, so it reflects everything in the account, including resources created outside Ankra.

### Update a credential

Identity fields are fixed - a credential always points at the same account or infrastructure. What changes is the secret material, and that rotates in place:

1. Click on the credential name
2. Open the **Rotation** tab
3. Enter the new secret and click **Verify & rotate**

The new secret is verified against the provider before anything is saved, so a failed rotation never breaks the working credential.

> [!NOTE]
>
> Rotating a credential automatically applies to everything using it. No need to reconfigure registries or clusters.

### Delete a credential

1. Go to **Credentials**
2. Click the menu (⋮) next to the credential
3. Select **Delete**

> [!WARNING]
>
> Deleting a credential will break authentication for anything using it. Update those integrations first.

### AI and MCP access

Ankra's AI and MCP clients can list and inspect credentials (secret fields are always redacted), validate names, delete unused credentials, and plan and apply a GitHub credential rotation - but they can never **create** a credential, because that would mean passing the secret itself to the AI, which the platform refuses. See the [MCP Tool Reference](/platform/mcp-tools#credentials).

***

## Security

### Storage

Credentials are stored securely in a dedicated secret store (HashiCorp Vault or OpenBao):

* Encrypted at rest
* Access controlled per organisation
* Every reveal of a secret value through the API is written to the organisation's audit log, as are verifying, rotating, renaming and deleting a credential. Listing credentials, and the platform's own use of a credential when it provisions or deploys, are not written there.

***

## Troubleshooting

### Authentication errors

| Error | Cause | Solution |
| - | - | - |
| 401 Unauthorized | Invalid credentials | Verify username and password/token |
| 403 Forbidden | Insufficient permissions | Check the token has required scopes |
| Token expired | Temporary tokens (ECR) | Refresh the token |
| Connection refused | Network issue | Check firewall and network access |

For provider-specific troubleshooting, see the individual credential pages (for example [GCP](/platform/credentials/gcp)).

***

## API access

Manage credentials via the Ankra API:

```python theme={null}
import requests

headers = {"Authorization": f"Bearer {TOKEN}"}

# List every credential in the organisation
response = requests.get(
    "https://platform.ankra.app/api/v1/org/credentials",
    headers=headers
)

# Create a credential: the path names the provider, the body carries
# what that provider needs (a Hetzner credential is an API token)
response = requests.post(
    "https://platform.ankra.app/api/v1/credentials/hetzner",
    headers=headers,
    json={
        "name": "hetzner-production",
        "api_token": "<your-hetzner-api-token>"
    }
)
```

Every provider has its own `POST /api/v1/credentials/{provider}` with the fields that provider needs; the API reference lists them.

See the [API Reference](/api-reference/introduction) for complete documentation.


# Ankra Cloud Credentials
Source: https://docs.ankra.ai/platform/credentials/ankra-cloud

Store an Ankra Cloud API token in Ankra to build self-managed kubeadm or k3s clusters on Ankra Cloud servers and to provision Ankra Cloud Kubernetes.

An Ankra Cloud credential stores an Ankra Cloud API token. One credential serves both cluster types on [Ankra Cloud](https://cloud.ankra.app): self-managed [Ankra Cloud clusters](/guides/ankra-cloud-clusters) and managed [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes).

> [!WARNING]
>
> **Closed beta.** Ankra Cloud as a cluster provider is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request - until it is, Ankra Cloud is not offered as a credential provider. [Contact support](/platform/support) to have it turned on for your organisation.

The token is validated when you save it: Ankra lists the zones and plans of the account (`GET /v1/zones` and `GET /v1/plans`), so a rejected or mistyped token is refused immediately. The token never appears in an error message or on the credential's page.

## What Ankra Accesses

For self-managed clusters, Ankra provisions the infrastructure directly:

| Resource | Operations | Why it's used |
| - | - | - |
| Zones, plans, templates, storage tiers | read | The wizard's live catalog and pricing |
| Servers | create, read, start/stop/restart, delete | The cluster's nodes and bastion |
| Server firewalls | update | Per-server inbound rules |
| Private networks | create, read, delete | The cluster's private network |
| Routers | create, read, delete | NAT egress for the nodes |
| Storages | read, delete | Persistent volumes the in-cluster CSI driver creates. When you delete the cluster, Ankra deletes them or keeps them, following the cluster's storage retention policy |
| Load balancers | none | Created and removed by the in-cluster cloud controller with the [runtime credential](#runtime-credential), as `LoadBalancer` Services come and go. Ankra itself never lists or deletes them |

Because Ankra does not clean up load balancers, delete a cluster's `LoadBalancer` Services before you delete the cluster. A load balancer the cloud controller has not removed by then stays in your Ankra Cloud account, and is billed, until you delete it in the [Ankra Cloud console](https://cloud.ankra.app).

For [Ankra Cloud Kubernetes](/guides/ankra-cloud-kubernetes), Ankra uses the managed Kubernetes API instead:

| Resource | Operations | Why it's used |
| - | - | - |
| Kubernetes clusters | create, read, upgrade, delete | Cluster lifecycle |
| Node pools | create, read, update, delete | Scale and manage the cluster's node pools |
| Kubeconfig | read | Install Ankra's agent; fetched fresh each time and never stored |
| Private networks | create, read, delete | The network the cluster's nodes join |
| Versions, plans, zones | read | Available Kubernetes versions, plans and zones, and the production and development control planes with their fees |

## Creating an Ankra Cloud credential

**1. Create an Ankra Cloud API token**

1. Sign in to the [Ankra Cloud console](https://cloud.ankra.app)
2. Open **Settings** → **API tokens** (owners and admins)
3. Create a token and copy it (prefixed with `act_`; shown once)

The token acts with the current role of the user who created it. That user must be allowed to operate the account - create servers, networks, routers and Kubernetes clusters. A read-only user's token passes the save-time check but fails when Ankra provisions.

**2. Add to Ankra**

Go to **Credentials** → **Add** → **Ankra Cloud**, then provide:

* **Name**: a unique identifier (e.g. `ankra-cloud-prod`)
* **API Token**: the `act_...` token from the previous step
* **API endpoint** (optional): only for a private or development Ankra Cloud. It must be an `https://` URL; leave it empty to use `https://cloud.ankra.app`

Click **Test connection** to verify the token, then save. You can also add the credential inline from either create-cluster wizard.

For self-managed clusters you also need an [SSH key credential](/platform/credentials/ssh-key). Ankra Cloud Kubernetes needs none.

> [!NOTE]
>
> The token can be rotated later from the credential's **Rotation** tab without recreating the credential - everything using it picks up the new token automatically.

## Runtime credential

A self-managed cluster runs the Ankra Cloud cloud controller manager and CSI driver inside the cluster, and they need a token too. The create wizard's **Runtime credential** picks which Ankra Cloud credential they get: by default the provisioning credential, or a second, dedicated one. A dedicated runtime credential limits what a compromised workload in the cluster could reach through that token. Ankra stores it in the Secret `ankra-cloud` in `kube-system`, SOPS-encrypted when the stack is committed to Git.

## Listing Ankra Cloud credentials

```bash theme={null}
curl https://platform.ankra.app/api/v1/credentials/ankracloud \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

## Troubleshooting

| Symptom | Cause | Solution |
| - | - | - |
| The credential is refused on save | The token is invalid, revoked, or copied incompletely | Create a new token and paste the full `act_...` value |
| The endpoint is refused | The endpoint is not an `https://` URL | Use `https://`, or leave it empty for `https://cloud.ankra.app` |
| The credential saves, but provisioning fails with a permissions error | The token's user may not operate the account | Give that user an operating role, or create a token as a user who has one and rotate it in |
| Provisioning fails with a payment or suspension error | The Ankra Cloud account needs a payment method or is suspended | Resolve it in the Ankra Cloud console, then retry |


# AWS Credentials
Source: https://docs.ankra.ai/platform/credentials/aws

Connect AWS to Ankra with an IAM role created by a CloudFormation stack, or with access keys - read-only for cost estimates and inventory, or with the provisioning role that creates EKS clusters and self-managed k3s clusters on EC2 in your own VPC.

AWS credentials let Ankra estimate the infrastructure cost of your clusters, sync cloud inventory, provision [Amazon EKS](/guides/eks-clusters), and build [self-managed k3s clusters on EC2](/guides/aws-clusters). There are two access levels, and you choose which one to grant:

* **Read-only** - cost estimates, pricing data, and cluster discovery only. Ankra never provisions or modifies AWS resources.
* **Provisioning** - everything read-only does, plus creating and managing EKS clusters *and* self-managed k3s clusters on EC2, in a VPC Ankra creates or one you adopt. One write role (`AnkraProvisioning`) covers every cluster Ankra can build in your account; the EC2 writes it grants are scoped to resources Ankra tags.

An account that wants self-managed clusters but must not grant `eks:*` has an [EC2-only alternative](#self-managed-clusters-ec2-only-alternative): the `AnkraSelfManagedProvisioning` role, which is the provisioning role minus the EKS statements.

There are also two ways to connect. The **IAM role** method (recommended) launches a one-click CloudFormation stack that creates a role Ankra assumes with short-lived credentials, secured by a unique external ID - no long-lived keys to store or rotate. The **access keys** method stores an access key ID and secret for an IAM user - simpler to set up, but you own key rotation, and the access level is whatever the user's IAM policy allows.

The credential is validated when you save it: the IAM role method performs a real `sts:AssumeRole` call against your role, and access keys are checked with a read-only `sts:GetCallerIdentity` call - so a role that can't be assumed or a key AWS rejects is refused immediately.

## What Ankra Accesses

For cost estimation and inventory, Ankra calls these AWS APIs, all read-only:

| Service | Actions | Why it's used |
| - | - | - |
| Pricing | `pricing:GetProducts`, `pricing:DescribeServices` | Read the public price catalog to estimate node costs |
| Cost Explorer | `ce:GetCostAndUsage`, `ce:GetCostForecast` | Read your account's actual spend and forecast |
| EC2 | `ec2:DescribeInstanceTypes`, `ec2:DescribeInstanceTypeOfferings`, `ec2:DescribeAvailabilityZones`, `ec2:DescribeRegions`, `ec2:DescribeInstances` | Read instance-type specs (vCPU and memory), region and zone availability, and running instances to price your nodes |
| EKS | `eks:ListClusters`, `eks:DescribeCluster` | Discover the EKS clusters in your account |
| STS | `sts:GetCallerIdentity` | Verify the credential works (the **Test connection** check) |

### Provisioning

Provisioning is one write role for every cluster Ankra can build in your account - [Amazon EKS](/guides/eks-clusters) and [self-managed k3s clusters on EC2](/guides/aws-clusters). It is a superset of the read-only level, so a single provisioning credential also powers cost estimates and inventory. Every EC2 write is scoped to resources carrying the `ankra.cloud/managed=true` tag Ankra sets on everything it creates, IAM writes to names prefixed `ankra-eks-` or `ankra-k3s-`, and the rest is read-only lookups. Your VPC, subnets, internet gateway, NAT gateways, DHCP options and existing route tables are never created, modified or deleted - Ankra builds inside the network you give it. The 30 statements of the policy, by their `Sid`:

> [!NOTE]
>
> **Launched the provisioning stack before the self-managed statements were added?** Your role carries only the EKS statements, and a self-managed cluster preflight names the EC2 permission it is missing. Update the stack rather than recreating it: on the stack page choose **Update** → **Replace current template** → **Amazon S3 URL**, paste `https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-provisioning.cfn.yaml`, keep every parameter as it is, and update. The role ARN and external ID do not change, so the credential in Ankra needs no edit.

| Sid | Actions | Why it's used | Scoped to |
| - | - | - | - |
| `EksLifecycle` | `eks:*` | Create, describe, scale, upgrade and delete EKS clusters and managed node groups | All resources |
| `Ec2Read` | `ec2:Describe*` | Read VPCs, subnets, route tables, DHCP options, instance types and offerings, availability zones, images, addresses, volumes and the instances Ankra runs; discover default-VPC subnets and spot price history for EKS | All resources (read-only) |
| `PricingAndCostRead` | `pricing:GetProducts`, `pricing:DescribeServices`, `ce:GetCostAndUsage`, `ce:GetCostForecast`, `servicequotas:GetServiceQuota`, `servicequotas:ListServiceQuotas`, `sts:GetCallerIdentity` | The cost catalog and spend reads, the self-managed create preflight's quota checks, and **Test connection** | All resources (read-only) |
| `UbuntuImageLookup` | `ssm:GetParameters`, `ssm:GetParameter`, `ssm:DescribeParameters` | Resolve the Canonical Ubuntu AMI for the region and series at create time | `arn:aws:ssm:*::parameter/aws/service/canonical/*` |
| `Ec2RunInstancesTagged` | `ec2:RunInstances` | Launch the bastion and node instances with their volumes and network interfaces | Instances, volumes and network interfaces created with the `ankra.cloud/managed=true` request tag |
| `Ec2RunInstancesReferences` | `ec2:RunInstances` | Reference your subnet and the Ankra security groups, key pair and image when launching | Subnets, security groups, key pairs, images (referenced, not created) |
| `Ec2CreateTagsOnCreate` | `ec2:CreateTags` | Tag resources as they are created | Only during `RunInstances`, `CreateSecurityGroup`, `AllocateAddress`, `CreateRouteTable`, `ImportKeyPair` |
| `Ec2CreateTagsOnOwned` | `ec2:CreateTags`, `ec2:DeleteTags` | Re-tag resources Ankra already owns | Resources tagged `ankra.cloud/managed=true` |
| `Ec2ManageOwnedInstances` | `ec2:TerminateInstances`, `ec2:StopInstances`, `ec2:StartInstances`, `ec2:RebootInstances`, `ec2:ModifyInstanceAttribute`, `ec2:ModifyInstanceMetadataOptions`, `ec2:AssociateIamInstanceProfile`, `ec2:ReplaceIamInstanceProfileAssociation`, `ec2:DisassociateIamInstanceProfile` | Stop and start, node restart and repair, teardown, the bastion's source/destination check in `bastion_nat` mode, the IMDSv2 hardening, and attaching instance profiles | Instances tagged `ankra.cloud/managed=true` |
| `Ec2CreateSecurityGroup` | `ec2:CreateSecurityGroup` | Create the node and bastion security groups inside your VPC | Any VPC (the group itself must carry the managed tag, next row) |
| `Ec2CreateSecurityGroupTagged` | `ec2:CreateSecurityGroup` | The same call, on the group being created | Security groups created with the managed request tag |
| `Ec2ManageOwnedSecurityGroups` | `ec2:AuthorizeSecurityGroupIngress`, `ec2:AuthorizeSecurityGroupEgress`, `ec2:RevokeSecurityGroupIngress`, `ec2:RevokeSecurityGroupEgress`, `ec2:UpdateSecurityGroupRuleDescriptionsIngress`, `ec2:DeleteSecurityGroup` | Manage rules (including `bastion_allowed_ips`) and delete the groups at teardown | Security groups tagged `ankra.cloud/managed=true` |
| `Ec2KeyPairs` | `ec2:ImportKeyPair` | Import the cluster's SSH public key | Key pairs named `ankra-k3s-*`, created with the managed tag |
| `Ec2DeleteOwnedKeyPairs` | `ec2:DeleteKeyPair` | Remove the key pair at teardown | Key pairs named `ankra-k3s-*` tagged `ankra.cloud/managed=true` |
| `Ec2AllocateAddressTagged` | `ec2:AllocateAddress` | One Elastic IP per cluster for the bastion | Elastic IPs created with the managed tag |
| `Ec2ManageOwnedAddresses` | `ec2:AssociateAddress`, `ec2:DisassociateAddress`, `ec2:ReleaseAddress` | Attach the Elastic IP to the bastion, keep it across a resize, release it at teardown | Elastic IPs, instances and network interfaces tagged `ankra.cloud/managed=true` |
| `Ec2CreateRouteTable` | `ec2:CreateRouteTable` | `bastion_nat` mode only: create the one Ankra-owned route table inside your VPC | Any VPC (the table itself must carry the managed tag, next row) |
| `Ec2CreateRouteTableTagged` | `ec2:CreateRouteTable` | The same call, on the table being created | Route tables created with the managed request tag |
| `Ec2ManageOwnedRouteTables` | `ec2:CreateRoute`, `ec2:ReplaceRoute`, `ec2:DeleteRoute`, `ec2:AssociateRouteTable`, `ec2:ReplaceRouteTableAssociation`, `ec2:DisassociateRouteTable`, `ec2:DeleteRouteTable` | Point the Ankra route table's default route at the bastion, associate the node subnets, and undo all of it at teardown | Route tables tagged `ankra.cloud/managed=true` - never a route table Ankra did not create |
| `Ec2RouteTableAssociationReferences` | `ec2:AssociateRouteTable`, `ec2:ReplaceRouteTableAssociation`, `ec2:DisassociateRouteTable` | The subnet side of the association above (an association carries no tags) | Any subnet (yours, untagged); the route table side is still tag-scoped |
| `Ec2DeleteOwnedVolumes` | `ec2:DeleteVolume` | Teardown sweep of the EBS volumes the CSI driver provisioned, when `retention_policy` is `delete` | Volumes tagged `ankra.cloud/managed=true` |
| `ElbRead` | `elasticloadbalancing:Describe*` | Find the load balancers the cloud controller created for the cluster | All resources (read-only) |
| `ElbDeleteOwned` | `elasticloadbalancing:DeleteLoadBalancer`, `elasticloadbalancing:DeleteTargetGroup`, `elasticloadbalancing:DeleteListener` | Teardown sweep of those load balancers, when `retention_policy` is `delete` | Load balancers tagged `ankra.cloud/managed=true` |
| `IamForEksRoles` | `iam:CreateRole`, `iam:DeleteRole`, `iam:AttachRolePolicy`, `iam:DetachRolePolicy`, `iam:PutRolePolicy`, `iam:DeleteRolePolicy`, `iam:GetRole`, `iam:GetRolePolicy`, `iam:ListRolePolicies`, `iam:ListAttachedRolePolicies`, `iam:TagRole` | The two IAM roles Ankra creates per EKS cluster (`ankra-eks-cluster-<name>` and `ankra-eks-node-<name>`) | `arn:aws:iam::*:role/ankra-eks-*` |
| `IamServiceLinkedRolesRead` | `iam:GetRole` | EKS validates its service-linked roles with the caller's own `GetRole` before a node group is created | `aws-service-role/` roles of `eks.amazonaws.com`, `eks-nodegroup.amazonaws.com`, `autoscaling.amazonaws.com` |
| `IamPassRoleForEks` | `iam:PassRole` | Attach the `ankra-eks-*` roles to the EKS control plane and to managed node-group instances | `ankra-eks-*` roles, passable only to `eks.amazonaws.com` and `ec2.amazonaws.com` |
| `IamForK3sRoles` | `iam:CreateRole`, `iam:DeleteRole`, `iam:PutRolePolicy`, `iam:DeleteRolePolicy`, `iam:AttachRolePolicy`, `iam:DetachRolePolicy`, `iam:GetRole`, `iam:GetRolePolicy`, `iam:ListRolePolicies`, `iam:ListAttachedRolePolicies`, `iam:ListInstanceProfilesForRole`, `iam:TagRole` | The two roles Ankra creates per self-managed cluster - `ankra-k3s-<cluster>-cp` (cloud controller manager and EBS CSI controller) and `ankra-k3s-<cluster>-node` | `arn:aws:iam::*:role/ankra-k3s-*` |
| `IamForK3sInstanceProfiles` | `iam:CreateInstanceProfile`, `iam:DeleteInstanceProfile`, `iam:GetInstanceProfile`, `iam:AddRoleToInstanceProfile`, `iam:RemoveRoleFromInstanceProfile`, `iam:TagInstanceProfile` | The instance profiles that attach those roles to the instances | `arn:aws:iam::*:instance-profile/ankra-k3s-*` |
| `IamPassRoleToEc2` | `iam:PassRole` | Attach the per-cluster roles to EC2 instances | `ankra-k3s-*` roles, passable only to `ec2.amazonaws.com` |
| `IamServiceLinkedRoles` | `iam:CreateServiceLinkedRole` | Let EKS, its node groups and their Auto Scaling groups, Elastic Load Balancing (the cloud controller's `LoadBalancer` Services) and Spot create their service-linked roles on first use in an account | `aws-service-role/*` for `eks.amazonaws.com`, `eks-nodegroup.amazonaws.com`, `autoscaling.amazonaws.com`, `elasticloadbalancing.amazonaws.com` and `spot.amazonaws.com` only |

The IAM permissions are deliberately narrow: role management applies only to roles named `ankra-eks-*` and `ankra-k3s-*` (the ones Ankra itself creates), and `iam:PassRole` is conditioned so those roles can only be passed to EKS and EC2. Ankra cannot touch any other IAM role in your account, and it cannot touch an EC2 resource it did not tag.

The same onboarding is served on the API for scripts: `GET /api/v1/credentials/aws/onboarding?scope=provisioning` returns the external ID and the quick-create link (`scope` is `cost`, `provisioning` or `self_managed`), `POST /api/v1/credentials/aws/role` stores the role with its `scope`, and `POST /api/v1/credentials/aws/keys` stores access keys - see the [credential API](/reference/aws#credential-api). The CLI wraps the same calls: `ankra credentials aws onboarding --scope provisioning` prints the external ID, the trust principal and the launch-stack URL together with the `create-role` command to run next; `ankra credentials aws create-role --name <name> --role-arn <arn> --external-id <id> --scope provisioning` stores the role once the stack is complete; `ankra credentials aws create-keys --name <name> --access-key-id <id>` stores access keys and asks for the secret on a masked prompt, never as a flag; and `ankra credentials aws list` shows the credentials the organisation has connected.

### Self-managed clusters (EC2-only alternative)

The provisioning role is the normal way to build self-managed clusters. For an account that must not grant `eks:*`, the `AnkraSelfManagedProvisioning` role ([template](https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-self-managed-provisioning.cfn.yaml), scope `self_managed`) is the provisioning role minus the EKS statements: no `EksLifecycle`, `IamForEksRoles`, `IamServiceLinkedRolesRead` or `IamPassRoleForEks`, no Cost Explorer reads (its `CatalogRead` statement carries the pricing, quota and identity lookups only), and service-linked roles limited to Elastic Load Balancing and Spot. Every EC2, SSM, ELB and `ankra-k3s-*` IAM statement in the table above is in it unchanged. A credential onboarded at this scope builds self-managed clusters but is refused for EKS; an account that wants both uses the provisioning role, not two credentials.

When you save a `self_managed` role, Ankra assumes it and additionally proves it against EC2 (a dry-run `DescribeVpcs`) and the Canonical Ubuntu AMI parameters, so a role launched from the wrong template is refused at **Test connection** rather than at the first cluster create. An access-keys credential is accepted for self-managed clusters as long as the user's policy carries the statements above.

With the IAM role method, these are exactly the policies the CloudFormation stack creates - you can review the templates before deploying ([read-only](https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-cloud-cost-readonly.cfn.yaml), [provisioning](https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-provisioning.cfn.yaml), [self-managed](https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-self-managed-provisioning.cfn.yaml)). The role's trust policy only allows Ankra's AWS principal to assume it, and only when the request carries your external ID, with sessions capped at one hour - Ankra never stores AWS keys for a role credential. With access keys, you attach equivalent policies to an IAM user yourself - the **Access keys** tab below includes ready-made policy JSON for both levels.

## Creating an AWS Credential

Pick the tab that matches what you want the credential to do. Each flow is complete - follow one from top to bottom. The three IAM-role flows are identical except for which CloudFormation template you launch; most accounts need only **Read-only** or **Provisioning**.

> [tab] Read-only (cost and inventory)
>
> Creates a role (`AnkraCloudCostReadOnly` by default) with the read-only actions from [What Ankra Accesses](#what-ankra-accesses). Ankra can price your nodes, read your spend, and discover clusters, but cannot create or change anything.
>
> You will move between two browser tabs - the Ankra credential dialog and the AWS CloudFormation console - and need an AWS account where you may create CloudFormation stacks and IAM roles (for example `AdministratorAccess`, or CloudFormation plus IAM write permissions). The whole flow takes about five minutes.
>
> **1. Start the wizard in Ankra**
>
> Go to **Credentials** → **Add** → **AWS** and pick **Read-only (cost & inventory)**. Enter a credential name.
>
> The dialog shows your unique **external ID** (it starts with `ankra-`). This ID ties the role to your organisation and is pre-filled in the stack you are about to launch - you don't need to copy it anywhere.
>
> > [!WARNING]
> >
> > Keep this dialog open until you finish. A fresh external ID is generated each time you open the wizard - if you close it and start again after creating the stack, the new ID won't match your stack and the connection will fail. See [troubleshooting](#troubleshooting-aws-credentials) if this happens.
>
> **2. Launch the CloudFormation stack**
>
> Click **Launch CloudFormation stack**. This opens the AWS console's quick-create page in a new tab, with everything pre-filled: the template, the stack name (`AnkraCloudCostReadOnly`), your external ID, and the Ankra principal that will assume the role.
>
> 1. If prompted, sign in to the AWS account you want to connect.
> 2. Leave the `ExternalId` and `AnkraPrincipalArn` parameters unchanged. You can rename the stack or role if your organisation requires it.
> 3. Tick **I acknowledge that AWS CloudFormation might create IAM resources with custom names** at the bottom of the page.
> 4. Click **Create stack**.
>
> **3. Wait for CREATE\_COMPLETE**
>
> The stack creates a single IAM role and nothing else, and usually finishes in under a minute. Wait until the stack status shows `CREATE_COMPLETE` (use the refresh button on the stack page).
>
> **4. Copy the Role ARN from the Outputs tab**
>
> On the stack page, open the **Outputs** tab and copy the value of the `RoleArn` output. It looks like:
>
> ```
> arn:aws:iam::<account-id>:role/AnkraCloudCostReadOnly
> ```
>
> If you don't see an Outputs tab, the stack hasn't finished creating yet, or you are looking at a different stack.
>
> **5. Add to Ankra (UI)**
>
> Back in the Ankra dialog, paste the ARN into **Role ARN**. Set the **Default region** to the region you want Ankra to use for cost data.
>
> Click **Test connection** - Ankra performs a real `sts:AssumeRole` call against your new role, and on success you'll see "AWS role assumed successfully". Then click **Connect AWS account** to save. The credential now appears in your credentials list and is used automatically for cost and inventory sync.

> [tab] Provisioning (EKS and self-managed)
>
> Creates a role (`AnkraProvisioning` by default) that can manage [EKS clusters](/guides/eks-clusters) and build [self-managed k3s clusters on EC2](/guides/aws-clusters), with the `ankra-eks-*` and `ankra-k3s-*` IAM roles Ankra creates for them, plus all the read-only actions - so a single provisioning credential also powers cost estimates and inventory. The statements are listed under [Provisioning](#provisioning).
>
> You will move between two browser tabs - the Ankra credential dialog and the AWS CloudFormation console - and need an AWS account where you may create CloudFormation stacks and IAM roles (for example `AdministratorAccess`, or CloudFormation plus IAM write permissions). The whole flow takes about five minutes.
>
> **1. Start the wizard in Ankra**
>
> Go to **Credentials** → **Add** → **AWS** and pick **Provisioning**. Enter a credential name.
>
> The dialog shows your unique **external ID** (it starts with `ankra-`). This ID ties the role to your organisation and is pre-filled in the stack you are about to launch - you don't need to copy it anywhere.
>
> > [!WARNING]
> >
> > Keep this dialog open until you finish. A fresh external ID is generated each time you open the wizard - if you close it and start again after creating the stack, the new ID won't match your stack and the connection will fail. See [troubleshooting](#troubleshooting-aws-credentials) if this happens.
>
> **2. Launch the CloudFormation stack**
>
> Click **Launch CloudFormation stack**. This opens the AWS console's quick-create page in a new tab, with everything pre-filled: the template, the stack name (`AnkraProvisioning`), your external ID, and the Ankra principal that will assume the role.
>
> 1. If prompted, sign in to the AWS account you want to connect.
> 2. Leave the `ExternalId` and `AnkraPrincipalArn` parameters unchanged. You can rename the stack or role if your organisation requires it, and set the optional `PermissionsBoundaryArn` parameter if your organisation requires a permissions boundary on new roles.
> 3. Tick **I acknowledge that AWS CloudFormation might create IAM resources with custom names** at the bottom of the page.
> 4. Click **Create stack**.
>
> **3. Wait for CREATE\_COMPLETE**
>
> The stack creates a single IAM role and nothing else, and usually finishes in under a minute. Wait until the stack status shows `CREATE_COMPLETE` (use the refresh button on the stack page).
>
> **4. Copy the Role ARN from the Outputs tab**
>
> On the stack page, open the **Outputs** tab and copy the value of the `RoleArn` output. It looks like:
>
> ```
> arn:aws:iam::<account-id>:role/AnkraProvisioning
> ```
>
> If you don't see an Outputs tab, the stack hasn't finished creating yet, or you are looking at a different stack.
>
> **5. Add to Ankra (UI)**
>
> Back in the Ankra dialog, paste the ARN into **Role ARN**. Set the **Default region** to the region you want Ankra to use for cost data and as the default for new clusters.
>
> Click **Test connection** - Ankra performs a real `sts:AssumeRole` call against your new role, and on success you'll see "AWS role assumed successfully". Then click **Connect AWS account** to save.
>
> **6. Create your first cluster**
>
> With the credential saved, follow [Amazon EKS](/guides/eks-clusters) or [AWS Clusters](/guides/aws-clusters) (self-managed) to provision a cluster from the portal, CLI, or API. If this stack was launched before the self-managed statements were added, update it first - see the note under [Provisioning](#provisioning).

> [tab] Self-managed only (EC2 without EKS)
>
> Creates a role (`AnkraSelfManagedProvisioning` by default) that can build and operate [self-managed k3s clusters on EC2](/guides/aws-clusters), plus the read-only catalog actions - and nothing for EKS. Use it only when your account must not grant `eks:*`; otherwise the **Provisioning** tab covers self-managed clusters too. The level is offered only once self-managed AWS clusters are enabled for your organisation - see [the EC2-only alternative](#self-managed-clusters-ec2-only-alternative) above.
>
> You will move between two browser tabs - the Ankra credential dialog and the AWS CloudFormation console - and need an AWS account where you may create CloudFormation stacks and IAM roles (for example `AdministratorAccess`, or CloudFormation plus IAM write permissions). The whole flow takes about five minutes.
>
> **1. Start the wizard in Ankra**
>
> Go to **Credentials** → **Add** → **AWS** and pick **Self-managed only**. Enter a credential name.
>
> The dialog shows your unique **external ID** (it starts with `ankra-`). This ID ties the role to your organisation and is pre-filled in the stack you are about to launch - you don't need to copy it anywhere.
>
> > [!WARNING]
> >
> > Keep this dialog open until you finish. A fresh external ID is generated each time you open the wizard - if you close it and start again after creating the stack, the new ID won't match your stack and the connection will fail. See [troubleshooting](#troubleshooting-aws-credentials) if this happens.
>
> **2. Launch the CloudFormation stack**
>
> Click **Launch CloudFormation stack**. This opens the AWS console's quick-create page in a new tab, with everything pre-filled: the template, the stack name (`AnkraSelfManagedProvisioning`), your external ID, and the Ankra principal that will assume the role.
>
> 1. If prompted, sign in to the AWS account that owns the VPC you want to build in.
> 2. Leave the `ExternalId` and `AnkraPrincipalArn` parameters unchanged. You can rename the stack or role if your organisation requires it, and set the optional `PermissionsBoundaryArn` parameter if your organisation requires a permissions boundary on new roles.
> 3. Tick **I acknowledge that AWS CloudFormation might create IAM resources with custom names** at the bottom of the page.
> 4. Click **Create stack**.
>
> **3. Wait for CREATE\_COMPLETE**
>
> The stack creates a single IAM role and nothing else, and usually finishes in under a minute. Wait until the stack status shows `CREATE_COMPLETE` (use the refresh button on the stack page).
>
> **4. Copy the Role ARN from the Outputs tab**
>
> On the stack page, open the **Outputs** tab and copy the value of the `RoleArn` output. It looks like:
>
> ```
> arn:aws:iam::<account-id>:role/AnkraSelfManagedProvisioning
> ```
>
> If you don't see an Outputs tab, the stack hasn't finished creating yet, or you are looking at a different stack.
>
> **5. Add to Ankra (UI)**
>
> Back in the Ankra dialog, paste the ARN into **Role ARN**. Set the **Default region** to the region your VPC is in - it is the default region for new clusters and for cost data.
>
> Click **Test connection** - Ankra performs a real `sts:AssumeRole` call against your new role, and on success you'll see "AWS role assumed successfully". Then click **Connect AWS account** to save.
>
> **6. Create your first self-managed cluster**
>
> With the credential saved, follow [AWS Clusters](/guides/aws-clusters) - prepare the VPC and subnets, run the preflight, then create from the portal, CLI, or API. The preflight names any permission the role is missing, so a credential created at the wrong level fails there rather than mid-provisioning.

> [tab] Access keys
>
> Stores an access key ID and secret for an IAM user. What the credential can do is determined entirely by the user's IAM policy - attach the read-only policy for cost and inventory, or the provisioning policy to also create EKS clusters.
>
> **1. Create a least-privilege IAM policy**
>
> In AWS IAM, create a policy with exactly the permissions Ankra uses - these mirror the CloudFormation templates from the IAM-role method.
>
> For cost and inventory only:
>
> ```json Read-only policy theme={null}
> {
>   "Version": "2012-10-17",
>   "Statement": [
>     {
>       "Sid": "PricingAndInventory",
>       "Effect": "Allow",
>       "Action": [
>         "pricing:GetProducts",
>         "pricing:DescribeServices",
>         "ec2:DescribeInstanceTypes",
>         "ec2:DescribeInstanceTypeOfferings",
>         "ec2:DescribeAvailabilityZones",
>         "ec2:DescribeRegions",
>         "ec2:DescribeInstances"
>       ],
>       "Resource": "*"
>     },
>     {
>       "Sid": "CostExplorer",
>       "Effect": "Allow",
>       "Action": ["ce:GetCostAndUsage", "ce:GetCostForecast"],
>       "Resource": "*"
>     },
>     {
>       "Sid": "ClusterDiscovery",
>       "Effect": "Allow",
>       "Action": [
>         "eks:ListClusters",
>         "eks:DescribeCluster",
>         "sts:GetCallerIdentity"
>       ],
>       "Resource": "*"
>     }
>   ]
> }
> ```
>
> To also provision clusters - EKS and self-managed - attach the `PolicyDocument` from the [provisioning template](https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-provisioning.cfn.yaml) instead (a superset of the read-only policy; its 30 statements are listed under [Provisioning](#provisioning)). It is a long policy because every EC2 write is tag-scoped; do not simplify it to `ec2:*`.
>
> If you prefer AWS-managed policies over least privilege, the read-only level is roughly covered by `ReadOnlyAccess` plus `Billing` - but the explicit policies above grant only what Ankra actually calls.
>
> For self-managed clusters without any EKS access, attach the `PolicyDocument` from the [self-managed template](https://ankra-templates.s3.eu-north-1.amazonaws.com/aws/v1/ankra-self-managed-provisioning.cfn.yaml) instead - see the [EC2-only alternative](#self-managed-clusters-ec2-only-alternative).
>
> **2. Create an IAM user and access key**
>
> 1. In AWS IAM, create a user (or pick an existing one) and attach the policy from the previous step.
> 2. Open the user → **Security credentials** → **Create access key**, and choose a use case such as **Third-party service**.
> 3. Copy the access key ID and secret access key - the secret is shown only once.
>
> **3. Add to Ankra (UI)**
>
> Go to **Credentials** → **Add** → **AWS** → **Access keys**, then provide:
>
> * **Name**: a unique identifier for the credential
> * **Access key ID** and **Secret access key**: the values from the previous step
>
> When you save, Ankra verifies the keys with a read-only `sts:GetCallerIdentity` call.
>
> > [!NOTE]
> >
> > Use the IAM role method where you can - it avoids storing long-lived secrets, and access is revocable on the AWS side by deleting the CloudFormation stack. With access keys, you own rotation: rotate the key in IAM and update the credential in Ankra.

> [!NOTE]
>
> Already added a read-only credential and want to provision clusters? The access level of an IAM-role credential is fixed when it is created and there is no edit flow. Run the **Provisioning** tab again under a new credential name, then delete the old read-only credential in Ankra and its CloudFormation stack in AWS. A provisioning credential whose stack predates the self-managed statements is different: keep the credential and update the stack, as described under [Provisioning](#provisioning).

## Revoking Access

For an IAM-role credential, delete the CloudFormation stack in AWS - this deletes the role, and no further access is possible. For an access-keys credential, deactivate or delete the access key in IAM. Then delete the credential in Ankra.

> [!WARNING]
>
> Revoking on the AWS side while the credential is still in use breaks cost sync and, at the provisioning levels, Ankra's ability to manage your EKS or self-managed clusters - a self-managed cluster's instances keep running, but Ankra can no longer scale, upgrade, stop or tear them down. Delete or replace the Ankra credential first if clusters depend on it.

## Troubleshooting AWS Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| AWS denied the role assumption. Check the role trust policy and external ID. | The stack hasn't finished, the external ID doesn't match, the ARN is wrong or points to a nonexistent role, or the trust policy was edited | Wait for `CREATE_COMPLETE`; verify you copied the `RoleArn` value from the stack's **Outputs** tab (not the stack ARN); for an external ID mismatch see below |
| AWS rejected the supplied credentials. | The access key is deactivated or deleted, or the secret was mistyped | Check the key is active in IAM, or create a new access key and re-paste both values |
| Could not reach the AWS STS endpoint. | Network or connectivity issue, or an invalid default region | Check the **Default region** is a valid AWS region and retry |
| Could not validate the AWS credentials. Check the access key id and secret access key. | Shown on save when validation fails - for either connection method, all causes collapse to this one message | Click **Test connection** to get the specific message, then use the rows above |
| An AWS credential with this name already exists. | Credential names are unique per organisation | Pick a different name, or delete the old credential first if you are replacing it |

**External ID mismatch** is the most common cause of a denied role assumption: a fresh external ID is generated each time the wizard opens, so if you closed and reopened the Ankra dialog after launching the stack, the stack carries an old ID. Fix it in AWS: on the stack page choose **Update** → **Use existing template**, replace the `ExternalId` parameter with the ID currently shown in the Ankra dialog, and update the stack. Alternatively, delete the stack and relaunch it from the current dialog. Note that AWS reports a nonexistent role as the same access-denied error, so double-check the ARN too.

**Test connection** only verifies that the role can be assumed (or that the keys are valid) - it does not inspect the attached permissions. If the credential saves fine but cost data stays empty, inventory doesn't appear, EKS cluster creation fails with `AccessDenied`, or the self-managed create preflight reports a missing permission, the role or user is missing actions from the tables in [What Ankra Accesses](#what-ankra-accesses). For a stack-created role that usually means the template was modified, or the provisioning stack was launched before the self-managed statements were added - update the stack to the published template. For an access-keys user, re-check the policy against the JSON in the **Access keys** tab.


# Azure Credentials
Source: https://docs.ankra.ai/platform/credentials/azure

Store an Azure service principal in Ankra to provision and manage Azure Kubernetes Service (AKS), with least-privilege role assignments.

Azure credentials store an Azure **service principal** used to provision and manage [Azure Kubernetes Service (AKS)](/guides/aks-clusters). Ankra authenticates with the client-credentials grant against Microsoft Entra ID and reads the subscription's locations, Kubernetes versions, VM SKUs, quota and virtual networks to build the catalogue, then creates and operates AKS clusters in the resource groups it owns or adopts.

## Least-privilege roles

Do not grant `Contributor` on the whole subscription. Scope the service principal to what Ankra does:

| Scope | Role | Why |
| - | - | - |
| Subscription | `Reader` | Locations, Kubernetes versions, VM SKUs and availability zones, compute quota, virtual network discovery |
| Resource group(s) Ankra will own or adopt | `Azure Kubernetes Service Contributor Role` | Create, upgrade, scale, stop, start and delete AKS clusters and node pools |
| Resource group(s) Ankra will own or adopt | `Network Contributor` | Attach node pools to your subnet (`vnet_subnet_id`) and let AKS manage load balancers and public IPs |
| Subscription (only when Ankra creates resource groups) | A custom role with `Microsoft.Resources/subscriptions/resourceGroups/write` and `.../delete` | Create the `ankra-<cluster-name>` resource group and delete it with the cluster |

Grant `Network Contributor` on the resource group of the virtual network too when the subnet lives elsewhere. If you would rather not grant resource-group creation at the subscription, create the group yourself and name it at cluster creation (`aks.resource_group`); Ankra adopts it and never deletes it.

> [!WARNING]
>
> The `Azure Kubernetes Service Contributor Role` lets the principal retrieve the cluster admin kubeconfig, which Ankra needs to install its agent. Scope it to the resource groups Ankra manages, not the subscription.

## Creating an Azure credential

**1. Create the service principal**

```bash theme={null}
az ad sp create-for-rbac --name ankra-aks --skip-assignment
```

Note the `appId` (client ID), `password` (client secret) and `tenant`. The secret is shown once - store it in a secret manager, not in a shell history or a ticket.

**2. Assign the roles**

```bash theme={null}
az role assignment create --assignee <app-id> --role Reader \
  --scope /subscriptions/<subscription-id>
az role assignment create --assignee <app-id> \
  --role "Azure Kubernetes Service Contributor Role" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>
az role assignment create --assignee <app-id> --role "Network Contributor" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>
```

Repeat the resource-group assignments for every group Ankra will manage.

**3. Store it in Ankra**

```bash Portal theme={null}
# Credentials → Add → Azure: enter a name, the subscription ID, tenant ID,
# client ID and client secret. Ankra validates the principal before storing it.
```

```bash CLI theme={null}
export AZURE_CLIENT_SECRET='<client-secret>'   # or omit it and answer the masked prompt
ankra credentials azure create \
  --name azure-production \
  --subscription-id <subscription-id> \
  --tenant-id <tenant-id> \
  --client-id <app-id>
ankra credentials azure list
```

The CLI never accepts the secret as a flag: set `AZURE_CLIENT_SECRET` for automation, or let the command prompt for it.

## Rotating the secret

Create a new secret on the application in Microsoft Entra ID, update the Ankra credential, then delete the old secret. Ankra reads the credential from its vault on every provider call, so a rotation takes effect immediately.

## Related

* [AKS clusters](/guides/aks-clusters)
* [Credentials overview](/platform/credentials)


# DigitalOcean API Credentials
Source: https://docs.ankra.ai/platform/credentials/digitalocean

Store a DigitalOcean personal access token in Ankra - a Read & Write token used to provision droplet clusters and DigitalOcean Kubernetes (DOKS).

DigitalOcean API credentials store a DigitalOcean personal access token, used to provision and manage self-managed [DigitalOcean droplet clusters](/guides/digitalocean-clusters) and [DigitalOcean Kubernetes (DOKS)](/guides/doks-clusters). The token is validated when you save it - Ankra makes a read-only call to the DigitalOcean API (`GET /v2/account`), so a rejected or mistyped token is refused immediately.

## What Ankra Accesses

One token covers both cluster types. For self-managed droplet clusters, Ankra provisions the infrastructure directly:

| Resource | Operations | Why it's used |
| - | - | - |
| Droplets | create, read, power actions, delete | The cluster's nodes and bastion |
| SSH keys | upload, read, delete | Install your [SSH key credential](/platform/credentials/ssh-key) on the droplets it creates |
| VPCs | create, read, update, delete | The cluster's private network |
| Firewalls | create, read, delete | Restrict access to the cluster's droplets |
| VPC NAT gateways | create, read, delete | Outbound internet access for private nodes |
| Tags | create, delete | Group the cluster's resources for cleanup |
| Load balancers | read, delete | Created by Kubernetes itself (the DigitalOcean cloud controller) - Ankra only cleans them up when you delete the cluster |
| Regions and sizes | read | Placement options and list prices in the cluster wizard |

For [DOKS](/guides/doks-clusters), Ankra uses the managed Kubernetes API instead:

| Resource | Operations | Why it's used |
| - | - | - |
| Kubernetes clusters | create, read, delete | DOKS cluster lifecycle |
| Node pools | create, read, update, delete | Scale and manage the cluster's node pools |
| Kubeconfig | read | Connect Ankra's agent to the cluster |
| Kubernetes options | read | Available versions, regions, and node sizes in the wizard |

For cost reconciliation, Ankra also reads the account's billing:

| Resource | Operations | Why it's used |
| - | - | - |
| Invoices | read | Import each month's invoice, and the running month's invoice preview, so Ankra can set what DigitalOcean billed against its own estimate (`ankra cost reconcile`) |

## Creating a DigitalOcean API Credential

**1. Get a DigitalOcean token**

1. Log in to the [DigitalOcean Control Panel](https://cloud.digitalocean.com/account/api/tokens)
2. Go to **API** → **Tokens** → **Generate New Token**
3. Give it **Read & Write** access - with **Full Access** scopes, or custom scopes covering at least `droplet`, `ssh_key`, `vpc`, `firewall`, `tag`, `load_balancer`, and `kubernetes` (add `regions` and `sizes` read for the wizard's options, and `billing:read` so Ankra can import your invoices for cost reconciliation)
4. Copy the token (prefixed with `dop_v1_`; shown once)

**2. Add to Ankra (UI)**

Go to **Credentials** → **Add** → **DigitalOcean**, then provide:

* **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `do-prod`)
* **API Token**: the token from the previous step

Click **Test connection** to verify the token against the DigitalOcean API, then save.

**3. Or via CLI**

```bash theme={null}
ankra credentials digitalocean create --name my-do-token
# You will be securely prompted for the API token
```

For self-managed droplet clusters you also need an [SSH key credential](/platform/credentials/ssh-key) - create one with `ankra credentials digitalocean ssh-key create --name my-key --generate`.

> [!NOTE]
>
> The token can be rotated later from the credential's page without recreating the credential - everything using it picks up the new token automatically.

## Listing DigitalOcean Credentials

```bash CLI theme={null}
ankra credentials digitalocean list
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/credentials/digitalocean \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

## Troubleshooting DigitalOcean Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| DigitalOcean rejected the API token. | The token is invalid, revoked, expired, or was copied incompletely | Generate a new token and paste the full `dop_v1_...` value |
| Could not reach the DigitalOcean API. | Network or connectivity issue | Retry; ensure outbound access to `api.digitalocean.com` |
| DigitalOcean returned HTTP `<code>`. | Unexpected DigitalOcean-side response | Retry; check the [DigitalOcean status page](https://status.digitalocean.com) if it persists |

If cost reconciliation shows the DigitalOcean credential as **no billing access**, the token lacks the `billing:read` scope: DigitalOcean refused to list its invoices, so what it billed is shown as unknown, never as zero. Add the scope to a new token and rotate it in; the next import (every six hours) reads the invoices.

**Test connection** verifies the token is accepted, not that it has every scope. If the credential saves fine but provisioning later fails with a permissions error, the token is read-only or missing a scope from the lists above - generate a token with the right scopes and rotate it in on the credential's page.


# Google Cloud (GCP) Credentials
Source: https://docs.ankra.ai/platform/credentials/gcp

Store a GCP service account key in Ankra - read-only for cloud cost estimates and GKE discovery, or with provisioning roles to create GKE clusters.

GCP credentials store a service account key that Ankra uses to estimate the infrastructure cost of your clusters, discover clusters, and provision [Google Kubernetes Engine (GKE)](/guides/gke-clusters). There are two access levels, and you choose which one to grant:

* **Read-only** - cost estimates and cluster discovery only. Ankra never modifies resources.
* **GKE provisioning** - everything read-only does, plus creating and managing GKE clusters.

The key is validated against the GCP Cloud Resource Manager API when you save it, so an invalid key or a project the service account can't read is rejected immediately.

## What Ankra Accesses

For cost estimation and discovery, Ankra calls three Google APIs with the service account, all read-only:

| API | Why it's used |
| - | - |
| Cloud Resource Manager API | Verify the service account can read the project (the **Test connection** check) |
| Cloud Billing API | Read the public Compute Engine price catalog (SKUs) for cost estimates |
| Compute Engine API | Read machine-type specs (vCPU and memory) to price your nodes |

Provisioning GKE additionally uses:

| API | Why it's used |
| - | - |
| Kubernetes Engine API | Create, upgrade, scale, and delete GKE clusters and node pools |

## Creating a GCP Credential

Pick the tab that matches what you want the credential to do. Each flow is complete - follow one from top to bottom.

> [tab] Read-only (cost and discovery)
>
> Grants the **Viewer** role (`roles/viewer`) only. Ankra can price your nodes and discover clusters, but cannot create or change anything.
>
> **1. Enable the required APIs**
>
> In the [Google Cloud Console](https://console.cloud.google.com), select your project and enable the **Cloud Resource Manager API**, **Cloud Billing API**, and **Compute Engine API**.
>
> Or with the `gcloud` CLI:
>
> ```bash theme={null}
> export PROJECT_ID="your-gcp-project-id"   # replace with your real project ID
> gcloud config set project "$PROJECT_ID"
>
> gcloud services enable \
>   cloudresourcemanager.googleapis.com \
>   cloudbilling.googleapis.com \
>   compute.googleapis.com
> ```
>
> **2. Create a read-only service account**
>
> 1. Go to **IAM & Admin** → **Service Accounts** → **Create service account**
> 2. Give it a name such as `ankra-cost-readonly`
> 3. Grant it the **Viewer** role (`roles/viewer`) on the project - or a custom read-only role
>
> Or with `gcloud` (reusing the `PROJECT_ID` from the previous step):
>
> ```bash theme={null}
> gcloud iam service-accounts create ankra-cost-readonly \
>   --display-name="Ankra cost (read-only)"
>
> gcloud projects add-iam-policy-binding "$PROJECT_ID" \
>   --member="serviceAccount:ankra-cost-readonly@${PROJECT_ID}.iam.gserviceaccount.com" \
>   --role="roles/viewer"
> ```
>
> > [!WARNING]
> >
> > If this fails with `does not have permission to access projects instance [...:getIamPolicy] (or it may not exist)`, either `PROJECT_ID` is still set to the placeholder, or your account lacks the `resourcemanager.projects.setIamPolicy` permission. Confirm `echo $PROJECT_ID` shows your real project ID, and that you hold `roles/owner` or `roles/resourcemanager.projectIamAdmin` on it (otherwise ask a project admin to run this one command).
>
> **3. Create and download a JSON key**
>
> 1. Open the service account → **Keys** → **Add key** → **Create new key**
> 2. Choose **JSON** and download the file
>
> Or with `gcloud`:
>
> ```bash theme={null}
> gcloud iam service-accounts keys create ankra-key.json \
>   --iam-account="ankra-cost-readonly@${PROJECT_ID}.iam.gserviceaccount.com"
> ```
>
> The downloaded JSON must contain `client_email`, `private_key`, and `token_uri`.
>
> **4. Add to Ankra (UI)**
>
> Go to **Credentials** → **Add** → **Google Cloud (GCP)**, then provide:
>
> * **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `gcp-prod`)
> * **Project ID**: your GCP project ID (e.g. `acme-prod`)
> * **Service Account Key (JSON)**: paste the full contents of the downloaded key file
>
> Click **Test connection** to verify access, then **Add**.

> [tab] GKE provisioning
>
> Grants the **Kubernetes Engine Admin** (`roles/container.admin`) and **Service Account User** (`roles/iam.serviceAccountUser`) roles so Ankra can create and manage [GKE clusters](/guides/gke-clusters), plus **Viewer** (`roles/viewer`) so the same credential also powers cost estimates and discovery. To also create VPC networks from the cluster wizard, add **Compute Network Admin** (`roles/compute.networkAdmin`).
>
> **1. Enable the required APIs**
>
> In the [Google Cloud Console](https://console.cloud.google.com), select your project and enable the **Cloud Resource Manager API**, **Cloud Billing API**, **Compute Engine API**, and **Kubernetes Engine API**.
>
> Or with the `gcloud` CLI:
>
> ```bash theme={null}
> export PROJECT_ID="your-gcp-project-id"   # replace with your real project ID
> gcloud config set project "$PROJECT_ID"
>
> gcloud services enable \
>   cloudresourcemanager.googleapis.com \
>   cloudbilling.googleapis.com \
>   compute.googleapis.com \
>   container.googleapis.com
> ```
>
> **2. Create a provisioning service account**
>
> 1. Go to **IAM & Admin** → **Service Accounts** → **Create service account**
> 2. Give it a name such as `ankra-gke`
> 3. Grant it the **Kubernetes Engine Admin** (`roles/container.admin`), **Service Account User** (`roles/iam.serviceAccountUser`), and **Viewer** (`roles/viewer`) roles on the project
> 4. Optional: also grant **Compute Network Admin** (`roles/compute.networkAdmin`) if you want to create VPC networks directly from Ankra's cluster wizard - without it, the wizard can only attach clusters to networks that already exist
>
> Or with `gcloud` (reusing the `PROJECT_ID` from the previous step):
>
> ```bash theme={null}
> gcloud iam service-accounts create ankra-gke \
>   --display-name="Ankra GKE provisioning"
>
> gcloud projects add-iam-policy-binding "$PROJECT_ID" \
>   --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
>   --role="roles/container.admin"
>
> gcloud projects add-iam-policy-binding "$PROJECT_ID" \
>   --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
>   --role="roles/iam.serviceAccountUser"
>
> gcloud projects add-iam-policy-binding "$PROJECT_ID" \
>   --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
>   --role="roles/viewer"
>
> # optional - lets the cluster wizard create VPC networks from Ankra
> gcloud projects add-iam-policy-binding "$PROJECT_ID" \
>   --member="serviceAccount:ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com" \
>   --role="roles/compute.networkAdmin"
> ```
>
> > [!WARNING]
> >
> > If this fails with `does not have permission to access projects instance [...:getIamPolicy] (or it may not exist)`, either `PROJECT_ID` is still set to the placeholder, or your account lacks the `resourcemanager.projects.setIamPolicy` permission. Confirm `echo $PROJECT_ID` shows your real project ID, and that you hold `roles/owner` or `roles/resourcemanager.projectIamAdmin` on it (otherwise ask a project admin to run this one command).
>
> `roles/iam.serviceAccountUser` is required because GKE nodes run as the project's default compute service account - Ankra's service account must be allowed to attach it to the node pools it creates.
>
> **3. Create and download a JSON key**
>
> 1. Open the service account → **Keys** → **Add key** → **Create new key**
> 2. Choose **JSON** and download the file
>
> Or with `gcloud`:
>
> ```bash theme={null}
> gcloud iam service-accounts keys create ankra-key.json \
>   --iam-account="ankra-gke@${PROJECT_ID}.iam.gserviceaccount.com"
> ```
>
> The downloaded JSON must contain `client_email`, `private_key`, and `token_uri`.
>
> **4. Add to Ankra (UI)**
>
> Go to **Credentials** → **Add** → **Google Cloud (GCP)**, then provide:
>
> * **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `gcp-prod`)
> * **Project ID**: your GCP project ID (e.g. `acme-prod`)
> * **Service Account Key (JSON)**: paste the full contents of the downloaded key file
>
> Click **Test connection** to verify access, then **Add**.
>
> **5. Create your first GKE cluster**
>
> With the credential saved, follow [Google Kubernetes Engine (GKE)](/guides/gke-clusters) to provision a cluster from the portal, CLI, or API.

> [!NOTE]
>
> Already added a read-only credential and want to provision GKE? Grant the extra roles and enable the Kubernetes Engine API on the **same service account** (run the `add-iam-policy-binding` and `services enable` commands from the **GKE provisioning** tab with your existing account's name) - no need to create a new credential in Ankra.

## Troubleshooting GCP Credentials

For `gcloud` setup errors during service-account creation (such as `does not have permission ... (or it may not exist)`), see the warning in the **Create a service account** step above - it's almost always an unsubstituted `PROJECT_ID` placeholder or a missing `setIamPolicy` permission.

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| The service account key is not valid JSON or is missing required fields | The pasted key isn't the full JSON file | Paste the entire downloaded JSON; it must include `client_email`, `private_key`, and `token_uri` |
| Google rejected the service account credentials | The key is disabled or deleted | Confirm the key is active, or create a new JSON key |
| The service account lacks read access to this project | Missing IAM role or disabled API | Grant the **Viewer** role and enable the **Cloud Resource Manager API** |
| The project was not found | Wrong project ID | Check the **Project ID** matches your GCP project exactly |
| Could not reach the GCP Resource Manager API | Network or connectivity issue | Retry; ensure outbound access to `*.googleapis.com` |

**Test connection** only verifies read access. If the credential saves fine but GKE cluster creation fails with a permissions error, the service account is missing `roles/container.admin` or `roles/iam.serviceAccountUser`, or the **Kubernetes Engine API** is not enabled - see the **GKE provisioning** tab above.

Creating a VPC network from the cluster wizard fails with `Required 'compute.networks.create' permission` when the service account lacks **Compute Network Admin** (`roles/compute.networkAdmin`) - grant it with the optional binding from the **GKE provisioning** tab, or pick an existing network instead.


# Git Credentials
Source: https://docs.ankra.ai/platform/credentials/git

Connect Ankra to GitHub and other Git providers for GitOps configuration sync.

Git credentials let Ankra read and write the repository that holds your GitOps configuration. GitHub is connected through the Ankra GitHub App (OAuth), so there are no long-lived tokens for you to store or rotate.

## Connecting GitHub

GitHub is connected through the Ankra GitHub integration rather than a manually stored token. See the [GitHub integration guide](/integrations/github) for the full setup, including installing the GitHub App and selecting repositories.

Once connected, Ankra automatically uses the connection when syncing configurations to your GitHub repository - no credential needs to be selected per cluster.

## Other Git providers

For GitLab and other Git providers, connect the repository when wiring up [GitOps](/concepts/gitops). Ankra stores the access securely and uses it only to sync your configuration.

## Related

> [card] [GitHub integration](/integrations/github)
>
> Install the GitHub App and select repositories.

> [card] [GitOps](/concepts/gitops)
>
> How Ankra keeps Git as the source of truth.


# Hetzner API Credentials
Source: https://docs.ankra.ai/platform/credentials/hetzner

Store a Hetzner Cloud API token in Ankra - a Read & Write project token used to provision and manage Hetzner clusters.

Hetzner API credentials store a Hetzner Cloud API token, used to provision and manage [Hetzner clusters](/guides/hetzner-clusters). The token is validated when you save it - Ankra makes a read-only call to the Hetzner Cloud API (`GET /locations`), so a rejected or mistyped token is refused immediately.

> [!TIP]
>
> Don't have a Hetzner account? [Sign up for Hetzner Cloud](https://www.hetzner.com/cloud) to get started.

## What Ankra Accesses

Hetzner clusters are self-managed: Ankra provisions the servers and networking with your token, then runs Kubernetes on top. The token is used for:

| Resource | Operations | Why it's used |
| - | - | - |
| Servers | create, read, rescale, power actions, delete | The cluster's nodes and bastion |
| SSH keys | upload, read, delete | Install your [SSH key credential](/platform/credentials/ssh-key) on the servers it creates |
| Private networks | create, attach, read, delete | The cluster's private network |
| Load balancers and volumes | read, delete | Created by Kubernetes itself (the Hetzner cloud controller) - Ankra only cleans them up when you delete the cluster |
| Locations, server types, datacenters | read | Placement options and list prices in the cluster wizard |

Hetzner API tokens are project-wide - there is no per-resource scoping in Hetzner's token model, and a **Read & Write** token can manage everything in its project. Create the token in a project dedicated to Ankra-managed clusters if you want isolation from other workloads.

## Creating a Hetzner API Credential

**1. Get a Hetzner API token**

1. Log in to the [Hetzner Console](https://console.hetzner.cloud)
2. Select your project
3. Go to **Security** → **API Tokens**
4. Click **Generate API Token** with **Read & Write** permissions - a read-only token passes the save-time check but fails as soon as Ankra needs to create a server
5. Copy the token (it's only shown once)

**2. Add to Ankra (UI)**

In the new Ankra portal, go to **Integrations & alerts** → **Credentials** → **Add credential** → **Hetzner Cloud**, then provide:

* **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `hetzner-prod`)
* **API Token**: the token from the previous step

Click **Test connection** to verify the token against the Hetzner API, then save.

**3. Or via CLI**

```bash theme={null}
ankra credentials hetzner create --name my-hetzner-token
# You will be securely prompted for the API token
```

The new portal's cluster wizard asks for an [SSH key credential](/platform/credentials/ssh-key); the API, the CLI and Terraform accept a Hetzner cluster without one, and Ankra generates its own key pair for every Hetzner cluster. The organisation needs a [payment method](/platform/billing#credit-and-payment-method) before it can create one. Next: [Hetzner Clusters](/guides/hetzner-clusters).

> [!NOTE]
>
> The token can be rotated later from the credential's page without recreating the credential - everything using it picks up the new token automatically.

## Listing Hetzner Credentials

```bash CLI theme={null}
ankra credentials hetzner list
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/credentials/hetzner \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

## Troubleshooting Hetzner Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| Hetzner rejected the API token. | The token is invalid, revoked, or was copied incompletely | Generate a new token and paste the full value |
| Hetzner accepted the token but denied the request. | The token lacks access to the project's resources | Generate a **Read & Write** token for the right project |
| Could not reach the Hetzner Cloud API. | Network or connectivity issue | Retry; ensure outbound access to `api.hetzner.cloud` |
| Hetzner returned HTTP `<code>`. | Unexpected Hetzner-side response | Retry; check the [Hetzner status page](https://status.hetzner.com) if it persists |

**Test connection** verifies the token is accepted, not that it can write. If the credential saves fine but cluster provisioning later fails with a permissions error, the token is read-only - generate a **Read & Write** token and rotate it in on the credential's page.


# Morpheus API Credentials
Source: https://docs.ankra.ai/platform/credentials/morpheus

Store a Morpheus appliance URL and access token in Ankra to provision and manage self-managed Morpheus clusters.

> [!WARNING]
>
> **Closed beta.** Morpheus cluster provisioning is in [closed beta](/guides/morpheus-clusters): the workflow is stable but the surface may still change. [Contact support](/platform/support) before relying on it.

Morpheus API credentials store the Morpheus appliance URL and a long-lived API access token, used to provision and manage self-managed [Morpheus clusters](/guides/morpheus-clusters). The token is validated when you save it - Ankra calls the appliance's identity endpoint (`GET /api/whoami`). For appliances behind an SSH jumphost, the direct probe is skipped and the connection is tested during cluster provisioning instead.

> [!NOTE]
>
> Morpheus credentials are managed from the **portal or API** - there is no `ankra credentials morpheus` CLI command.

## What Ankra Accesses

Ankra drives the Morpheus appliance API with your token:

| Resource | Operations | Why it's used |
| - | - | - |
| Instances | create, read, start/stop, delete | The cluster's nodes and bastion, provisioned as Morpheus instances |
| Networks | read | Placement options for the cluster's instances |
| Groups, clouds, service plans, instance types | read | The provisioning targets and sizes offered in the cluster wizard |

There is no finer token scoping on the Morpheus side: the token acts as its user, so that user must be able to see the target group and cloud and provision instances into them.

## Creating a Morpheus API Credential

**1. Get a Morpheus access token**

In the Morpheus UI, go to **User Settings** → **API Access** and create a long-lived access token for a user that can provision into the target group and cloud.

**2. Add to Ankra (UI)**

Go to **Credentials** → **Add** → **Morpheus**, then provide:

* **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `morpheus-lab`)
* **Appliance URL**: the HTTPS address of your Morpheus appliance (e.g. `https://morpheus.example.com`)
* **Access Token**: the token from the previous step
* **Skip TLS certificate verification**: enable only for self-signed certificates on trusted networks

For appliances that are not directly reachable, expand **SSH jumphost** and set the jumphost **host** and **private key** (port defaults to 22, username to `root`).

Click **Test connection**, then save.

For Morpheus clusters you also need an [SSH key credential](/platform/credentials/ssh-key), created from the portal or generated via another provider's CLI.

> [!NOTE]
>
> The access token can be rotated later from the credential's page. The **appliance URL is fixed** - to point at a different appliance, create a new credential.

## Troubleshooting Morpheus Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| HPE Morpheus rejected the API token. | The token is invalid, expired, or revoked | Create a new access token in the Morpheus UI and re-paste it |
| Could not reach the HPE Morpheus API. | Wrong appliance URL, the appliance is not reachable from Ankra, or a TLS failure on a self-signed certificate | Check the URL; for private appliances configure the SSH jumphost; for self-signed certificates enable **Skip TLS certificate verification** |
| HPE Morpheus returned HTTP `<code>`. | Unexpected appliance-side response | Retry; check the appliance's health if it persists |
| Morpheus credential with jumphost accepted; connection test runs during cluster provisioning. | Not an error - jumphost credentials skip the direct probe | Nothing to do; the tunnel is exercised when a cluster is provisioned |

**Test connection** verifies the token identifies a user, not what that user may do. If the credential saves fine but provisioning fails, the token's user cannot see or provision into the selected group and cloud - fix the user's Morpheus role, or create a token for a user that can and rotate it in on the credential's page.


# OVH API Credentials
Source: https://docs.ankra.ai/platform/credentials/ovh

Store OVHcloud application keys, a consumer key with cloud-project rights, and a Public Cloud project in Ankra to provision OVH clusters and OVHcloud MKS.

OVH API credentials store an OVHcloud **application key**, **application secret**, **consumer key**, and Public Cloud **project ID**, used to provision and manage self-managed [OVH clusters](/guides/ovh-clusters) and [OVHcloud Managed Kubernetes (MKS)](/guides/ovh-mks-clusters). The credentials are validated when you save them - Ankra makes a signed read-only call to the OVH API (`GET /cloud/project/{project_id}/region`), so invalid keys or a consumer key without cloud-project rights are refused immediately.

## What Ankra Accesses

All calls are scoped to your Public Cloud project (`/cloud/project/{project_id}/...`) on the OVH EU API endpoint (`eu.api.ovh.com`). One credential covers both cluster types. For self-managed OVH clusters, Ankra provisions the infrastructure directly:

| Resource | Operations | Why it's used |
| - | - | - |
| Instances | create, read, power actions, delete | The cluster's nodes and bastion |
| SSH keys | upload, read, delete | Install your [SSH key credential](/platform/credentials/ssh-key) on the instances it creates |
| Private networks (vRack) and subnets | create, read, delete | The cluster's private network |
| Cloud gateways | create, read, attach, delete | Outbound internet access (egress NAT) for private nodes |
| Flavors, images, public network | read | Placement options in the cluster wizard |
| Operations | read | Poll long-running OVH operations to completion |

For [OVHcloud MKS](/guides/ovh-mks-clusters), Ankra uses the managed Kubernetes API instead:

| Resource | Operations | Why it's used |
| - | - | - |
| Kubernetes clusters (`/kube`) | create, read, delete | MKS cluster lifecycle |
| Node pools | create, read, update, delete | Scale and manage the cluster's node pools |
| Kubeconfig | read | Connect Ankra's agent to the cluster |
| Regions, versions, flavors | read | Available regions, Kubernetes versions, and node sizes in the wizard |

## Creating OVH API Credentials

**1. Generate OVH API credentials**

1. Go to [https://api.ovh.com/createToken/](https://api.ovh.com/createToken/)
2. Log in with your OVH account
3. Set the following access rules - these are exactly what the validation checks and the tables above use:
   * **GET, POST, PUT, DELETE** on `/cloud/project/*`
   * **GET** on `/cloud/project`
4. Click **Create Keys**
5. Save the **Application Key**, **Application Secret**, and **Consumer Key**

**2. Get your project ID**

1. Log in to the [OVH Control Panel](https://www.ovh.com/manager/)
2. Go to **Public Cloud** → select your project
3. Copy the **Project ID** from the dashboard URL or project settings

**3. Add to Ankra (UI)**

Go to **Credentials** → **Add** → **OVH**, then provide:

* **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `ovh-prod`)
* **Application Key**, **Application Secret**, **Consumer Key**: the keys from step 1
* **Project ID**: from step 2

Click **Test connection** to verify the keys against the OVH API, then save.

**4. Or via CLI**

```bash theme={null}
ankra credentials ovh create --name my-ovh-cred --project-id <project-id>
# You will be securely prompted for application key, application secret, and consumer key
```

For self-managed OVH clusters you also need an [SSH key credential](/platform/credentials/ssh-key).

> [!NOTE]
>
> The application key, application secret, and consumer key can be rotated later from the credential's page. The **project ID is fixed** - to target a different Public Cloud project, create a new credential.

## Listing OVH Credentials

```bash CLI theme={null}
ankra credentials ovh list
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/credentials/ovh \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

## Troubleshooting OVH Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| OVH rejected the supplied keys. | The application key, application secret, or consumer key is invalid or revoked | Regenerate the keys at [api.ovh.com/createToken](https://api.ovh.com/createToken/) and re-enter all three |
| OVH accepted the keys but the consumer key lacks the required permissions. | The consumer key's access rules don't cover cloud-project resources | Regenerate with **GET, POST, PUT, DELETE** on `/cloud/project/*` and **GET** on `/cloud/project` |
| Could not reach the OVH API. | Network or connectivity issue | Retry; ensure outbound access to `eu.api.ovh.com` |
| OVH returned HTTP `<code>`. | Unexpected OVH-side response, or a wrong project ID | Check the **Project ID** matches your Public Cloud project exactly, then retry |

Saving without testing runs the same validation and reports the same causes - for a permissions failure the save error spells out the exact access rules to regenerate with.

Consumer keys can also expire if you set a validity period at creation. If a credential that used to work starts failing with rejected keys, regenerate at [api.ovh.com/createToken](https://api.ovh.com/createToken/) (with unlimited validity if your policy allows) and rotate the three keys in on the credential's page.


# Proxmox VE API Credentials
Source: https://docs.ankra.ai/platform/credentials/proxmox

Store a Proxmox VE API URL and token in Ankra - with VM, datastore, and SDN privileges - to provision and manage self-managed Proxmox clusters.

Proxmox VE API credentials store the HTTPS Proxmox API URL and an API token, used to provision and manage self-managed [Proxmox VE clusters](/guides/proxmox-clusters). The credential is validated when you save it - Ankra calls the Proxmox API (`GET /version`) and then bootstraps any missing storage and networking (see below). For environments behind an SSH jumphost, the direct probe is skipped and the connection is tested during cluster provisioning instead.

## What Ankra Accesses

Ankra drives the Proxmox VE API with your token:

| Resource | Operations | Why it's used |
| - | - | - |
| Nodes and cluster | read | Discover nodes, pick VM IDs, and inspect capacity for placement |
| QEMU VMs | clone, configure, resize, start/stop/reboot, delete | The cluster's nodes and bastion, cloned from the cloud-init template |
| QEMU guest agent | exec, read network interfaces | Discover VM addresses and (with Tailscale) run the tailnet join |
| Storage | read, configure, upload | Find image-capable storage, download cloud images, and build the VM template |
| SDN (zones, vnets, subnets) | create, read, update, delete | The `ankra` private network with NAT and DHCP for cluster VMs |
| Node network interfaces | read, configure | Detect or create the `vmbr0` management bridge during bootstrap |

The token needs these privileges on `/` (or on the target nodes, storage, bridges and `/sdn`):

| Privilege | Used for |
| - | - |
| `VM.Allocate`, `VM.Audit`, `VM.Clone`, `VM.Config.*`, `VM.Console`, `VM.Migrate`, `VM.PowerMgmt`, `VM.Snapshot`, `VM.Snapshot.Rollback`, `VM.Backup` | Creating, configuring, resizing, powering and deleting the cluster's VMs |
| `VM.GuestAgent.Audit` | Reading VM addresses through the QEMU guest agent |
| `Datastore.AllocateSpace` | VM disks |
| `Datastore.Allocate` | Enabling `images`, `rootdir` and `import` content on a storage (bootstrap) |
| `Datastore.AllocateTemplate` | Downloading the Ubuntu cloud image for the default template (bootstrap) |
| `Datastore.Audit` | Letting the cluster's CSI driver see the storage in `/cluster/resources`, which it needs to report capacity and create volumes |
| `Sys.Audit` | Reading nodes, capacity and tasks |
| `Sys.Modify` | Converting the management interface to `vmbr0` and downloading the cloud image (bootstrap) |
| `SDN.Allocate` | Creating and applying the `ankra` SDN zone, vnet and subnet (bootstrap) |
| `SDN.Use` | Attaching VMs to the `ankra` vnet and seeing bridges in the catalogs |

Saving the credential checks the privileges that are not marked bootstrap and refuses a token that lacks any of them, naming each one: `The Proxmox VE API token lacks Datastore.Audit, SDN.Use`. The privileges marked bootstrap are exercised only while the credential is saved. Once the bootstrap has finished you can drop them, and Ankra keeps provisioning with the rest. Enabling Tailscale additionally requires `VM.GuestAgent.Unrestricted` (see [below](#tailscale-and-headscale-optional)).

A role and token with exactly this set, created on the Proxmox host:

```bash theme={null}
pveum role add AnkraProvisioner --privs "VM.Allocate,VM.Audit,VM.Backup,VM.Clone,VM.Config.CDROM,VM.Config.CPU,VM.Config.Cloudinit,VM.Config.Disk,VM.Config.HWType,VM.Config.Memory,VM.Config.Network,VM.Config.Options,VM.Console,VM.GuestAgent.Audit,VM.Migrate,VM.PowerMgmt,VM.Snapshot,VM.Snapshot.Rollback,Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit,Sys.Audit,Sys.Modify,SDN.Allocate,SDN.Use"
pveum user add ankra@pve --comment "Ankra platform"
pveum acl modify / --users ankra@pve --roles AnkraProvisioner
pveum user token add ankra@pve ankra --privsep 0
```

## Creating a Proxmox VE API Credential

**1. Create an API token in Proxmox**

1. In the Proxmox VE web UI, go to **Datacenter** → **Permissions** → **API Tokens**
2. Create a token for a user whose role carries the privileges listed above, and copy the **token ID** (`user@realm!name`) and **secret**

**2. Add to Ankra (UI)**

Go to **Credentials** → **Add** → **Proxmox VE**, then provide:

* **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `proxmox-lab`)
* **API URL**: the HTTPS address of your Proxmox API (e.g. `https://proxmox.example.com:8006`)
* **Token ID** and **Token Secret**: from the previous step
* **Skip TLS certificate verification** (`tls_insecure` in the API): enable only for self-signed certificates on trusted networks

For environments that are not directly reachable, expand **SSH jumphost & Tailscale** and set the jumphost **host** and **private key** (port defaults to 22, username to `root`). Optionally attach **Tailscale/Headscale** to have provisioned VMs join your tailnet (see below).

Click **Test connection**, then save.

**3. Or add it with the CLI**

```bash theme={null}
ankra credentials proxmox create \
  --name proxmox-lab \
  --api-url https://proxmox.example.com:8006 \
  --token-id 'ankra@pve!ankra'
```

The CLI prompts for the token secret, so it never appears in your shell history. Add `--tls-insecure` for a self-signed certificate. For a jumphost, add `--jumphost-host`, `--jumphost-private-key-file` and, if they differ from the defaults (`root`, port 22), `--jumphost-username` and `--jumphost-port`.

Saving the credential inspects every online Proxmox node and bootstraps whatever is missing:

* **Storage** — when no active storage supports VM images, Ankra enables `images` and `rootdir` on the `local` directory storage, or creates `local` at `/var/lib/vz`. The `import` content type is enabled for cloud-image downloads. A `local` storage you disabled, or restricted to some nodes, is never re-enabled or widened: Ankra refuses and asks you to change it yourself.
* **Management bridge** — when no Linux bridge exists, Ankra converts the single active Ethernet or bond management interface to `vmbr0`. Static and `manual`-method interfaces are supported (including dedicated servers where the provider assigns the IP outside Proxmox's network config); DHCP-managed interfaces cannot be converted through the Proxmox API and are refused with instructions.
* **Private network** — Ankra creates the `ankra` SDN simple zone, vnet, and subnet 10.20.0.0/16 with SNAT and dnsmasq-served DHCP, giving cluster VMs an isolated NAT'd network. Each node needs the `dnsmasq` package (`apt install dnsmasq && systemctl disable --now dnsmasq`).
* **Cloud-init template** — nodes without the `ankra-ubuntu-24-04` template get it, built automatically from the Ubuntu 24.04 cloud image. Your own templates are left alone.

The network conversion preserves the host address, gateway, uplink, and MTU. It is refused before any live change if the interface is ambiguous, has custom options, or another network change is pending. Do not edit Proxmox networking concurrently while saving the credential.

## Connecting a Proxmox VE that already runs VMs

You can connect a Proxmox VE installation that already runs your own VMs, networks and storage. Ankra only adds what it needs alongside them. It never modifies, moves or deletes anything it did not create. When the bootstrap would have to touch something of yours, it stops before making any change and tells you what to fix:

| Ankra refuses when | Because | What to do |
| - | - | - |
| An SDN zone, vnet or subnet has unapplied changes | Applying SDN in Proxmox applies **every** pending change cluster-wide, including yours | Apply or revert your changes under **Datacenter → SDN**, then save again |
| A node interface or another SDN subnet overlaps `10.20.0.0/16` | Every node would get an address and a NAT rule in that range | Free the range, or connect a host that does not use it |
| A zone or vnet named `ankra` exists but is not the network Ankra builds | Cluster VMs would land on your network | Rename or remove it |
| `local` storage is disabled or restricted to some nodes | Ankra will not re-enable or widen your storage configuration | Enable it, or give Ankra another image-capable storage |

When you create a cluster, Ankra also checks that:

* **It only clones its own template.** Without an explicit `template`, Ankra clones `ankra-ubuntu-24-04` and never one of your templates. To use your own, name it with `template`.
* **VMID 9999 is free.** The [persistent volume driver](/guides/proxmox-persistent-volumes) files every cluster volume under VMID 9999. A guest of yours with that VMID would appear to own the cluster's disks, so Ankra refuses until it is moved to another VMID. The check only sees guests the token can audit, which is every guest when the role is granted on `/` as shown above.
* **The selected hosts have the memory.** Ankra adds up the memory of every VM the cluster needs and refuses when the selected hosts do not have that much free. It does not overcommit a host your VMs run on.

Every VM Ankra creates is tagged `ankra` and `ankra-cluster-<id>`, and its description says it is managed by Ankra. In the Proxmox UI you can tell Ankra's VMs from yours at a glance. Change or delete them through Ankra, not in Proxmox.

> [!NOTE]
>
> The token ID and secret can be rotated later from the credential's page. The **API URL is fixed** - to point at a different Proxmox installation, create a new credential.

## Tailscale and Headscale (optional)

Attach Tailscale/Headscale settings to a Proxmox VE credential and every VM Ankra provisions with it installs Tailscale and joins your tailnet on first boot — each VM getting its own tailnet address, reachable across Proxmox hosts and from your own networks over an encrypted mesh.

Provide both fields, or leave both empty:

* **Tailscale login server** (`login_server` in the API) — the Headscale control-server URL (for example `https://net.ankra.dev`). Tailscale's own coordination server also works.
* **Tailscale auth key** (`auth_key`) — a reusable pre-auth key from your control server.

> [!NOTE]
>
> You can add, change, or remove Tailscale on an **existing** credential from the credential's page — no need to delete and recreate it. The stored auth key is never shown back.

Each guest joins with its own tailnet address; it does not import your other subnet routes (`accept_routes` defaults to `false` — importing the route for the guest's own SDN subnet would send its reply traffic into the tailnet and can cut it off from the bastion mid-provisioning). **Host-spread clusters use the tailnet address for cross-node traffic**: the Proxmox SDN private network is node-local, so a control plane placed on a different host than the bastion is only reachable through the tailnet. Kubeadm advertise/join, haproxy upstreams, etcd peering, and cert SANs all follow the recorded tailnet address once a guest has joined.

> [!NOTE]
>
> The tailnet join runs through the Proxmox QEMU guest agent, which requires the credential's Proxmox token to hold `VM.GuestAgent.Unrestricted` — a separate, higher privilege than the read-only `VM.GuestAgent.Audit` that address discovery already needs. A token with only `VM.GuestAgent.Audit` provisions fine until Tailscale is configured, then every VM's tailnet join fails with an API `403` on `/agent/exec`. Add `VM.GuestAgent.Unrestricted` to the token's role before enabling Tailscale on the credential.

For Proxmox clusters you also need an [SSH key credential](/platform/credentials/ssh-key) (`ankra credentials ssh-key create`).

## Troubleshooting Proxmox VE Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| Proxmox VE rejected the API token. | The token ID or secret is wrong, or the token's user lacks access | Re-check the token ID format (`user@realm!name`) and secret; verify the token's role has the privileges listed above |
| Could not reach the Proxmox VE API. | Wrong API URL, the API is not reachable from Ankra, or a TLS failure on a self-signed certificate | Check the URL (HTTPS, usually port `8006`); for private environments configure the SSH jumphost; for self-signed certificates enable **Skip TLS certificate verification** |
| Proxmox VE returned HTTP `<code>`. | Unexpected Proxmox-side response | Retry; check the Proxmox node's task log if it persists |
| Proxmox credential with jumphost accepted; connection test runs during cluster provisioning. | Not an error - jumphost credentials skip the direct probe | Nothing to do; the tunnel is exercised when a cluster is provisioned |

Saving can additionally fail with **"Could not configure Proxmox VE storage and networking"** - the bootstrap could not complete. The message ends with Proxmox's own reason. A missing privilege reads `status 403: Permission check failed (<path>, <privilege>)`, most often `SDN.Allocate` (creating the `ankra` zone) or `Datastore.AllocateTemplate` (downloading the cloud image); add it to the token's role and save again. Other common causes: the management interface is DHCP-managed (convert it to a static or `manual` configuration first), or `dnsmasq` is not installed on a node. **"Proxmox VE infrastructure setup is already running for this organisation or target"** means another save is mid-bootstrap against the same installation - wait for it to finish and retry.


# Registry Credentials
Source: https://docs.ankra.ai/platform/credentials/registry

Authenticate Ankra with Helm chart registries and container registries (HTTP and OCI).

Registry credentials authenticate with Helm chart repositories and container registries. They're used when syncing charts from private registries.

## Creating a Registry Credential

**1. Navigate to Credentials**

Go to **Credentials** in the Ankra dashboard.

**2. Add Credential**

Click **Add** and select **Registry** as the provider type.

**3. Enter Details**

* **Name**: a unique identifier (e.g., `ghcr-auth`, `harbor-prod`)
* **Username**: your registry username
* **Password**: your registry password or access token

**4. Save**

Click **Create** to securely store the credential.

## Provider-Specific Setup

> [accordion] GitHub Container Registry (GHCR)
>
> **Create a Personal Access Token:**
>
> 1. Go to GitHub → Settings → Developer settings → Personal access tokens
> 2. Generate a token with `read:packages` scope
> 3. For pushing charts, also add `write:packages`
>
> **Credential values:**
>
> * Username: your GitHub username
> * Password: the Personal Access Token

> [accordion] Google Artifact Registry
>
> **Create a Service Account:**
>
> 1. Go to Google Cloud Console → IAM → Service Accounts
> 2. Create a new service account
> 3. Grant "Artifact Registry Reader" role
> 4. Create and download a JSON key
>
> **Credential values:**
>
> * Username: `_json_key`
> * Password: the entire JSON key file contents

> [accordion] Amazon ECR
>
> **Get an auth token:**
>
> ```bash theme={null}
> aws ecr get-login-password --region us-east-1
> ```
>
> **Credential values:**
>
> * Username: `AWS`
>
> * Password: the token from the command above
>
> > [!WARNING]
> >
> > ECR tokens expire after 12 hours. Refresh the token before it expires.

> [accordion] Azure Container Registry
>
> **Create a Service Principal:**
>
> ```bash theme={null}
> az ad sp create-for-rbac --name ankra-acr-reader \
>   --scopes /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/{registry} \
>   --role acrpull
> ```
>
> **Credential values:**
>
> * Username: the `appId` from the output
> * Password: the `password` from the output

> [accordion] Docker Hub
>
> **Create an Access Token:**
>
> 1. Go to Docker Hub → Account Settings → Security
> 2. Create a new Access Token with Read permissions
>
> **Credential values:**
>
> * Username: your Docker Hub username
> * Password: the Access Token (not your password)

> [accordion] Harbor
>
> **Use a robot account (recommended):**
>
> 1. Go to your Harbor project → Robot Accounts
> 2. Create a new robot account with pull permissions
>
> **Credential values:**
>
> * Username: `robot$project+name` (the robot account name)
> * Password: the robot account secret

> [accordion] JFrog Artifactory
>
> **Create an API Key or Access Token:**
>
> 1. Go to User Profile → Edit Profile
> 2. Generate an API Key or create an Access Token
>
> **Credential values:**
>
> * Username: your Artifactory username
> * Password: the API Key or Access Token

## Using Registry Credentials

When adding a registry, select the credential to use for authentication:

1. Go to **Add-ons** → **Manage registries** → **Add**
2. Enter the registry URL
3. Select the credential from the dropdown
4. Click **Add**

Ankra will use the credential when syncing charts from the registry. See [Registries](/guides/registries) for more.


# Scaleway Credentials
Source: https://docs.ankra.ai/platform/credentials/scaleway

Store a project-scoped Scaleway API key in Ankra to build clusters on Scaleway Instances and to create or import Scaleway Kapsule clusters.

Scaleway credentials store an API key (access key and secret key) and the Scaleway Project ID it works in. Ankra uses them to build [Scaleway clusters](/guides/scaleway-clusters) on Instances and to create or import [Scaleway Kapsule](/guides/managed-kubernetes#scaleway-kapsule-closed-beta) clusters. The key is validated when you save it: Ankra reads the project with it, so a wrong key or Project ID is refused immediately.

> [!WARNING]
>
> **Closed beta.** Scaleway credentials are part of the Scaleway provider, which is in closed beta. The workflow is stable but the surface may still change, and it is enabled per organisation on request - until it is, Scaleway does not appear among the credential providers and its endpoints are not served. [Contact support](/platform/support) to have it turned on for your organisation.

## Least-privilege permissions

Create the API key on a Scaleway **IAM application** dedicated to Ankra, not on a person's account, and scope every policy rule to the one project Ankra manages. Do not grant Organization-wide scope, `IAMFullAccess`, billing administration or `KubernetesSystemMastersGroupAccess`. Scaleway groups permissions into named [permission sets](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/):

| Application | Used for | Permission sets |
| - | - | - |
| **Provisioning** | Building and deleting Instances clusters | `ProjectReadOnly`, `InstancesFullAccess`, `SSHKeysFullAccess`, `PrivateNetworksFullAccess`, `VPCFullAccess`, `VPCGatewayFullAccess`, `IPAMReadOnly`, `LoadBalancersFullAccess`, `BlockStorageFullAccess` |
| **Runtime** | The cloud controller and CSI driver inside an Instances cluster (the cluster's **Runtime credential**) | `ProjectReadOnly`, `InstancesFullAccess`, `BlockStorageFullAccess`, `LoadBalancersFullAccess`, `PrivateNetworksReadOnly`, `VPCReadOnly` |
| **Kapsule** | Creating, importing and operating Kapsule clusters | `ProjectReadOnly`, `KubernetesFullAccess`, `InstancesReadOnly`, `PrivateNetworksReadOnly`, `VPCReadOnly`, `VPCGatewayReadOnly`, `LoadBalancersFullAccess`, `BlockStorageFullAccess` |

The runtime key is installed in the cluster, which is why it should be a separate, narrower application than the provisioning one. Every credential for one cluster must target the same project. Saving a credential proves it can read the project, not that it holds every permission a later create or delete needs - run the cluster preflight too.

## Creating a Scaleway credential

**1. Create an API key in Scaleway**

In the Scaleway console, create an IAM application with a policy scoped to your project (see the table above), then generate an API key for it. Copy the access key (`SCW...`) and the secret key - Scaleway shows the secret key once. Note the Project ID from the project's settings.

**2. Add to Ankra (UI)**

Go to **Credentials** → **Add** → **Scaleway** (or **Add Scaleway Credential** in the cluster wizard), then provide:

* **Name**: a unique identifier, for example `scw-prod`
* **Access Key**: the `SCW...` access key
* **Secret Key**: the secret key
* **Project ID**: the project's UUID

Click **Test connection**, then save.

**3. Or via CLI**

```bash theme={null}
ankra credentials scaleway create --name scw-prod \
  --project-id <project-id> \
  --access-key <access-key>
# You will be securely prompted for the secret key
```

Clusters on Scaleway Instances also need an [SSH key credential](/platform/credentials/ssh-key) - create one with `ankra credentials scaleway ssh-key create --name my-key --generate`.

> [!NOTE]
>
> The access key and secret key can be rotated from the credential's **Rotation** tab without recreating the credential. The Project ID is fixed: a credential always points at the same project.

## Listing Scaleway credentials

```bash CLI theme={null}
ankra credentials scaleway list
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/credentials/scaleway \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

The credential's **Capacity** tab shows the project's usage swept across zones - servers with their vCPU and memory, storage and load balancers. Scaleway does not expose quota headroom through its APIs, so the tab shows usage only.

## Troubleshooting

| Issue | Solution |
| - | - |
| Saving fails with `Scaleway credential validation failed` | Check the Project ID and that the API key is active and allowed to read that project |
| Saving fails with a timeout | Ankra could not reach the Scaleway API; retry |
| A cluster create or delete fails with `403` | The IAM application lacks a permission set from the table above. Add it to the application's policy rather than widening the key to the Organization |


# SSH Key Credentials
Source: https://docs.ankra.ai/platform/credentials/ssh-key

Store or generate SSH keys in Ankra for server access on provisioned self-managed clusters.

SSH key credentials store public keys that are deployed to servers during cluster provisioning. You can either provide your own public key or let Ankra generate a keypair for you. They're required for self-managed clusters on providers such as [Hetzner](/platform/credentials/hetzner), [OVH](/platform/credentials/ovh), [DigitalOcean](/platform/credentials/digitalocean), [UpCloud](/platform/credentials/upcloud), [Scaleway](/platform/credentials/scaleway) (closed beta), [AWS EC2](/guides/aws-clusters), [Ankra Cloud](/platform/credentials/ankra-cloud) (closed beta), [Proxmox](/platform/credentials/proxmox), and [Morpheus](/platform/credentials/morpheus).

## Creating an SSH Key Credential

**1. Choose an approach**

* **Bring your own key**: provide an existing SSH public key
* **Generate a keypair**: create a new keypair and save the private key, which you only get once

**2. Add to Ankra (UI)**

In the new Ankra portal, go to **Integrations & alerts** → **Credentials** → **Add credential** → **SSH key**, enter a name, and either paste your public key or generate a key pair. Generating creates a 4096-bit RSA key pair in your browser and offers the private key as a `.pem` download on that page; closing the page discards it.

**3. Or via CLI**

An SSH key credential belongs to the whole organisation, so one credential can be attached to clusters on any provider.

```bash theme={null}
# Provide your own public key
ankra credentials ssh-key create --name my-key --public-key-file ~/.ssh/id_ed25519.pub

# Or let Ankra generate a keypair; the private key is written to the file you name
ankra credentials ssh-key create --name my-key --generate --private-key-file ./my-key.pem
```

With `--generate` the platform generates an RSA key pair and returns the private key once, written to the file you name.

The provider-named routes, such as `ankra credentials hetzner ssh-key create --name my-key --generate`, create the same organisation-wide credential and still work.

> [!WARNING]
>
> When generating a keypair, the private key is only returned once. Save it immediately to a secure location.

## Listing SSH Key Credentials

```bash CLI theme={null}
ankra credentials ssh-key list
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/credentials/hetzner/ssh-keys \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```


# UpCloud API Credentials
Source: https://docs.ankra.ai/platform/credentials/upcloud

Store an UpCloud API token in Ankra to provision and manage UpCloud server clusters and UpCloud Managed Kubernetes (UKS).

UpCloud API credentials store an UpCloud API token, used to provision and manage self-managed [UpCloud clusters](/guides/upcloud-clusters) and [UpCloud Managed Kubernetes (UKS)](/guides/uks-clusters). The token is validated when you save it - Ankra makes a read-only call to the UpCloud API (`GET /account`), so a rejected or mistyped token is refused immediately.

## What Ankra Accesses

One token covers both cluster types. For self-managed UpCloud clusters, Ankra provisions the infrastructure directly:

| Resource | Operations | Why it's used |
| - | - | - |
| Servers | create, read, start/stop/restart, delete | The cluster's nodes and bastion |
| SDN networks | create, read, update, delete | The cluster's private network |
| Routers | create, read, delete | Attach the private network |
| Gateways | create, read, delete | Outbound internet access (NAT) for private nodes |
| Storage templates | read | The OS image for new servers |
| Load balancers | read, delete | Created by Kubernetes itself - Ankra only cleans them up when you delete the cluster |

For [UKS](/guides/uks-clusters), Ankra uses the managed Kubernetes API instead:

| Resource | Operations | Why it's used |
| - | - | - |
| Kubernetes clusters (`/kubernetes`) | create, read, delete | UKS cluster lifecycle |
| Node groups | create, read, update, delete | Scale and manage the cluster's node groups |
| Kubeconfig | read | Connect Ankra's agent to the cluster |
| Versions, plans, zones | read | Available Kubernetes versions, node plans, and zones in the wizard |

## Creating an UpCloud API Credential

**1. Create an UpCloud API token**

1. Log in to the [UpCloud Control Panel](https://hub.upcloud.com)
2. Open the API tokens page. Where it lives depends on your account type: a workspace account has it under **Settings** → **API tokens** (`hub.upcloud.com/settings/api-tokens`), a regular account under **Account** → **API tokens** (`hub.upcloud.com/account/api-tokens`). For a scoped identity, first create a workspace member under **People** with **API connections** allowed, and create the token as that member
3. Create a token and copy it (prefixed with `ucat_`; shown once)

The token inherits the permissions of the account it belongs to - that account must be allowed to manage servers, networking, storage, and Kubernetes. A read-only or restricted member's token passes the save-time check but fails when Ankra provisions.

**2. Add to Ankra (UI)**

Go to **Credentials** → **Add** → **UpCloud**, then provide:

* **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `upcloud-prod`)
* **API Token**: the `ucat_...` token from the previous step

Click **Test connection** to verify the token against the UpCloud API, then save.

**3. Or via CLI**

```bash theme={null}
ankra credentials upcloud create --name my-upcloud
# You will be securely prompted for the API token
```

For self-managed UpCloud clusters you also need an [SSH key credential](/platform/credentials/ssh-key) - create one with `ankra credentials upcloud ssh-key create --name my-key --generate`.

> [!NOTE]
>
> The token can be rotated later from the credential's page without recreating the credential - everything using it picks up the new token automatically.

## Listing UpCloud Credentials

```bash CLI theme={null}
ankra credentials upcloud list
```

```bash cURL theme={null}
curl https://platform.ankra.app/api/v1/credentials/upcloud \
  -H "Authorization: Bearer $ANKRA_API_TOKEN"
```

## Troubleshooting UpCloud Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result | Cause | Solution |
| - | - | - |
| UpCloud rejected the API token. | The token is invalid, revoked, expired, or was copied incompletely | Create a new token and paste the full `ucat_...` value |
| Could not reach the UpCloud API. | Network or connectivity issue | Retry; ensure outbound access to `api.upcloud.com` |
| UpCloud returned HTTP `<code>`. | Unexpected UpCloud-side response | Retry; check the [UpCloud status page](https://status.upcloud.com) if it persists |

**Test connection** verifies the token is accepted, not what its account may manage. If the credential saves fine but provisioning later fails with a permissions error, the token's account is restricted - allow it to manage servers, networking, storage, and Kubernetes, or create a token for a less restricted account and rotate it in on the credential's page.


# Dashboard
Source: https://docs.ankra.ai/platform/dashboard

Start the day on one screen - what changed since your last visit, what needs you, and how the whole fleet is doing.

When you sign in you want to know what broke overnight, what is waiting on you and which cluster to open first. The Dashboard answers that for the organisation you have selected, from top to bottom in that order.

> [!NOTE]
>
> The Dashboard only shows clusters in the organisation you currently have selected. Switch organisations from the profile menu or the [command palette](/platform/command-palette) (**Switch Organisation**) to see a different fleet.

## Briefing

The line at the top summarises what changed since your last visit - for example operations that ran or failed, plans approved, AI sessions that completed and how cloud spend is pacing this month. Each sentence links to where it came from. When nothing needs you it says so. A new organisation also sees a setup checklist here.

## Your clusters

Quick links to the clusters you subscribe to, so the ones you work on every day are one click away. **Browse clusters** opens the full cluster list.

## Needs your attention

Approvals, failures and alerts waiting on you, in one place:

* **Inbox** - the same personal worklist as [Activity & Inbox](/platform/activity-inbox): plans to approve, actions to confirm, failed steps and AI sessions waiting for an answer.
* **Active alerts** - alerts firing across the fleet. See [Alerts](/guides/alerts).
* **Fleet issues** - offline clusters, failed reconciles and unhealthy add-ons, most severe first. **Diagnose with AI** hands an issue to the [AI Assistant](/platform/ai-assistant) with its context attached.

## Fleet overview

Everything running across the organisation:

* **Fleet globe** - each cluster at its real location. Tower height follows node count and colour follows live status; select a cluster to open it.
* **Fleet pulse** - clusters online, GitOps health, failing resources, and cloud spend with the projected month-end total by provider and by top cluster. The full breakdown is in [Cloud Cost](/platform/cloud-cost).
* **Fleet Security** - actionable critical and high findings across the fleet, with the worst cluster. Opens the [Security Center](/guides/cluster-security).
* **Failure domains** - which clusters survive losing a zone and which lose quorum.
* **Fleet Backups** - backup posture and the worst cluster, when backups are enabled for your organisation.
* **CPU and memory** across the fleet.

### Clusters missing from the globe

Ankra places a cluster from its nodes' `topology.kubernetes.io/region` label first, and otherwise from the public IP the agent reports, which gives an approximate location. A cluster with neither is listed separately instead of on the globe:

| Reason | Meaning | Fix |
| - | - | - |
| `no_region_label` | No region label on the nodes and no public IP reported | Turn on public IP reporting on the agent with the Helm value `public_ip.reporting_enabled=true` - see [Cluster Agent](/concepts/cluster-agent#fleet-world-map-public-ip-reporting) |
| `unknown_region` | The region label is set, but Ankra has no coordinates for it | Nothing to fix - only the map pin is missing |

Draft and archived clusters never appear on the globe.

## Next step

Open the first item under **Needs your attention**. If it is a failed deploy, [find out why it failed and retry it](/platform/operations).


# Debug Pods
Source: https://docs.ankra.ai/platform/debug-pods

Spin up a pod that impersonates a workload - same service account, node, volumes and environment - under an image that has the tools you need, and open a recorded terminal into it.

A **debug pod** is a pod Ankra creates on your behalf, in any namespace of a cluster, from an image chosen for its tools rather than for the workload. Point it at an existing pod and it **impersonates** that pod: the same service account, the same node, the same volumes and volume mounts, the same environment variables and `envFrom` sources, the same tolerations and security context. What the workload's container sees, the debug pod sees - from a shell that actually has `curl`, `dig`, `psql` or `strace` in it.

The workload itself is never touched. Unlike `kubectl debug`'s ephemeral containers, nothing is injected into the running pod; the debug pod is a separate object that copies the running pod's shape.

***

## When to reach for one

* The image is **distroless** or has no shell, so the pod terminal cannot attach.
* The pod is **crash-looping** and you need to inspect what it would have seen: the mounted config, the secret it could not read, the hostname it could not resolve.
* You want to check a **volume's contents or permissions** - a PVC, a projected ConfigMap - exactly as the workload mounts them.
* You need a scratch shell **in a namespace** with the namespace's network policies and DNS, with nothing mirrored at all.

***

## Creating a debug pod

**1. From a pod, or from the pods list**

On a pod's page, click **Debug**. On **Kubernetes → Workloads → Pods**, click **New debug pod** to start from a namespace instead of a pod.

**2. Choose an image**

Pick one from the catalogue - **netshoot** (the default: network and system troubleshooting tools plus database clients), **busybox**, **alpine**, or **ubuntu** - or enter a custom image reference. Every catalogue image is pinned to a tag.

**3. Choose what to mirror**

When you started from a pod, pick which of its containers to mirror (the first one by default; init containers are offered too) and leave **Mirror volume mounts** and **Mirror environment variables** on unless you specifically want a clean shell.

**4. Set a lifetime**

30 minutes to 8 hours, one hour by default. The pod ends itself when the lifetime is up whether or not anyone deletes it.

**5. Create and open terminal**

Ankra waits for the pod to start and drops you into its [terminal](/platform/pod-terminal). If the image cannot be pulled or a mirrored reference cannot be resolved, the pod is removed again and the reason is shown.

From the CLI:

```bash theme={null}
# Impersonate a pod and drop straight into a shell in the debug pod
ankra cluster debug create --namespace payments --from-pod api-6d8f9c7b5-x2kq9 --attach

# A plain shell in a namespace, with a specific image and a two-hour lifetime
ankra cluster debug create --namespace payments --image docker.io/library/alpine:3.21 --ttl 2h

ankra cluster debug images     # the catalogue
ankra cluster debug list       # every debug pod on the cluster
ankra cluster debug delete debug-api-6d8f9c7b5-x2kq9-7f3a --namespace payments

# Open a shell in a debug pod (or any pod) later
ankra cluster terminal debug-api-6d8f9c7b5-x2kq9-7f3a --namespace payments
```

Without `--attach` the CLI creates the pod and prints the portal link to its terminal; `--attach` (and `ankra cluster terminal`, which works on any pod) opens the shell in the terminal you are in, through the platform, with the session recorded exactly like a portal one. See [Pod Terminal → From the CLI](/platform/pod-terminal#from-the-cli).

***

## What is mirrored, and what is not

| Mirrored from the target pod | Deliberately not mirrored |
| - | - |
| Service account (and whether its token is mounted) | **Labels** - a copy of the workload's labels would put the debug pod behind its Service, inside its PodDisruptionBudget and its NetworkPolicy peers |
| Node (`nodeName`), so volumes that attach to one node attach here too | Host namespaces (`hostNetwork`, `hostPID`, `hostIPC`) |
| Volumes and the chosen container's volume mounts | The projected service-account token volume - Kubernetes projects a fresh one for the debug pod's own identity |
| `env` and `envFrom` of the chosen container | The workload's image, command and probes |
| Tolerations, pod and container security contexts, resource requests and limits, working directory | |
| Image pull secrets, DNS policy and config, host aliases, runtime class | |

Some mirrored volumes cannot hold the target's data - an `emptyDir` is a fresh empty directory, an ephemeral claim is a new one, a `downwardAPI` volume describes the debug pod rather than the target. They are still mounted, because the mount path and its permissions are usually what is being debugged, and each one is named in the warnings shown after creation.

Because the security context and resources are copied verbatim, a debug pod is admitted wherever its target is: Pod Security levels, LimitRanges and ResourceQuotas all see the same shape.

Without a target, a debug pod is a plain pod of the chosen image with no service-account token.

***

## Lifetime and cleanup

Every debug pod carries `activeDeadlineSeconds`, so the kubelet ends it at its lifetime even if Ankra never comes back to delete it. The cluster agent additionally removes debug pods that have expired or terminated, and never touches a pod that does not carry the `ankra.io/debug-pod=true` label. Delete one early from its page, from the pods list, or with `ankra cluster debug delete`.

A debug pod is recognised by its label and annotations, never by its name:

| Key | Meaning |
| - | - |
| `ankra.io/debug-pod=true` | This is a debug pod (label) |
| `ankra.io/debug-target-pod`, `ankra.io/debug-target-container` | What it impersonates |
| `ankra.io/debug-requested-by` | Who asked for it |
| `ankra.io/debug-created-at`, `ankra.io/debug-expires-at` | When it started and when it ends |

***

## Permissions and audit

Creating a debug pod needs both `kubernetes.write` (it creates a pod) and `kubernetes.exec` (its purpose is a shell, and mirroring a workload's environment is an effective read of its secrets). Deleting one needs `kubernetes.write`. The built-in **operator**, **admin** and **owner** roles hold both; **member** and **viewer** hold neither.

Every create and delete writes an [audit log](/guides/audit-log) row (`create_debug_pod`, `delete_debug_pod`) naming the namespace, pod, image, what was mirrored and who asked - including a create the cluster refused. Every terminal session into a debug pod is recorded, like every other pod terminal session: see [Pod Terminal → Recorded sessions](/platform/pod-terminal#recorded-sessions).

> [!WARNING]
>
> A mirrored environment is the workload's environment. A debug pod's shell can print any secret the workload receives through `env` or `envFrom`, and the session recording will contain it. Treat transcript access (`audit.read`) accordingly.

***

## Requirements

* The **cluster agent** must be online and at version **2.1.1074** or newer. An older agent answers `AGENT_OUTDATED` and names the upgrade.
* The chosen image must be pullable from the target namespace - a custom image from a private registry needs the same pull secret the workload uses (mirrored automatically when you impersonate a pod).
* Debug pods are not available on sandbox clusters.


# Keyboard Shortcuts
Source: https://docs.ankra.ai/platform/keyboard-shortcuts

Navigate Ankra faster with keyboard shortcuts

> [!NOTE]
>
> Ankra is designed for keyboard-first navigation. Press `⌘+Enter` (Mac) or `Ctrl+Enter` (Windows/Linux) anywhere to view all shortcuts.

## Global Shortcuts

These shortcuts work from anywhere in Ankra:

| Action | Mac | Windows/Linux |
| - | - | - |
| Open Command Palette | `⌘ + K` | `Ctrl + K` |
| View Keyboard Shortcuts | `⌘ + Enter` | `Ctrl + Enter` |
| Toggle AI Panel | `⌘ + J` | `Ctrl + J` |
| Toggle AI Fullscreen | `⇧ + ⌘ + J` | `Shift + Ctrl + J` |
| New AI Chat | `⇧ + ⌘ + O` | `Shift + Ctrl + O` |
| Collapse Sidebar | `⌘ + B` | `Ctrl + B` |
| Hide Sidebar | `⇧ + ⌘ + B` | `Shift + Ctrl + B` |
| Close Dialog/Palette | `Esc` | `Esc` |

***

## Command Palette Navigation

When the command palette is open (`⌘+K` / `Ctrl+K`):

| Action | Shortcut |
| - | - |
| Navigate Up | `↑` |
| Navigate Down | `↓` |
| Select Item | `Enter` |
| Close Palette | `Esc` |

> [!TIP]
>
> The command palette uses fuzzy search. Type "dep" to find "Deployments" or "sts" for "StatefulSets".

***

## Tab Navigation

Pages with multiple tabs support keyboard navigation using the first letter of each tab name.

### Alerts Page

| Action | Shortcut |
| - | - |
| Switch to Alerts tab | `A` |
| Open the AI Inbox, where AI incidents live (AI section) | `I` |

### Resource Detail Pages

Most detail pages (pods, deployments, services, etc.) support tab shortcuts:

| Action | Shortcut |
| - | - |
| Overview tab | `O` |
| Events tab | `E` |
| Logs tab | `L` |
| YAML tab | `Y` |
| Metrics tab | `M` |

> [!NOTE]
>
> Tab shortcuts only work when you're not focused on an input field or text area.

***

## AI Assistant Shortcuts

| Action | Mac | Windows/Linux |
| - | - | - |
| Open AI Panel | `⌘ + J` | `Ctrl + J` |
| Close AI Panel | `⌘ + J` | `Ctrl + J` |
| Toggle Fullscreen | `⇧ + ⌘ + J` | `Shift + Ctrl + J` |
| Start New Chat | `⇧ + ⌘ + O` | `Shift + Ctrl + O` |

***

## Quick Reference Card

> [card] Essential Shortcuts
>
> * `⌘/Ctrl + K` - Command Palette
> * `⌘/Ctrl + J` - AI Assistant
> * `⌘/Ctrl + B` - Toggle Sidebar
> * `Esc` - Close dialogs

> [card] Power User
>
> * `⌘/Ctrl + Enter` - All shortcuts
> * `⇧ + ⌘/Ctrl + O` - New AI chat
> * `⇧ + ⌘/Ctrl + J` - AI fullscreen
> * Tab letters for navigation

***

## Tips for Keyboard Navigation

> [!TIP]
>
> **Learn the Command Palette first:** `⌘+K` / `Ctrl+K` is your gateway to navigating anywhere in Ankra without touching the mouse.

> [!TIP]
>
> **Use tab shortcuts on detail pages:** When viewing a pod, deployment, or other resource, press the first letter of the tab you want to switch to.

> [!TIP]
>
> **Keep AI handy:** `⌘+J` / `Ctrl+J` instantly opens the AI assistant for troubleshooting help without leaving your current context.

> [!TIP]
>
> **Chain shortcuts:** Open command palette (`⌘+K`), navigate to a cluster, then use it again to jump to specific resources, all without clicking.

***

## Related

* [Command Palette](/platform/command-palette) - Search and navigate with the command palette
* [AI Assistant](/platform/ai-assistant) - Get help from the AI assistant
* [Support](/platform/support) - Get help from the Ankra team


# Kubernetes Resources
Source: https://docs.ankra.ai/platform/kubernetes-insights

Browse every Kubernetes resource in a cluster and act on it - logs, manifest edits, audited secret reveals, events and the AI - without a kubeconfig.

You need to see what is really running in a cluster, and fix it, without switching kubectl contexts or handing out kubeconfigs. Every cluster connected to Ankra has a **Kubernetes** menu in its sidebar that lists the resources the Ankra Agent reports, and lets you act on them within your organisation permissions.

This page covers what Ankra adds on top of the Kubernetes objects and where each one lives in the menu. For what a Deployment or a PersistentVolume is, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/).

## Where Everything Is

Open a cluster, then **Kubernetes** in the cluster sidebar. Most resources sit one submenu deeper:

| Menu path | Resources |
| - | - |
| **Kubernetes** | Namespaces, Events, Nodes, CRDs, Helm Releases |
| **Kubernetes → Workloads** | CronJobs, DaemonSets, Deployments, StatefulSets, HorizontalPodAutoscalers, Jobs, Pods, ReplicaSets |
| **Kubernetes → Networking** | Ingress Classes, Ingresses, Services |
| **Kubernetes → Storage** | Persistent Volumes, Persistent Volume Claims, CSI Drivers, Storage Classes |
| **Kubernetes → Configs** | ConfigMaps, Secrets |
| **Kubernetes → RBAC** | Cluster Role Bindings, Cluster Roles, Network Policies, Pod Disruption Budgets, Role Bindings, Roles, Service Accounts |

Network Policies and Pod Disruption Budgets are under **RBAC**, not Networking or Workloads. Endpoints, LimitRanges, CSINodes and VolumeAttachments have no menu entry; read them with the CLI, which takes any kind:

```bash theme={null}
ankra cluster get resources LimitRange -n my-namespace
ankra cluster get resources Endpoints -n my-namespace
```

## What Every Resource Page Adds

Lists filter by namespace and name, and you can select several rows and delete them in one go. Click a resource to open its page. Across resource types you get:

* **Manifest** - the live YAML. Click **Edit**, change it, then **Apply** to send the change to the cluster.
* **Events** - on Deployments, StatefulSets, DaemonSets, ReplicaSets, HorizontalPodAutoscalers, Pods and Services, the Kubernetes events for that object. The cluster-wide list is **Kubernetes → Events**.
* **Resource Map** - on ConfigMaps, Secrets and Services, a graph of the workloads and other objects connected to it.
* **Security** - on Deployments, StatefulSets, DaemonSets, ReplicaSets and Pods, the vulnerability scan results for that workload. See [Cluster Security](/guides/cluster-security).
* **Managed by Ankra** - a badge on anything a [Stack](/concepts/stacks) deployed, naming its stack and manifest or add-on, with its sync status, such as **Synced** or **Out of Sync**. Change such a resource in its Stack, not on the resource page: the Stack is the source of truth.
* **Freshness** - each page shows when its data was last updated, and a banner says when the agent is disconnected and you are looking at cached data. A resource deleted from the cluster keeps its page, marked as deleted.
* **AI** - press `⌘+J` (`Ctrl+J`) on any resource page and the [AI Assistant](/platform/ai-assistant) starts with that resource as its context. Where [AI Insights](/platform/ai-insights) has flagged the resource, a banner offers **Ask AI**.

## Workloads

**Kubernetes → Workloads**. Deployments, StatefulSets and DaemonSets have a **Restart** button for a rolling restart, next to **Delete**. Their pages have **Overview**, **Pods**, **Events**, **Manifest** and **Security** tabs; CronJobs list the Jobs they created.

A pod page has **Overview**, **Logs**, **Terminal**, **Metrics**, **Events**, **Volumes**, **Manifest** and **Security** tabs, each with a single-key shortcut. The pod-level tools have their own guides:

* [Logs](/platform/logs) - stream and search container logs, or search across the cluster.
* [Pod Terminal](/platform/pod-terminal) - a recorded shell in a running container.
* [Debug Pods](/platform/debug-pods) - a pod that impersonates this one under an image with the tools you need.
* [Cluster Metrics](/platform/cluster-metrics) - CPU and memory for nodes and pods.

## Networking

**Kubernetes → Networking** holds Services, Ingresses and Ingress Classes. A Service page has a **Pods** tab listing the pods its selector matches, which is the quickest way to see why a Service has no backends, and a **Resource Map** linking it to its pods, Ingresses and Network Policies. An Ingress page lists each rule with its host, path and backend Service.

Clusters Ankra creates can include a networking stack at create time: Traefik as the ingress controller, cert-manager and a Let's Encrypt issuer. Network Policies are under **Kubernetes → RBAC**; [Cluster Security](/guides/cluster-security) scores how tightly they are scoped.

## Storage

**Kubernetes → Storage** holds Persistent Volumes, Persistent Volume Claims, Storage Classes and CSI Drivers. The Persistent Volumes list shows each volume's **Reclaim Policy**, and the Storage Classes list shows each class's **Reclaim Policy** and whether it allows volume expansion.

> [!WARNING]
>
> **Changing a Stack can delete volume data.** Removing a manifest from a Stack, or renaming one, makes Ankra delete the objects in it, PersistentVolumeClaims included. With a `Delete` reclaim policy, the default for most CSI drivers, the disk behind the claim is destroyed too. Read [Protect Persistent Data Before Changing a Stack](/guides/protect-persistent-data) before you rename or remove a manifest that holds a namespace or a claim.

## Configs

**Kubernetes → Configs** holds ConfigMaps and Secrets. Both pages have a **Resource Map** showing which workloads mount or read the object.

A Secret opens with its key names only; the values stay hidden. To see them, click **Reveal values** on the Secret's **Data** card. That needs the `kubernetes.secrets_reveal` permission, which the `owner`, `admin` and `operator` roles hold, and each reveal is written to the [audit log](/guides/audit-log). After a reveal, click the eye icon next to a key to show its decoded value, or the copy icon to copy it, and **Hide values** when you are done. Without the permission the card says so instead of offering the button.

The **Manifest** tab shows the Secret with value digests until you reveal it, and can only be edited after a reveal, so a save never writes digests over the real values. A digest (`hmac-sha256:` and 32 characters) changes when its value changes. It is keyed per cluster with a key only the platform holds, so it cannot be used to check a guessed value, and the same value on two clusters shows two different digests.

From the terminal, `ankra cluster get secrets` shows the same thing: key names, and each value as a `sha256:` digest followed by 12 hex characters. To read one Secret's values, name it, give its namespace and add `--reveal`:

```bash theme={null}
ankra cluster get secrets db-credentials -n default --reveal -o yaml
```

`--reveal` needs the same `kubernetes.secrets_reveal` permission, and each reveal is written to the audit log like one from the console. It reads exactly one Secret, so it is refused on a listing: without a name, with `-A` or with `-l`. Values under `data` stay base64-encoded, as `kubectl` prints them. The command exits 7 when your role lacks the permission, 3 when the Secret does not exist, and 1 when the platform cannot read live values, for example because the cluster is not connected.

To keep secrets out of plain text in Git, see [SOPS Secrets](/guides/sops). For values shared across clusters and stacks, use [Variables](/concepts/variables) instead of hand-edited ConfigMaps.

## RBAC

**Kubernetes → RBAC** shows the Kubernetes RBAC objects inside the cluster: Roles and Cluster Roles (with a **Rules** tab), their bindings, Service Accounts, plus Network Policies and Pod Disruption Budgets.

This is not where you give a teammate access. Ankra has its own access control:

* [Roles & Access](/guides/roles-and-access) decides what each member can do in Ankra, per organisation, cluster or cluster group.
* [Cluster Access](/guides/cluster-access) grants a member `kubectl` access to a cluster. Ankra turns each grant into a RoleBinding or ClusterRoleBinding, which then appears in this menu.

## Namespaces, Events, CRDs and Helm Releases

* **Namespaces** - a namespace page adds **Workloads** and **Metrics** tabs for everything in it.
* **Events** - every Kubernetes event in the cluster, in one list.
* **CRDs** - every CustomResourceDefinition, and the custom resources of each one.
* **Helm Releases** - every Helm release, with **Overview**, **Values**, **Manifest**, **Notes**, **History** and **Resources** tabs. For a release you installed yourself you can edit its values and apply a Helm upgrade, **Roll back** to an earlier revision, or uninstall it. For a release an Ankra add-on owns these are disabled, because the add-on would re-apply its own version; change it from the add-on instead. See the [Add-on catalog](/platform/addon-catalog).

  Passwords, tokens and keys in a release stay hidden: in its values, in the Secrets it renders and in its notes, each one shows as a `[REDACTED:...]` placeholder. To see them, click **Reveal values** on the **Values** tab. That needs the `kubernetes.secrets_reveal` permission, and each reveal is written to the [audit log](/guides/audit-log). The values can only be edited after a reveal, so an upgrade never writes a placeholder over a real password; an upgrade that still carries one is refused.

## Nodes

**Kubernetes → Nodes** shows the Kubernetes Node objects, with **Overview**, **Pods**, **Metrics** and **Manifest** tabs for each node. See [Kubernetes Nodes](/platform/kubernetes-nodes). To add, remove or resize the machines themselves, use **Nodes** in the cluster sidebar, described in [Cluster Nodes](/platform/cluster-nodes).

## Next Steps

Start from a problem: open the failing workload under **Kubernetes → Workloads**, check its **Events** tab, then its pod's **Logs**. If the cause is still unclear, press `⌘+J` and ask the [AI Assistant](/platform/ai-assistant) about the resource you are on.


# Kubernetes Nodes
Source: https://docs.ankra.ai/platform/kubernetes-nodes

Inspect a node's health, capacity, placement, GPUs and cached images, and act on it

> [!NOTE]
>
> The node page answers "what is this machine, is it healthy, and what can it run?" in one screen - including the accelerator on a GPU node.

## Accessing nodes

Navigate to your cluster and click **Kubernetes → Nodes** in the sidebar, then click a node. The same page is reachable from the cluster overview's node table and the Command Palette (`⌘+K`).

From the CLI, list the nodes or describe one node with its events:

```bash theme={null}
ankra cluster get nodes
ankra cluster describe node <name>
```

***

## The node header

Chips carry state, the fact strip carries identity:

* **Readiness** - `Ready`, `NotReady` or `Unknown` from the kubelet's `Ready` condition, plus **Scheduling disabled** when the node is cordoned.
* **Role** - `Worker`, `Control Plane` or any other `node-role.kubernetes.io/*` label.
* **Accelerator** - on a GPU node, the GPU count and product (`1× NVIDIA H100 80GB HBM3`).
* **Age, instance type, location (provider · region · zone), node group, kubelet version and internal IP.**

Everything that describes the host itself (operating system, kernel, runtime, architecture, addresses) lives in the **Host** card below.

The **⋯ Actions** menu holds cordon, uncordon, drain and delete.

***

## Overview tab

### Stat tiles

One figure per tile, always the **allocatable** amount: **CPU**, **Memory**, **GPU** (only on accelerator nodes), **Storage** and **Pods** - the last one counts the pods placed on the node against its `pods` capacity. Capacity and the kubelet's reservation are in the **Allocatable** card.

### Accelerator

When a node advertises a GPU resource (`nvidia.com/gpu`, an `nvidia.com/mig-*` profile, `amd.com/gpu`, `gpu.intel.com/*`, `habana.ai/gaudi`) or carries NVIDIA GPU Feature Discovery labels, an **Accelerator** card appears under the tiles. On an NVIDIA node it reads the labels the GPU operator stamps on the node:

| Fact | Source label |
| - | - |
| Product, family, compute capability | `nvidia.com/gpu.product`, `nvidia.com/gpu.family`, `nvidia.com/gpu.compute.*` |
| GPU count and memory per GPU | `nvidia.com/gpu.count`, `nvidia.com/gpu.memory` |
| CUDA driver and runtime | `nvidia.com/cuda.driver-version.full`, `nvidia.com/cuda.runtime-version.full` (or the legacy split `cuda.driver.*` / `cuda.runtime.*` labels) |
| Sharing | `nvidia.com/gpu.sharing-strategy` and `nvidia.com/gpu.replicas` (time-slicing, MPS), `nvidia.com/mig.*` (MIG capability, strategy, active profile and its state), `nvidia.com/mps.capable`, `nvidia.com/vgpu.present` |
| Driver upgrade | `nvidia.com/gpu-driver-upgrade-state` and the `nvidia.com/gpu-driver-upgrade-enabled` annotation |
| GPU operator components | every `nvidia.com/gpu.deploy.*=true` label |

The card leads with the five facts that decide what can run: GPU count × memory, CUDA driver, CUDA runtime, sharing strategy and (on MIG-capable parts) the MIG configuration. **More details** reveals MPS and vGPU capability, the driver-upgrade state, compute mode, machine type, when discovery last ran, the operator components deployed, and how many GPUs the device plugin currently advertises as allocatable.

A node whose driver is still installing shows **Not advertised yet** - the labels are there but `nvidia.com/gpu` has no allocatable capacity, so nothing can be scheduled on it yet.

#### Live telemetry

With a [Prometheus metrics source](/integrations/prometheus) connected, the Accelerator card reads the DCGM exporter the GPU operator ships and shows, per GPU: utilisation, framebuffer in use, temperature, power draw, SM clock, memory bandwidth, the last XID error if there is one, and the pod currently attached to the GPU. A **GPU workloads** list underneath names every pod on the node requesting a GPU resource, linked to its pod page.

The queries match DCGM series on the node's `Hostname` label (the GPU operator sets it from the node name), falling back to `kubernetes_node` and `node` for scrape configurations that relabel it. If Prometheus is connected but has no DCGM series for the node, the card says so rather than showing empty gauges - check that the exporter's ServiceMonitor is being scraped.

### Conditions

One row per kubelet condition: a health dot, the condition, its reason and when it last changed. Pressure conditions (`MemoryPressure`, `DiskPressure`, `PIDPressure`, `NetworkUnavailable`) are healthy when `False` and a **Problem** when `True`; `Ready` is the other way round. Only a condition that needs attention shows its label and the kubelet's message; the card's subtitle says how many do.

### Host

Operating system, architecture, kernel and container runtime, every address the kubelet reports, the pod CIDR(s) and the cloud provider with its instance ID. **Identifiers** reveals the machine ID, system UUID, boot ID and full provider ID with one-click copy.

### Allocatable

Allocatable against capacity for every resource the node reports - CPU, memory, ephemeral storage, pods, huge pages and extended resources such as `nvidia.com/gpu` or MIG profiles - with a bar showing the share the scheduler can actually use.

### Scheduling

Whether the node is cordoned, and its taints with their effect (`NoExecute` is highlighted).

### Labels, annotations and cached images

Three collapsed panels at the end of the page, each with a count in its header:

* **Labels** grouped by prefix (`nvidia.com`, `feature.node.kubernetes.io`, `topology.kubernetes.io`, …). Large groups start collapsed; type in **Search labels** to find a key or value across every group, and click a label to copy `key=value`.
* **Annotations**, with copy and expand for long values.
* **Cached images** - what the kubelet has pulled, largest first, with the total on disk in the header.

***

## Pods tab

Every pod scheduled on the node with phase, readiness, restarts and age, with bulk delete. The tab badge shows the pod count.

***

## Metrics tab

The node's Metrics tab reads your connected Prometheus, not the built-in platform metrics. With a [Prometheus metrics source](/integrations/prometheus) connected: CPU, memory, disk and network usage over the selected time range. On a GPU node a **GPU** section follows with utilisation, memory used, power draw and temperature charts per GPU.

Without a metrics source, the tab explains how to connect one.

***

## Manifest tab

The node's full manifest, editable in place.

***

## Related

* [Cluster metrics](/platform/cluster-metrics) - built-in metrics and a connected Prometheus
* [Kubernetes Resources](/platform/kubernetes-insights)
* [Managed Kubernetes](/guides/managed-kubernetes) - node groups on cloud clusters


# Logs
Source: https://docs.ankra.ai/platform/logs

Stream and analyze real-time logs from your Kubernetes workloads in Ankra

A pod is crash-looping or returning errors and you need to see what it printed, across every replica, without setting up `kubectl` access first. The **Logs** page streams live logs from any workload in the cluster through the Ankra agent.

## What you can do

* **Stream real-time logs** from any workload in your cluster
* **View logs from multiple pods** simultaneously
* **Filter and search** within log output
* **Switch between containers** in multi-container pods
* **Customize display** with font size, line wrapping, and colour highlighting

***

## Accessing Logs

There are two ways to access logs in Ankra:

### Cluster Logs

Navigate to **Logs** in the cluster sidebar to access the cluster-wide log viewer. This allows you to:

1. Select any workload (Deployment, StatefulSet, or DaemonSet)
2. View logs from all pods belonging to that workload
3. Switch between pods without leaving the page

### Pod Logs

Navigate to **Kubernetes → Pods**, click on a pod, and select the **Logs** tab to view logs for that specific pod.

### Historical log search

When a **Log Source** (Loki, Elasticsearch or OpenSearch) is connected under **Settings → Integrations**, the cluster **Logs** page gains a **Search** tab for time-ranged queries across your log store. See [Log Sources](/integrations/log-sources) for setup and credential guidance.

With no log store of your own, turn on [Ankra hosted logs](/guides/hosted-logs) for the cluster: Ankra keeps its container logs for 7 days, and each application's log **History** in the new portal searches them.

***

## Log Viewer Features

### Workload Selection

In the Cluster Logs view, use the workload selector to choose which application's logs to view:

| Workload Type | Badge Color | Description |
| - | - | - |
| Deployment | Blue | Stateless applications |
| StatefulSet | Purple | Stateful applications |
| DaemonSet | Green | Node-level services |

### Pod Selection

When viewing a workload with multiple pods, you can:

* **View a single pod** - select one pod from the dropdown
* **View all pods** - select multiple pods to see combined logs
* **Identify log sources** - each log line shows which pod it came from

### Container Selection

For pods with multiple containers:

* Use the container dropdown to switch between containers
* Select multiple containers to view combined logs
* Init containers and sidecar containers are also available

***

## Streaming Controls

### Play/Pause

| Button | Description |
| - | - |
| Pause | Stop receiving new log lines (existing logs remain visible) |
| Play | Resume streaming new log lines |

### Auto-scroll

The log viewer automatically scrolls to show new logs as they arrive. When you scroll up to view older logs:

* Auto-scroll disables immediately and your scroll position is preserved
* New logs continue to arrive in the background without disturbing your view
* A **Scroll to bottom** button appears at the bottom of the viewer
* Click the button to jump to the latest logs and resume auto-scrolling
* Auto-scroll only re-engages when you explicitly click the button or resume streaming

### Load Older Logs

Scroll to the top of the log viewer to automatically load older logs. The viewer will:

1. Fetch the previous time window of logs
2. Prepend them to the current view
3. Maintain your scroll position

***

## Filtering & Search

### Text Search

Use the search box to filter logs:

* Type any text to filter log lines in real-time
* Only matching lines are displayed - both existing and newly arriving logs are filtered
* Match count is displayed
* Clearing the search restores all log lines

### Regex Search

Click the `.*` button to enable regex mode:

* Use regular expressions for advanced filtering
* Syntax errors are shown inline
* Common patterns: `error|warn`, `\d{3}`, `"status":\s*\d+`

### Log Level Filtering

Use the level filter buttons to show/hide logs by severity:

| Level | Color | Examples |
| - | - | - |
| Error | Red | ERROR, FATAL, CRITICAL |
| Warn | Yellow | WARN, WARNING |
| Info | Blue | INFO |
| Debug | Gray | DEBUG, TRACE |

***

## Display Settings

Click the **Settings** (gear icon) to customize the log viewer:

### Tail Lines

Choose how many recent log lines to fetch when connecting:

* 100 lines (default)
* 500 lines
* 1000 lines
* 5000 lines
* All available logs

### Font Size

Adjust the log text size:

* 10px to 20px
* Use the slider or +/- buttons

### Line Wrapping

Toggle line wrapping on/off:

* **On** - long lines wrap to multiple lines
* **Off** - long lines scroll horizontally

### Color Levels

Toggle syntax highlighting for log levels:

* **On** - Log levels are colour-coded
* **Off** - plain text display

### Timestamps

Toggle timestamp display:

* **On** - show Kubernetes timestamps at the start of each line
* **Off** - hide timestamps for cleaner output

***

## Fullscreen Mode

Click the **Fullscreen** button (expand icon) to enter fullscreen mode:

* Log viewer fills the entire screen
* All controls remain accessible
* Press `Escape` or click the button again to exit

***

## Downloading Logs

Click the **Download** button to save logs to a file:

* Logs are saved as a `.txt` file
* Filename includes pod name and timestamp
* All currently loaded logs are included

***

## Offline Clusters & Cached Data

Log streaming requires an active connection to your cluster through the Ankra agent.

### When the Cluster is Online

* Logs stream in real-time from the Kubernetes API
* New log lines appear as they are written
* You can load older logs by scrolling up

### When the Cluster Goes Offline

* **Existing logs remain visible** - logs already loaded in the viewer stay accessible
* **New logs cannot be fetched** - the stream pauses until connection is restored
* **A warning banner appears** - it says the cluster is offline and data may be stale

### Reconnection

When the cluster comes back online:

* The log stream automatically reconnects
* New logs resume streaming
* You may need to refresh to clear cached state

> [!WARNING]
>
> If you navigate away from the Logs page while the cluster is offline, you will not be able to view logs again until the connection is restored.

***

## Ask the AI about a failing pod

Open the AI Assistant with `⌘ J` / `Ctrl J` while you are on the pod or its logs and ask what is wrong. It can read the pod's logs, events and status itself. See [AI Assistant](/platform/ai-assistant).

***

## Performance Tips

For busy workloads:

### Reduce Initial Load

* **Use smaller tail lines** - start with 100-500 lines instead of "All" for busy workloads
* **Select specific containers** - avoid streaming all containers if you only need one

### Filter Aggressively

* **Apply log level filters** - hide DEBUG/INFO logs when investigating errors
* **Use search early** - filters apply in real-time to both existing and incoming logs, reducing visual noise immediately
* **Enable regex for precision** - narrow results with patterns like `error|exception|failed`

### Manage the Stream

* **Scroll up freely** - your position is preserved even during high-throughput streams; new logs accumulate in the background
* **Pause when needed** - pause streaming to stop new data from arriving entirely
* **Download for analysis** - export logs to a file for grep, analysis tools, or sharing
* **Clear when needed** - clear accumulated logs and start fresh if the buffer grows very large

### Multi-Pod Considerations

When viewing logs from multiple pods:

* Start with one pod, then add more as needed
* High-traffic pods can overwhelm the combined view
* Consider using log level filters to reduce cross-pod noise

***

## Common Tasks

### Debugging a Crashing Pod

1. Navigate to **Logs** in the sidebar
2. Select the workload containing the failing pod
3. Look for ERROR or FATAL messages
4. Scroll up to see logs from before the crash
5. Check previous container logs if the pod restarted

### Monitoring Multiple Replicas

1. Open **Logs** for your workload
2. Select all pods in the pod dropdown
3. Each log line shows which pod it came from
4. Use search to filter across all pods

### Finding Specific Errors

1. Enter your search term in the filter box
2. Enable regex mode for complex patterns
3. Use log level filters to show only errors
4. The match count helps you assess frequency

***

## Tips

> [!TIP]
>
> **Use the Command Palette:** Press `⌘+K` and type "logs" to quickly jump to the Logs page.

> [!TIP]
>
> **Pause for Investigation:** When debugging, pause the stream to prevent new logs from pushing important lines out of view.

> [!TIP]
>
> **Regex for JSON Logs:** Use patterns like `"error":\s*true` or `"status":\s*[45]\d\d` to find specific JSON log entries.

> [!TIP]
>
> **Download for Sharing:** Download logs before sharing with team members or attaching to issue reports.

***

## Keyboard Shortcuts

| Shortcut | Action |
| - | - |
| `⌘+K` → "logs" | Open Logs page |
| `Escape` | Exit fullscreen mode |

## Next step

To search logs older than the live stream, turn on [Ankra hosted logs](/guides/hosted-logs) or connect a [log source](/integrations/log-sources). For a shell inside the container, see [Pod Terminal](/platform/pod-terminal).


# MCP Server
Source: https://docs.ankra.ai/platform/mcp-server

Connect Cursor, Claude, and other MCP clients to Ankra with scoped access to platform tools.

Ankra exposes a remote [Model Context Protocol](https://modelcontextprotocol.io/) server at:

```text theme={null}
https://platform.ankra.app/api/v1/mcp
```

Use it to inspect clusters, workloads, logs, alerts, and related platform data from an MCP client. Write access can also apply changes through Ankra's agent tools, and lets your client work [AI board](/platform/ai-board) tickets alongside Ankra's own agents - see [Work the AI board with your own agent](/guides/board-own-agent).

## Choose an Access Scope

| Scope | Access |
| - | - |
| `mcp:read` | Read-only platform tools and Ankra's safe ask-mode tools, including temporary workspace operations and isolated pull request demos |
| `mcp:write` | The read surface plus mutating tools such as apply, scale, delete, and pull request creation |

`mcp:write` implies read access. When creating a write token in the portal, Ankra selects both scopes.

> [!WARNING]
>
> MCP clients own the confirmation experience. Ankra does not show a second server-side confirmation prompt before a write tool runs. Only grant `mcp:write` to clients you trust.

## Create an MCP Token

> [tab] Ankra Platform
>
> **1. Open API Tokens**
>
> Open your profile, select **API Tokens**, then select **Add Token**.
>
> **2. Choose MCP access**
>
> Enter a descriptive name and select **mcp:read**. Select **mcp:write** only if the client needs to change resources.
>
> **3. Copy the token**
>
> Copy the generated token immediately and store it securely. Ankra only shows it once.

> [tab] Ankra CLI
>
> Create a read-only token:
>
> ```bash theme={null}
> ankra tokens create cursor --scopes mcp:read
> ```
>
> Create a token with read and write access:
>
> ```bash theme={null}
> ankra tokens create cursor --scopes mcp:read,mcp:write
> ```

MCP-scoped tokens work only with the MCP endpoint and stay bound to the organisation selected when the token was created. They cannot call Ankra's REST API or override their organisation.

## Connect Cursor

Add Ankra to your Cursor MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "ankra": {
      "url": "https://platform.ankra.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <ankra-token>"
      }
    }
  }
}
```

Restart or refresh MCP servers in Cursor after saving the configuration. Ankra then appears as an available MCP server with tools filtered by the token's scopes.

> [!TIP]
>
> Keep personal tokens out of shared project configuration. Use a user-level MCP configuration or a local file that is excluded from version control.

## Connect Claude with OAuth

Claude connects to Ankra over OAuth, so you do not need to create or copy a token first. Where you add the connection depends on which Claude you use:

* **Claude web and desktop apps** - add Ankra as a custom connector in Settings.
* **Claude Code** (the terminal client) - add Ankra with the `claude mcp add` command.

> [tab] Claude web and desktop
>
> Custom connectors require a paid Claude plan. On Team and Enterprise plans an owner may need to add the connector for the organisation.
>
> **1. Open the Connectors settings**
>
> In Claude, select your profile icon in the bottom left corner, then **Settings**. In the settings sidebar, select **Connectors** under the **Customize** heading. You see a list of available connectors such as Slack and Gmail - Ankra is not in this list yet, which is why you add it as a custom connector.
>
> **2. Add a custom connector**
>
> Select the **Add** button in the top right of the Connectors page, then select **Add custom connector** from the menu.
>
> ![Claude Connectors settings with the Add menu open, showing Browse connectors and Add custom connector](https://mintcdn.com/ankra/-eNKDu16kjR2YgJe/images/mcp-claude-add-connector-menu.png?fit=max\&auto=format\&n=-eNKDu16kjR2YgJe\&q=85\&s=95633216e834947a2405549e5255db77)
>
> The Add menu in the top right of Claude's Connectors settings
>
> **3. Enter the Ankra server details**
>
> In the **Add custom connector** dialog, enter `Ankra` as the name and this URL in the **Remote MCP server URL** field:
>
> ```text theme={null}
> https://platform.ankra.app/api/v1/mcp
> ```
>
> Leave the **OAuth Client ID** and **OAuth Client Secret** fields under Advanced settings empty - Ankra does not need them. Then select **Add**.
>
> ![Claude Add custom connector dialog filled in with the name Ankra and the Ankra MCP server URL](https://mintcdn.com/ankra/-eNKDu16kjR2YgJe/images/mcp-claude-custom-connector-dialog.png?fit=max\&auto=format\&n=-eNKDu16kjR2YgJe\&q=85\&s=59009613da3e8b6b709b95ca9b78dc01)
>
> The completed Add custom connector dialog
>
> **4. Connect and sign in to Ankra**
>
> Ankra now appears in your connector list with a **Connect** button. Select it. Claude opens Ankra's OAuth consent page in a new window - sign in to Ankra if you are not signed in already, select the organisation the connection should use, review the requested `mcp:read` or `mcp:write` access, then approve the connection. Claude then shows Ankra as connected.
>
> **5. Enable Ankra in a chat**
>
> Open a new chat and select the tools menu (the sliders icon below the message box). Check that **Ankra** is listed and enabled. To verify the connection works end to end, ask Claude to list your Ankra clusters - it should call the `list_clusters` tool and return the clusters in your organisation.

> [tab] Claude Code
>
> **1. Add the server**
>
> Run this once from your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http ankra https://platform.ankra.app/api/v1/mcp
> ```
>
> This registers the server for your user in the current project. Add `--scope user` to make it available in every project.
>
> **2. Authenticate**
>
> Start Claude Code and run the `/mcp` command. It lists every configured MCP server with its connection status - **ankra** shows as needing authentication. Select it, then choose **Authenticate**. Your browser opens Ankra's OAuth consent page - sign in, select the organisation, review the requested access, then approve the connection and return to the terminal.
>
> **3. Verify the connection**
>
> Run `/mcp` again and confirm that **ankra** shows as connected. Then ask Claude Code to list your Ankra clusters - it should call the `list_clusters` tool and return the clusters in your organisation.
>
> If you prefer a long-lived token over OAuth, create an [MCP token](#create-an-mcp-token) and register the server with an authorisation header instead:
>
> ```bash theme={null}
> claude mcp add --transport http ankra https://platform.ankra.app/api/v1/mcp \
>   --header "Authorization: Bearer <your-token>"
> ```

By default, Ankra issues a seven-day MCP-only token to the client. The flow uses OAuth 2.1 authorization code with PKCE. No client secret or refresh token is issued, so when the grant expires, reconnect: select **Connect** on the Ankra connector in Claude's Connectors settings, or run `/mcp` and authenticate again in Claude Code.

## How Tool Access Works

The [MCP Tool Reference](/platform/mcp-tools) lists every available tool with the scope it requires and whether it needs a `cluster_id`.

* `tools/list` only returns tools allowed by the token.
* Cluster-scoped tools require a `cluster_id`. Call `list_clusters` to discover IDs.
* Ankra verifies that the cluster belongs to the token's organisation and [project](/concepts/projects) before dispatch. An MCP token minted while the organisation has projects is pinned to the project it was created in, and an older one is not pinned and does not follow switches (see [Tokens and projects](/concepts/projects#tokens-and-projects)); `list_projects` and `get_current_project` say where it acts.
* Draft-only chat tools are not available over MCP.
* Parameters containing literal secrets are refused before a mutating tool runs.
* Tool calls are rate limited per token: 120 read calls and 20 write calls per minute. Write calls also use a fail-closed platform write limit.
* Every resolved tool call, including refused calls, is written to the organisation audit log.

## How Calls Behave

MCP is stateless: each `tools/call` is one request with nothing parked between calls. Three consequences follow, and the server's `instructions` field repeats them to the model on `initialize`.

* **Every call has a 55-second deadline.** A call that outruns it answers `isError` with a timeout. A mutating call that had already started is not undone by that timeout, so read the target's state before repeating a write.
* **Writes that start platform work do not wait for it.** Tools such as `apply_stack_changes`, `upgrade_cluster` or `update_node_group` answer at once with an `operation_id` (or a `live_status_hint` naming the id to poll). Call `wait_for_execution` with that id to block for up to 50 seconds and receive the settled execution, or `timed_out: true` with the last observed step summary; call it again to keep waiting. `get_execution_details` reads the same document without waiting.
* **Confirmation cards do not exist over MCP.** A tool that raises a confirmation card in the Ankra chat executes directly here when the token holds `mcp:write`: the token scope is the approval. `apply_stack_changes` applies the stack draft the token last edited, so keep one client per token while editing a draft and pass `stack_name` on every apply.
* **A call can act under a Launch Plan approval.** Put the approval's id in the call's `_meta` as `"ankra/launch_plan_approval_id"`. The write then runs only if it is one of the actions you approved, the approval is yours, it has not expired or been revoked, and the plan has not changed since you approved it. Each approved action runs once. Any other call naming the approval is refused, and nothing runs.

## Links to the Portal

Everything the tools read and change is also visible in the Ankra portal, and the server's `instructions` ask the model to give you a portal link when it reports on a resource, finishes a change, or asks you to review or approve something in the UI.

* `list_clusters` and `get_cluster_details` return each cluster's `portal_url`.
* `get_portal_url` returns the link for any other page - a cluster's stacks, add-ons, operations or nodes, one pod or Deployment, an application, a pipeline run, a stack profile, an AI ticket, an alert, a CVE, credentials, tokens or settings. It is read-only, so an `mcp:read` token can call it.
* Links carry the organisation as `?org=` and the project as `?project=`, so one opened while another organisation or project is selected offers to switch.

[Portal URLs](/platform/portal-urls) lists every page and how its address is built, if you want to point your own agents or runbooks at them.

## Troubleshooting

### 401 Invalid or missing bearer token

The token is missing, expired, revoked, or copied incorrectly. Create a new MCP token and update the client. For Claude clients connected with OAuth this usually means the seven-day grant expired - reconnect the Ankra connector in Claude's settings, or run `/mcp` and authenticate again in Claude Code.

### 403 Token has no MCP scope

The token is REST-only. Recreate it with `mcp:read` or `mcp:read,mcp:write`.

### Claude reports "Couldn't register with Ankra's sign-in service"

Claude could not reach Ankra's OAuth discovery endpoints, so it could not register itself as an OAuth client. This is a platform-side routing problem, not a mistake in your connector configuration - the server URL field only accepts the MCP endpoint, and no OAuth Client ID is needed. Ask your Ankra administrator to confirm that `/oauth/` and the `/.well-known/oauth-*` discovery paths on the platform host route to the API service, then select **Connect** on the Ankra connector again.

### 403 Origin not allowed

A browser-based client is calling from an origin that Ankra does not allow. Contact your Ankra administrator to review the configured origins.

### A tool reports that it needs mcp:write

The requested tool changes state and is outside the read surface. Use a write-scoped token only if the client should make that change.

### A tool reports a rate limit

Wait one minute and retry. If normal usage regularly reaches the limit, ask your Ankra administrator to review the MCP rate limits.

## Related

* [API Tokens](/reference/tokens)
* [Work the AI board with your own agent](/guides/board-own-agent)
* [Portal URLs](/platform/portal-urls)
* [AI Provider](/platform/ai-provider)
* [Hermes Integration](/integrations/hermes)


# MCP Tool Reference
Source: https://docs.ankra.ai/platform/mcp-tools

Every tool the Ankra MCP server exposes, with the scope each one requires and whether it targets a specific cluster.

This page lists the full tool surface of the Ankra MCP server - 450+ tools across clusters, Kubernetes, Stacks, add-ons, applications, variables, credentials, GitOps, observability, notification routing, the Security Center, backups, provisioning, cluster lifecycle, managed Kubernetes, CI/CD, collaboration, support tickets, cost, managed services, cluster mesh, DNS, object storage, and playgrounds. Some families appear only while the organisation has the matching feature enabled. The same tool registry powers the AI Assistant in the product and chat over Slack, Microsoft Teams, and SCM comments, so what you can ask Ankra to do is the same everywhere. For connecting a client and creating tokens, see [MCP Server](/platform/mcp-server).

Two scopes gate access:

* **`mcp:read`** reaches every read-only tool and nothing else, so a read token changes nothing.
* **`mcp:write`** adds the mutating tools - everything marked `mcp:write` below, including the ephemeral workspace operations and throwaway pull request demos. The in-product Ask mode allows those as safe creations, but over MCP they need `mcp:write`. Write access implies the read surface.

**Cluster-scoped** tools require a `cluster_id` argument (a UUID); call `list_clusters` first to discover IDs. Ankra verifies the cluster belongs to the token's organisation before dispatch. Tools marked **No** do not require `cluster_id`. Many of them still act on one cluster, and take an optional `cluster_id` or `cluster_name` selector that falls back to the cluster selected for the session (for example `get_node_usage` and `roll_cluster_to_version`). The rest operate at the organisation level.

**Portal links:** `list_clusters` and `get_cluster_details` return each cluster's `portal_url`, and `get_portal_url` builds the portal link for any other page, so a client can hand you a clickable link to what it is describing. See [Portal URLs](/platform/portal-urls).

> [!WARNING]
>
> Creating a credential is deliberately **not** available over MCP or chat. Creating one would mean passing the secret itself as a tool argument, and Ankra refuses mutating tool calls whose parameters contain literal secrets. Create credentials in the portal or [CLI](/reference/cli/credentials); over MCP you can list and inspect credentials (secret fields are always redacted), validate names, delete unused credentials, and plan or apply a GitHub credential rotation.

## Clusters & Kubernetes

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_clusters` | `mcp:read` | No | List every cluster in the organisation with state, environment, Kubernetes version, and its `portal_url` |
| `get_cluster_details` | `mcp:read` | No | Detailed information about one cluster by name or ID, with its `portal_url` |
| `get_cluster_attention_summary` | `mcp:read` | No | The exact signals behind a cluster's Needs Attention badge |
| `get_cluster_status` | `mcp:read` | Yes | Cluster health overview |
| `get_cluster_snapshot` | `mcp:read` | Yes | Full cluster overview in a single call |
| `get_cluster_cost` | `mcp:read` | Yes | Estimated cloud infrastructure cost for the cluster |
| `get_stack_cost` | `mcp:read` | Yes | Estimated cost attributed to one Stack, derived from its namespaces |
| `get_security_reports` | `mcp:read` | Yes | Trivy Operator image-vulnerability summary |
| `get_compliance_reports` | `mcp:read` | Yes | Trivy benchmark checks, remediation, passed controls, and configuration-audit summary |
| `get_cluster_bastion` | `mcp:read` | Yes | Public IP of the Ankra-managed bastion/gateway host |
| `list_namespaces` | `mcp:read` | Yes | List namespaces with their status |
| `get_resource_quotas` | `mcp:read` | Yes | Resource quotas and current usage per namespace |
| `list_recent_executions` | `mcp:read` | Yes | Recent platform executions (deployments, write operations) |
| `get_execution_details` | `mcp:read` | Yes | Full details for one execution, including steps and error excerpts |
| `wait_for_execution` | `mcp:read` | Yes | Block up to 50 seconds for an execution to settle, then return its details, or `timed_out: true` with the last observed state |
| `cluster_query` | `mcp:read` | Yes | Structured lookup against the live cluster resource index |
| `cluster_search` | `mcp:read` | Yes | Full-text search over the live cluster resource index |
| `cluster_describe` | `mcp:read` | Yes | Full body of one named resource from the live cluster index |
| `get_pods` | `mcp:read` | Yes | Pod status, restarts, and placement, with namespace/name/label filters |
| `get_pod_logs` | `mcp:read` | Yes | Logs from a specific pod |
| `get_deployments` | `mcp:read` | Yes | Deployment information |
| `get_statefulsets` | `mcp:read` | Yes | StatefulSet information |
| `get_daemonsets` | `mcp:read` | Yes | DaemonSet information |
| `get_services` | `mcp:read` | Yes | Service information |
| `get_ingresses` | `mcp:read` | Yes | Ingress information |
| `get_events` | `mcp:read` | Yes | Kubernetes events (Normal/Warning) |
| `get_nodes` | `mcp:read` | Yes | Node information |
| `get_configmaps` | `mcp:read` | Yes | ConfigMap information |
| `get_secrets` | `mcp:read` | Yes | Secret metadata (never secret values) |
| `get_jobs` | `mcp:read` | Yes | Job information |
| `get_cronjobs` | `mcp:read` | Yes | CronJob information |
| `get_pvcs` | `mcp:read` | Yes | PersistentVolumeClaim information |
| `get_cluster_role_bindings` | `mcp:read` | Yes | ClusterRoleBindings and RoleBindings for RBAC analysis |
| `describe_resource` | `mcp:read` | Yes | Detailed YAML/JSON for one Kubernetes resource |
| `describe_resources` | `mcp:read` | Yes | Batch-fetch multiple Kubernetes resources in one call |
| `restart_deployment` | `mcp:write` | Yes | Rolling restart of a deployment |
| `scale_deployment` | `mcp:write` | Yes | Scale a deployment to a replica count |
| `scale_statefulset` | `mcp:write` | Yes | Scale a StatefulSet to a replica count |
| `delete_pod` | `mcp:write` | Yes | Delete a specific pod |
| `delete_resource` | `mcp:write` | Yes | Delete any Kubernetes resource, including custom resources |
| `apply_manifest` | `mcp:write` | Yes | Apply a Kubernetes manifest to create or update resources |
| `patch_resource` | `mcp:write` | Yes | Patch a Kubernetes resource (strategic merge or JSON patch) |
| `create_storage_class` | `mcp:write` | Yes | Create a StorageClass for a CSI driver installed on the cluster; never edits an existing class and never makes the new one the default (kubernetes.write) |
| `delete_storage_class` | `mcp:write` | Yes | Delete a StorageClass no claim or volume uses; the default class is refused, and volumes already provisioned from it are not touched (kubernetes.write) |
| `delete_persistent_volumes` | `mcp:write` | Yes | Delete up to 20 Released or Available PersistentVolumes no claim is bound to, snapshotting each CSI volume first where the cluster can; a volume that cannot be snapshotted loses its data for good (kubernetes.write) |
| `add_helm_registry` | `mcp:write` | No | Add a Helm chart registry to the organisation's catalog |
| `cancel_execution_step` | `mcp:write` | No | Cancel one step of a running execution while the rest continues |
| `cancel_execution` | `mcp:write` | No | Cancel a running platform execution; a mid-flight cancellation can leave the resource between versions until the next reconcile |
| `retry_execution` | `mcp:write` | No | Retry a terminal (failed, cancelled, timeout) execution from the start with its original payload |
| `reconcile_cluster` | `mcp:write` | No | Re-render every stack member against the committed definitions and variables and re-apply drift (takes a `cluster_id` argument) |
| `get_node_usage` | `mcp:read` | No | Live CPU and memory per node from metrics-server, with allocatable capacity and percentages (never a cached answer) |
| `get_pod_usage` | `mcp:read` | No | Live CPU and memory per pod from metrics-server, optionally per container, filtered by namespace |
| `get_cluster_agent_status` | `mcp:read` | No | The Ankra agent's online state, version against the latest release, upgrade posture and last check-in |
| `upgrade_cluster_agent` | `mcp:write` | No | Upgrade the agent to the latest release now instead of waiting for the fleet rollout (agents.manage) |
| `list_helm_releases` | `mcp:read` | No | Every Helm release installed on the cluster, Ankra-managed or not, for drift detection |
| `get_cluster_dns_zone` | `mcp:read` | No | The cluster's generated DNS zone and the public domain hostnames publish under |
| `get_sops_config` | `mcp:read` | No | Whether SOPS is enabled and the AGE public key secrets are encrypted with |
| `resize_bastion` | `mcp:write` | No | Resize the bastion of an Ankra-provisioned cluster (clusters.write) |
| `resync_cluster_ssh_keys` | `mcp:write` | No | Re-register the cluster's SSH key with its provider (clusters.write) |
| `cordon_node` | `mcp:write` | Yes | Mark one node unschedulable so no new pods land on it, while running pods keep running |
| `uncordon_node` | `mcp:write` | Yes | Make a cordoned node schedulable again, the reversal of `cordon_node` |

## Stacks

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_stacks` | `mcp:read` | Yes | List the cluster's Stacks with their add-ons, manifests, and state |
| `get_stack_details` | `mcp:read` | Yes | One Stack in full, including add-on and manifest configuration |
| `get_stack_history` | `mcp:read` | Yes | Version history: who changed what and when, per resource |
| `get_stack_deployments` | `mcp:read` | Yes | Deployment status grouped per resource, with failure detail |
| `export_cluster_iac` | `mcp:read` | Yes | Export the cluster's Stacks as an Infrastructure-as-Code YAML document |
| `validate_stack` | `mcp:read` | Yes | Validate a Stack specification without applying it |
| `list_available_charts` | `mcp:read` | No | Browse the Helm chart catalog with search and category filters |
| `create_stack` | `mcp:write` | Yes | Create a new Stack on the cluster |
| `update_stack` | `mcp:write` | Yes | Update a Stack's add-ons, manifests, or configuration |
| `rename_stack` | `mcp:write` | Yes | Rename a Stack |
| `redeploy_stack` | `mcp:write` | Yes | Re-deploy a Stack to reconcile it onto the cluster |
| `clone_stack` | `mcp:write` | Yes | Clone a Stack within or across clusters |
| `addon_install` | `mcp:write` | Yes | Install a chart from the catalog into a Stack |
| `delete_stack` | `mcp:write` | Yes | Delete an entire Stack and everything it deployed |
| `uninstall_addon_from_stack` | `mcp:write` | Yes | Uninstall one add-on from a deployed Stack |
| `disconnect_manifest_from_stack` | `mcp:write` | Yes | Remove a manifest from a deployed Stack |
| `list_stack_profiles` | `mcp:read` | No | List reusable stack profiles, including public ones |
| `get_stack_profile` | `mcp:read` | No | A stack profile's metadata, version history, and contents |
| `create_stack_profile` | `mcp:write` | Yes | Save a deployed Stack as a new reusable stack profile |
| `save_stack_profile_version` | `mcp:write` | Yes | Snapshot a deployed Stack as a new version of an existing profile |
| `update_stack_profile` | `mcp:write` | Yes | Update a stack profile's metadata |
| `delete_stack_profile` | `mcp:write` | Yes | Delete a stack profile and all its versions |
| `instantiate_stack_profile` | `mcp:write` | Yes | Instantiate a stack profile onto the cluster |
| `validate_cluster_manifest` | `mcp:read` | No | Validate an ImportCluster YAML the way `ankra cluster validate` and the API do, without changing anything |
| `apply_cluster_manifest` | `mcp:write` | Yes | Apply an ImportCluster YAML declaratively: the cluster's definition is replaced by the manifest (stacks.write) |
| `stage_cluster_manifest_drafts` | `mcp:write` | Yes | Stage every stack in an ImportCluster YAML as a draft for a person to promote |
| `roll_cluster_to_version` | `mcp:write` | No | Roll the whole cluster definition back to an earlier resource version (clusters.operate) |
| `export_stack_profile_iac` | `mcp:read` | No | Export a published profile version as ClusterInfrastructureAsCode YAML |
| `import_stack_profile` | `mcp:write` | No | Create a stack profile from a ClusterInfrastructureAsCode YAML document, publishing its first version, or open it as a builder draft for human review with `as_draft` |
| `apply_stack_changes` | `mcp:write` | Yes | Apply the current stack draft to the cluster, preserving items absent from the draft unless `replace_missing` is set |
| `get_stack_profile_draft` | `mcp:read` | No | Read a stack profile builder draft with its contents, parameters and publish validation verdict |
| `create_stack_profile_draft` | `mcp:write` | No | Start a stack profile builder draft for a new profile, or for a new version of an existing one, without a cluster |
| `add_addon_to_stack_profile_draft` | `mcp:write` | No | Add a Helm chart add-on to a stack profile builder draft, with `ANKRA_SECRET_PARAMETER` standing in for any secret value |
| `update_addon_in_stack_profile_draft` | `mcp:write` | No | Change an add-on's Helm values, chart version, namespace or parents inside a stack profile builder draft |
| `remove_addon_from_stack_profile_draft` | `mcp:write` | No | Remove an add-on from a stack profile builder draft and clean up references to it |
| `add_manifest_to_stack_profile_draft` | `mcp:write` | No | Add a raw Kubernetes manifest to a stack profile builder draft, with real secret values rejected |
| `remove_manifest_from_stack_profile_draft` | `mcp:write` | No | Remove a manifest from a stack profile builder draft and clean up references to it |
| `publish_stack_profile_draft` | `mcp:write` | No | Validate a stack profile builder draft and publish it as a new profile or the next version of an existing one |

## Add-ons

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_addons` | `mcp:read` | Yes | List installed add-ons with sync status, health, and version |
| `get_addon_details` | `mcp:read` | Yes | One add-on in detail, including its resource tree |
| `get_addon_status` | `mcp:read` | Yes | Status of the add-ons Ankra manages on the cluster |
| `get_addon_history` | `mcp:read` | Yes | Deployment history: previous versions and sync operations |
| `get_addon_settings` | `mcp:read` | Yes | An add-on's settings (chart version, namespace, sync options) |
| `get_addon_configuration` | `mcp:read` | Yes | An add-on's Helm values, with secret values redacted |
| `sync_addon` | `mcp:write` | Yes | Trigger a sync to apply pending changes from the source repository |
| `rollback_addon` | `mcp:write` | Yes | Roll an add-on back to a previous deployment version |
| `update_addon_settings` | `mcp:write` | Yes | Update an add-on's settings |
| `update_addon_configuration` | `mcp:write` | Yes | Update an add-on's Helm values |
| `list_helm_registries` | `mcp:read` | No | The organisation's connected Helm registries with sync state (credentials never returned) |
| `get_helm_registry` | `mcp:read` | No | One registry with a page of the charts it holds |
| `list_helm_registry_sync_jobs` | `mcp:read` | No | A registry's sync jobs, to see whether a missing chart simply has not synced |
| `list_helm_registry_credentials` | `mcp:read` | No | Stored registry credentials by name and id only |
| `sync_helm_registry` | `mcp:write` | No | Re-read a registry's index now (helm.manage) |
| `get_chart_default_values` | `mcp:read` | No | A chart version's default values.yaml |
| `render_chart_template` | `mcp:read` | No | Render a chart version's manifests server-side like `helm template`, with optional values |
| `get_chart_details` | `mcp:read` | No | Detailed chart information at a repository URL: maintainers, versions, app versions |
| `get_addon_security_updates` | `mcp:read` | Yes | Installed add-ons whose running version is covered by an upstream security advisory with a fix, and the chart version to upgrade to |
| `list_chart_versions` | `mcp:read` | Yes | Every catalog version of one Helm chart, newest first, with the registries that carry it |

## Applications

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_applications` | `mcp:read` | No | List the organisation's applications with state and analysis status |
| `get_application` | `mcp:read` | No | One application's repository, artifacts, pull request, and lifecycle state |
| `get_application_jobs` | `mcp:read` | No | The platform jobs behind an application's analysis and generation |
| `get_application_deployments` | `mcp:read` | No | Where an application is deployed and its readiness |
| `list_application_installations` | `mcp:read` | No | List the installations of an application across clusters |
| `list_application_workflow_runs` | `mcp:read` | No | CI workflow runs for an application's repository |
| `get_application_workflow_run_jobs` | `mcp:read` | No | Jobs and step detail for one application workflow run |
| `create_application` | `mcp:write` | No | Connect a repository as a new application and start analysis |
| `deploy_application` | `mcp:write` | No | Deploy an application onto a cluster as part of a Stack |
| `retry_application` | `mcp:write` | No | Re-run analysis and generation after a failure |
| `reconcile_application` | `mcp:write` | No | Re-evaluate an application against its repository and refresh its state |
| `rerun_application_workflow` | `mcp:write` | No | Re-run a CI workflow run for an application |
| `delete_application` | `mcp:write` | No | Disconnect an application from Ankra |
| `get_application_setup_proposal` | `mcp:read` | No | The generated setup: detected stack, setup PR, database, and the deploy contract with its negotiable options |
| `revise_application_setup` | `mcp:write` | No | Change a recorded deploy-contract default; commits the revised contract to the setup branch |
| `get_application_publish_readiness` | `mcp:read` | No | Whether the repository can publish images - registry, Actions secrets, publish step, and an actually-pushed image |
| `list_application_env_secrets` | `mcp:read` | No | Stored environment-secret keys (values are never returned) |
| `set_application_env_secret` | `mcp:write` | No | Store one environment-secret value (API-token only - chat surfaces never carry secret values) |
| `delete_application_env_secret` | `mcp:write` | No | Remove one stored environment-secret key |
| `apply_application_env_secrets` | `mcp:write` | No | Seal the stored secrets into every deployment and roll the workloads |
| `get_application_auto_deploy` | `mcp:read` | No | Whether push-to-deploy is enabled and the build watermark it converges from |
| `set_application_auto_deploy` | `mcp:write` | No | Turn push-to-deploy on or off (enabling stamps the current build; a manual rollback is never fought) |
| `get_application_container_security` | `mcp:read` | No | Image CVEs from the pipeline's scans plus Dependabot and OSV |
| `get_application_code_security` | `mcp:read` | No | SAST and IaC findings from the pipeline's scan artifacts |
| `get_preview_domain` | `mcp:read` | No | The DNS zones and hostname suffix a cluster may publish on - always consult before proposing a public hostname |
| `get_application_timeline` | `mcp:read` | No | An application's recorded history newest first, from creation through builds, deploys, demos and AI reviews |
| `promote_application` | `mcp:write` | No | Move exactly the image tag one environment runs onto the next environment through the ordinary deploy, never a rebuild |
| `park_application_deployment` | `mcp:write` | No | Scale one deployment of an application to zero on purpose, remembering its replica count so it can be woken |
| `wake_application_deployment` | `mcp:write` | No | Restore a parked deployment to its remembered replica count |
| `get_application_ai_config` | `mcp:read` | No | How Ankra AI is configured for an application's repository per lane, including the pull request review budget |
| `update_application_ai_config` | `mcp:write` | No | Change how Ankra AI runs on an application's repository, such as enabling a lane, its model, scope or review budget |
| `list_application_pull_request_reviews` | `mcp:read` | No | The AI reviews Ankra has posted on an application's pull requests, newest first, with their findings |

## Credentials

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_credentials` | `mcp:read` | No | List every credential across all providers, with availability and sync state; a GitHub App credential also reports its `installation_id` |
| `get_credential` | `mcp:read` | No | One credential's identity, availability, and dependents - secret fields are always redacted |
| `validate_credential_name` | `mcp:read` | No | Check whether a credential name is valid and free to use |
| `get_github_credential_usages` | `mcp:read` | No | Everything that depends on a GitHub credential |
| `verify_github_credential` | `mcp:read` | No | Probe a GitHub App credential's installation and report each check |
| `get_github_credential_activity` | `mcp:read` | No | Recent GitHub App installation activity events for a credential |
| `plan_github_credential_replacement` | `mcp:read` | No | Build the plan for rotating a deprecated GitHub OAuth credential to a GitHub App credential |
| `list_provider_credentials` | `mcp:read` | No | List cloud provider and SSH key credentials |
| `list_gitops_credentials` | `mcp:read` | No | List GitHub credentials available for GitOps |
| `list_gitops_repositories` | `mcp:read` | No | List repositories reachable under a GitHub credential |
| `delete_credential` | `mcp:write` | No | Delete a credential that is not in use |
| `replace_github_credential` | `mcp:write` | No | Apply a planned GitHub credential rotation (organisation admins only) |

## Variables

Variables are the plain-text configuration values stack definitions interpolate with `${{ ankra.variables.* }}` - never secrets (the platform refuses secret-looking values; secrets travel SOPS-encrypted).

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_organisation_variables` | `mcp:read` | No | The organisation-wide variables every cluster inherits |
| `list_cluster_variables` | `mcp:read` | Yes | One cluster's variables, overriding same-named organisation variables |
| `set_organisation_variable` | `mcp:write` | No | Create or update (upsert) an organisation variable |
| `delete_organisation_variable` | `mcp:write` | No | Delete an organisation variable |
| `set_cluster_variable` | `mcp:write` | Yes | Create or update (upsert) a variable on one cluster |
| `delete_cluster_variable` | `mcp:write` | Yes | Delete a variable from one cluster |

## GitOps

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_gitops_conflicts` | `mcp:read` | No | Open GitOps merge conflicts: resources changed in both Git and the cluster |
| `get_gitops_conflict_diff` | `mcp:read` | No | The Git, cluster, and base sides of one conflict, with secrets redacted |
| `resolve_gitops_conflict` | `mcp:write` | No | Resolve one GitOps merge conflict by picking the winning side |
| `get_gitops_status` | `mcp:read` | No | The cluster's sync state: repository, branch, credential, last and pending commits, plus `credential_missing` and `source_mismatch` |
| `connect_gitops_repository` | `mcp:write` | No | Connect a GitOps repository and branch to a cluster that has none, using an existing GitHub credential |

## Source Control & Workspaces

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `github_list_repositories` | `mcp:read` | No | List GitHub repositories the connected account can reach |
| `github_list_repository_files` | `mcp:read` | No | List files and directories in a repository |
| `github_read_file` | `mcp:read` | No | Read one file from a repository |
| `github_list_workflow_runs` | `mcp:read` | No | Recent GitHub Actions workflow runs for a repository |
| `github_get_workflow_run_jobs` | `mcp:read` | No | Jobs and step-level detail for one workflow run |
| `github_get_job_logs` | `mcp:read` | No | Log output for one GitHub Actions job |
| `github_list_artifacts` | `mcp:read` | No | GitHub Actions artifacts for a repository |
| `github_download_artifact` | `mcp:read` | No | Download and read the contents of an artifact |
| `github_commit_files` | `mcp:write` | No | Commit one or more files to a repository |
| `github_create_pull_request` | `mcp:write` | No | Create a pull request with file changes |
| `scm_create_pull_request` | `mcp:write` | No | Open a pull request on a GitHub repository - the pull request itself is the review gate |
| `list_related_repositories` | `mcp:read` | No | The repositories stated as related for AI code review under one GitHub App installation |
| `relate_repositories` | `mcp:write` | No | State that two repositories are related, so a code review of either may read the other (organisation admin) |
| `unrelate_repositories` | `mcp:write` | No | Remove a stated relationship, in whichever order it was stated (organisation admin) |
| `workspace_search_code` | `mcp:write` | No | Search an application's source repository from an ephemeral, locked-down workspace |
| `workspace_read_file` | `mcp:write` | No | Read one file from an application's source repository via an ephemeral workspace |
| `workspace_list_files` | `mcp:write` | No | List an application repository's files via an ephemeral workspace |
| `deploy_pr_demo` | `mcp:write` | No | Deploy a throwaway, time-limited demo of a pull-request build into an isolated namespace; returns a public `preview_url` when a demo domain or active cluster DNS zone is configured |
| `demo_stop` | `mcp:write` | No | Tear down a pull-request demo |
| `get_demo_diagnostics` | `mcp:read` | No | Read a demo's tracked record plus a log tail of its container's most recent start attempt - the crash evidence behind a failed demo |
| `redeploy_demo` | `mcp:write` | No | Redeploy an existing PR or branch demo with its recorded identity so the application's saved demo configuration applies |
| `get_application_demo_config` | `mcp:read` | No | Read an application's saved demo environment defaults and throwaway-database flag |
| `update_application_demo_config` | `mcp:write` | No | Replace an application's saved demo configuration (the pre-setup every future demo inherits); affects only TTL-reaped demo namespaces |
| `github_search_code` | `mcp:read` | No | Search file contents on a repository's default branch with GitHub code search |
| `watch_workflow_run` | `mcp:read` | No | Register a watch on the CI run a commit triggered, so the conversation is woken with its conclusion |
| `scm_merge_pull_request` | `mcp:write` | No | Ask Ankra to merge a pull request automatically once its pipeline, gates and reviews are green |
| `list_application_demos` | `mcp:read` | No | An application's active PR and branch demos with status, preview URL and expiry |
| `inspect_demo` | `mcp:read` | No | Diagnose a demo or preview that does not load, reading its record and the live state that decides whether it is reachable |

## Observability & Alerts

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_alerts` | `mcp:read` | No | The organisation's alert definitions, firing state, and alert metrics |
| `create_alert` | `mcp:write` | No | Create an alert definition with rules in the evaluator's vocabulary (cluster state, GitOps sync, metric thresholds, metrics stopped flowing, security findings, resource state, job status); a rule naming no clusters targets the bound cluster |
| `set_alert_enabled` | `mcp:write` | No | Enable or mute one alert; muting keeps the firing history and settles its open incidents |
| `delete_alert` | `mcp:write` | No | Permanently delete an alert definition, its rules and its firing history |
| `query_prometheus` | `mcp:read` | Yes | PromQL instant query against the cluster's Prometheus |
| `query_prometheus_range` | `mcp:read` | Yes | PromQL range query over a time window |
| `list_alert_destinations` | `mcp:read` | No | The Slack / Teams / Discord / PagerDuty / webhook endpoints notifications deliver to (webhook URLs redacted to their host) |
| `list_notification_routes` | `mcp:read` | No | The rules that filter notifications by kind, severity, cluster and source onto destinations |
| `preview_notification_routing` | `mcp:read` | No | Dry-run a hypothetical notification through the organisation's routing and report every delivery, suppression and reason |
| `create_notification_route` | `mcp:write` | No | Route matching notifications to an existing destination |
| `update_notification_route` | `mcp:write` | No | Change one route's filters, destination, priority, mode or enabled state |
| `delete_notification_route` | `mcp:write` | No | Delete a route; what gets delivered or suppressed changes immediately |
| `test_notification_route` | `mcp:write` | No | Queue a sample notification through a route's destination (alerts.write) |
| `query_logs` | `mcp:read` | Yes | Search the cluster's registered log store (Loki, Elasticsearch, OpenSearch or VictoriaLogs) over a time window |
| `get_log_labels` | `mcp:read` | Yes | The labels or fields the cluster's log store can be filtered on, to use before or after a `query_logs` that returns nothing |
| `connect_log_source` | `mcp:write` | Yes | Connect the log source Ankra derived from the cluster's installed add-ons, exactly as a `query_logs` refusal named it |
| `connect_metrics_source` | `mcp:write` | Yes | Connect the Prometheus-compatible metrics source Ankra derived from the cluster's installed add-ons, exactly as a `query_prometheus` refusal named it |
| `get_cluster_hosted_log_shipping` | `mcp:read` | No | Whether a cluster ships its container logs to Ankra's hosted log store, and whether its agent supports the switch |
| `set_cluster_hosted_log_shipping` | `mcp:write` | No | Turn shipping of a cluster's container logs to Ankra's hosted log store on or off |
| `list_alertmanager_silences` | `mcp:read` | Yes | The silences configured in the cluster's Prometheus Alertmanager, with matchers, time window and state |
| `create_alertmanager_silence` | `mcp:write` | Yes | Create a silence in the cluster's Prometheus Alertmanager so matching alerts stop notifying until it ends |
| `expire_alertmanager_silence` | `mcp:write` | Yes | End an Alertmanager silence by id so matching alerts notify again |
| `get_cluster_insights` | `mcp:read` | Yes | The platform's own AI health diagnoses for the cluster, with root cause, recommended actions and what was tried before |
| `get_execution_trends` | `mcp:read` | Yes | Platform execution history for the cluster over a time window, with failure rate and the most-failing executions |
| `list_systemic_patterns` | `mcp:read` | Yes | Issues that have recurred and been remediated repeatedly, grouped by who can fix them at the source |
| `resource_timeline` | `mcp:read` | Yes | The state-transition history of one Kubernetes resource over a time window, such as restarts, scaling and spec changes |
| `probe_endpoint` | `mcp:read` | No | Probe a public HTTP or HTTPS endpoint and report its status, latency, headers, a body snippet and TLS certificate |
| `trace_request_path` | `mcp:read` | No | Trace a URL end to end through DNS, ingress and backends and name the first broken hop with evidence |

## Security Center

The organisation-wide CVE surface with CISA KEV and EPSS exploitation intelligence, the bill of materials behind it, the disposition and compliance decisions on top of it, and the cluster, stack, pod and add-on drill-downs; `get_security_reports` / `get_compliance_reports` above stay the per-cluster Trivy summaries. Every read needs `security.read`; the writes re-check `security.triage` or `security.manage` the way the portal does, and each is confirmed before it runs. Tools that name a `cluster_id` take it as an argument, so an MCP client can read any cluster of the organisation without binding one.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `get_security_overview` | `mcp:read` | No | Fleet security summary: totals by severity, fixable counts, CISA KEV exposure, scanner coverage and top remediation candidates |
| `list_security_findings` | `mcp:read` | No | Findings across every scanned cluster, exploited-in-the-wild first, with rich filters |
| `get_security_finding` | `mcp:read` | No | One finding with its exploitation intelligence and every current occurrence |
| `list_security_finding_occurrences` | `mcp:read` | No | Where one finding occurs: every cluster, workload, container and image, one row per occurrence, filtered by scan state (active or resolved) and cluster |
| `get_security_advisory` | `mcp:read` | No | The platform's advisory for any CVE id: parsed NVD/OSV record, CISA guidance and your fleet exposure |
| `list_security_cluster_posture` | `mcp:read` | No | Per-cluster finding counts, known-exploited exposure and scanner freshness |
| `list_security_workloads` | `mcp:read` | No | Workloads carrying findings, one row per container image with cluster, namespace, add-on attribution and actionable counts, with the findings filters |
| `list_security_namespaces` | `mcp:read` | No | Namespaces of the fleet or of one cluster with scanned workloads, images, running pods, SBOM coverage and actionable findings |
| `list_security_pods` | `mcp:read` | No | The running pods of one namespace on one cluster, each container joined to the findings of its scanned workload (an unscanned container is not a clean one) |
| `list_cluster_security_stacks` | `mcp:read` | No | Every stack of one cluster with its attribution status, scope, actionable and known-exploited findings and SBOM coverage, plus the outside-any-stack row |
| `get_cluster_stack_security` | `mcp:read` | No | One stack's posture on a cluster: status, scope, CVE posture across its workloads, exploited findings, top actionable findings and bill-of-materials picture |
| `get_cluster_pod_security` | `mcp:read` | No | One pod container by container: image, scanner coverage, actionable CVEs by severity, known-exploited and fixable-severe counts, bill of materials |
| `get_cluster_addon_security` | `mcp:read` | No | One add-on's posture on one cluster: attributed workloads and images, observed and actionable findings, dispositions in force, scanner state |
| `list_security_sbom_components` | `mcp:read` | No | The fleet's packages grouped by name, version and ecosystem with licences, licence risk tier, where each runs and the findings that name it |
| `list_security_sbom_images` | `mcp:read` | No | Images that publish a bill of materials, with base OS, component count, where they run and their attributed findings |
| `get_security_sbom_image` | `mcp:read` | No | One image's full bill of materials: identity, base OS, the containers running it and every component with licences |
| `list_security_sbom_containers` | `mcp:read` | No | Every running container, init containers included, joined to its image's bill of materials or marked absent |
| `list_security_sbom_image_findings` | `mcp:read` | No | The CVEs named on one image: package and fixed version, KEV listing, EPSS, disposition and spread |
| `get_application_security_versions` | `mcp:read` | No | Every pushed image version of an application with its bill of materials, findings, licence exposure and where it runs |
| `list_security_dispositions` | `mcp:read` | No | The organisation's disposition policies: selector, disposition, reason, expiry, expire-when-fixed and lifecycle status |
| `preview_security_disposition` | `mcp:read` | No | What a disposition would cover before it is written: the selector, the occurrences it matches across clusters and workloads, and the observations it excludes |
| `create_security_disposition` | `mcp:write` | No | Acknowledge a finding (security.triage) or accept its risk (security.manage), scoped to the add-on the occurrence is attributed to, with reason and review deadline |
| `update_security_disposition` | `mcp:write` | No | Change a policy's reason, review deadline or expire-when-fixed flag (security.manage) |
| `revoke_security_disposition` | `mcp:write` | No | Withdraw a policy with a reason so every finding it covered returns to open (security.manage) |
| `get_security_compliance_overview` | `mcp:read` | No | The compliance rollup across every scanned cluster: benchmark pass/fail counts, config-audit totals, scanner freshness and the clusters with no data |
| `list_security_compliance_frameworks` | `mcp:read` | No | The curated frameworks (GDPR, ISO 27001, SOC 2, NIST CSF), whether each is enabled and its live score |
| `get_security_compliance_framework_report` | `mcp:read` | No | One framework control by control, live or for a recorded month |
| `set_security_compliance_framework` | `mcp:write` | No | Enable or disable a framework for the organisation (security.manage); enabling starts scoring and monthly recording |
| `get_cluster_policy_violations` | `mcp:read` | No | One cluster's pod-security policy violations read live: failing resources per policy, totals by severity, and whether the baseline is in audit or enforce |
| `set_cluster_security_policy_mode` | `mcp:write` | No | Switch a cluster's pod-security policies between audit and enforce; enforce can reject pods at admission |
| `get_cluster_network_policy_overprivilege` | `mcp:read` | No | One cluster's NetworkPolicy over-privilege score on ingress and egress, computed live from its policies and workloads |
| `enable_security_baseline` | `mcp:write` | No | Publish the curated security baseline stack on a cluster: trivy-operator plus the pod-security policies in audit mode, committed to its GitOps repository |
| `get_cluster_security_history` | `mcp:read` | No | One cluster's daily security posture trend from its stored snapshots, oldest first: findings by severity, fixable critical/high, workloads and namespaces scanned, risk score and the actionable / acknowledged / accepted-risk split per day (`days`, 1 to 365, default 90) |
| `get_cluster_security_report_schedule` | `mcp:read` | No | The cluster's scheduled security report: whether one is configured, weekly or monthly, the email recipients, enabled or paused, when it last went out and when it is next due |
| `set_cluster_security_report_schedule` | `mcp:write` | No | Store the cluster's scheduled security report: frequency, up to 20 recipients and whether sending is enabled; replaces the whole schedule (clusters.write) |
| `send_cluster_security_report_now` | `mcp:write` | No | Email the cluster's security report to its scheduled recipients within the next minute; refuses when no schedule is configured (clusters.write) |
| `get_security_sbom_component` | `mcp:read` | No | Follow one exact package (name, version and ecosystem) to the images, workloads and clusters that run it |

## Backup Vaults

Available while the organisation's backups feature is enabled; vault creation with your own bucket keys stays in the portal and CLI. Stack protection, restore points and restores are in the Backups & Restore Points section below.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_backup_vaults` | `mcp:read` | No | The S3-compatible vaults backups and migration data move through, with verification status |
| `get_backup_vault` | `mcp:read` | No | One vault's provider, bucket, verification status and error excerpt (credentials never returned) |
| `list_backup_vault_imports` | `mcp:read` | No | The data imports a vault holds, with upload status, databases and restore progress |
| `provision_backup_vault` | `mcp:write` | No | Create a vault and let Ankra create its bucket from a stored credential (backups.manage) |
| `verify_backup_vault` | `mcp:write` | No | Re-run the credential check against a vault's bucket (backups.operate) |

## Provisioning & Nodes

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_instance_types` | `mcp:read` | No | Instance types and pricing per cloud provider |
| `list_proxmox_options` | `mcp:read` | No | Provisioning options a Proxmox VE credential can reach |
| `list_morpheus_options` | `mcp:read` | No | Provisioning options an HPE Morpheus credential can reach |
| `create_hetzner_cluster` | `mcp:write` | No | Create and provision a Kubernetes cluster on Hetzner Cloud |
| `create_ovh_cluster` | `mcp:write` | No | Create and provision a Kubernetes cluster on OVHcloud |
| `create_upcloud_cluster` | `mcp:write` | No | Create and provision a Kubernetes cluster on UpCloud |
| `create_digitalocean_cluster` | `mcp:write` | No | Create and provision a Kubernetes cluster on DigitalOcean |
| `create_aws_cluster` | `mcp:write` | No | Create and provision a self-managed Kubernetes cluster on AWS EC2, in a VPC Ankra creates or one you adopt - runs the create preflight first |
| `create_proxmox_cluster` | `mcp:write` | No | Create and provision a Kubernetes cluster on Proxmox VE |
| `create_morpheus_cluster` | `mcp:write` | No | Create and provision a Kubernetes cluster on HPE Morpheus |
| `list_cluster_nodes` | `mcp:read` | No | The provisioned VM nodes of a cluster, with live provider status |
| `restart_node` | `mcp:write` | No | Restart one provisioned node - control plane, worker, or bastion |
| `ssh_diagnose_node` | `mcp:read` | No | Diagnose a node at the OS level over SSH via the bastion |
| `ssh_repair_node` | `mcp:write` | No | Repair a node's Kubernetes service unit through the node-recovery engine |
| `list_kubernetes_versions` | `mcp:read` | No | The Kubernetes versions the platform knows per engine (kubeadm and k3s), with the default install version and supported channels |
| `list_upcloud_options` | `mcp:read` | No | The live UpCloud zones and server plans a credential can reach, with prices and GPU details |
| `create_scaleway_cluster` | `mcp:write` | No | Create and provision a self-hosted Kubernetes cluster on Scaleway Instances |
| `import_cluster` | `mcp:write` | No | Import an existing Kubernetes cluster from any distribution or provider into Ankra, without provisioning new infrastructure |
| `get_provider_quotas` | `mcp:read` | No | What a cloud-provider credential may still create, with per-dimension limits and usage |
| `request_provider_quota_increase` | `mcp:write` | No | Raise a cloud-provider limit for a credential (Azure), or produce the exact request to submit by hand for other providers |
| `get_bastion_health` | `mcp:read` | Yes | The bastion health verdict the platform last recorded for an Ankra-provisioned cluster |
| `diagnose_bastion` | `mcp:read` | Yes | Inspect an Ankra-provisioned cluster's SSH bastion host, including sshd configuration, failed logins, disk and pending security updates |
| `harden_bastion` | `mcp:write` | No | Apply a curated, revertable sshd hardening action set to an Ankra-provisioned cluster's SSH bastion |
| `get_node_cloud_init_log` | `mcp:read` | No | The cloud-init status and output log tail of one node of an Ankra-provisioned cluster, read over SSH |
| `get_etcd_members` | `mcp:read` | No | The etcd membership, member health, alarms and quorum of an Ankra-provisioned cluster, read over SSH |
| `remove_etcd_member` | `mcp:write` | No | Remove a dead control-plane node's stale member from an Ankra-provisioned cluster's etcd, run on a healthy peer over SSH |
| `ssh_kubectl_read` | `mcp:read` | No | Run one allowlisted read-only kubectl command on a control-plane node over SSH, only when the cluster's agent is not answering |
| `ssh_kubectl_recover` | `mcp:write` | No | Run one allowlisted state-changing kubectl command on a control-plane node over SSH to recover a cluster whose agent is offline |

## Cluster Lifecycle & Node Groups

Day-2 operations for Ankra-provisioned clusters on every self-managed provider (Hetzner, OVHcloud, UpCloud, DigitalOcean, Scaleway, AWS EC2, Proxmox VE, HPE Morpheus). These tools accept `cluster_name` or `cluster_id` directly, so they work from any conversation.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_node_groups` | `mcp:read` | No | Node groups, control plane topology, and worker counts for one cluster |
| `scale_workers` | `mcp:write` | No | Scale the default worker pool, or one named node group |
| `add_node_group` | `mcp:write` | No | Add a node group with instance type, count, and optional labels, taints, and autoscaling |
| `update_node_group` | `mcp:write` | No | Change a node group's autoscaling bounds, labels and taints in one call, or its instance type on its own (that replaces every node). Scales nodes, not pods |
| `delete_node_group` | `mcp:write` | No | Delete a node group and its nodes |
| `change_control_plane` | `mcp:write` | No | Change the control plane's node count or instance type. Growing the count and resizing three or more controllers run live; reducing the count runs on a stopped cluster. Resizing the only controller of a running Hetzner cluster takes the Kubernetes API down for a few minutes and needs `accept_api_downtime: true` |
| `stop_cluster` | `mcp:write` | No | Stop a cluster and keep its configuration: on Hetzner, OVHcloud, UpCloud, DigitalOcean, Proxmox VE and HPE Morpheus the virtual machines are deleted after an etcd snapshot (a Hetzner, UpCloud or DigitalOcean k3s cluster can pause instead and keep them powered off); AWS EC2, Scaleway and Ankra Cloud power the servers off and keep them |
| `start_cluster` | `mcp:write` | No | Start (re-provision) a stopped cluster, optionally control plane only |
| `upgrade_preflight` | `mcp:read` | No | Check a Kubernetes version hop without changing anything: the hop plan per node, running operations, PodDisruptionBudgets, CloudNativePG settings, control-plane memory, restore points, control-plane reachability and the k3s address pins, each answered pass, warn, block or skipped |
| `upgrade_cluster` | `mcp:write` | No | Upgrade the cluster's Kubernetes version. Runs the same preflight first and refuses on a block; never forces past a PodDisruptionBudget |
| `delete_cluster` | `mcp:write` | No | Deprovision a cluster entirely; requires re-typing the cluster name to confirm |
| `update_cluster` | `mcp:write` | No | Change a cluster's settings, today only its environment label |
| `set_cluster_agent_auto_upgrade` | `mcp:write` | No | Turn automatic upgrades of the Ankra agent on a cluster on or off |
| `move_cluster_to_organisation` | `mcp:write` | No | Move a cluster into another existing organisation (administrator of both organisations only) |
| `list_power_schedules` | `mcp:read` | No | A cluster's scheduled one-off or repeating stop and start actions, with their next run and last outcome |
| `create_power_schedule` | `mcp:write` | No | Schedule a stop or start of an Ankra-provisioned cluster once or on a cron expression in a time zone. An enabled `scale_to_zero` stop is refused unless a person has confirmed the cluster is not production |
| `update_power_schedule` | `mcp:write` | No | Replace a power schedule's action, timing and enabled flag, restating every field. An update that results in an enabled `scale_to_zero` stop is refused unless a person has confirmed the cluster is not production |
| `delete_power_schedule` | `mcp:write` | No | Delete a power schedule without touching the cluster itself |

## Managed Kubernetes

Create and operate provider-managed control planes - EKS (AWS), AKS (Azure), GKE (Google Cloud), DOKS (DigitalOcean), UKS (UpCloud), OVHcloud MKS, and Kapsule (Scaleway).

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_managed_k8s_options` | `mcp:read` | No | Regions, versions, and machine sizes a credential can deploy; per-cluster options and available upgrades |
| `create_managed_cluster` | `mcp:write` | No | Create a managed Kubernetes cluster with one or more node pools |
| `list_managed_node_pools` | `mcp:read` | No | Node pools of a managed cluster with counts and autoscaling state |
| `add_managed_node_pool` | `mcp:write` | No | Add a node pool with size, count, and optional autoscaling |
| `update_managed_node_pool` | `mcp:write` | No | Update a node pool's count or autoscaling configuration |
| `delete_managed_node_pool` | `mcp:write` | No | Delete a node pool |
| `discover_managed_clusters` | `mcp:read` | No | The managed clusters already running behind a provider credential, marking the ones Ankra has imported |
| `import_managed_cluster` | `mcp:write` | No | Adopt a managed cluster that already runs at the provider; Ankra fetches the kubeconfig and installs the agent itself |
| `upgrade_managed_cluster` | `mcp:write` | No | Upgrade a managed cluster's Kubernetes version |
| `stop_managed_cluster` | `mcp:write` | No | Stop a managed cluster through provider-native power control when supported (AKS today) |
| `start_managed_cluster` | `mcp:write` | No | Start a stopped managed cluster through provider-native power control when supported |

## CI/CD & Deploy Analysis

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `cicd_propose_application_pipeline` | `mcp:read` | No | Render the canonical Ankra CI/CD pipeline for a target repository |
| `cicd_validate_workflow_yaml` | `mcp:read` | No | Validate a GitHub Actions workflow against Ankra's platform invariants |
| `cicd_validate_chart_values` | `mcp:read` | No | Validate Helm chart values against Ankra's Kubernetes security defaults |
| `deploy_inspect_chart_values` | `mcp:read` | Yes | Probe a chart's values for the paths the deploy wizard cares about |
| `deploy_inspect_repo` | `mcp:read` | Yes | Inspect key repository files for the application's runtime needs |
| `deploy_finalize_analysis` | `mcp:read` | Yes | Finalise a deploy analysis with the full analysis payload |
| `cicd_convert_workflow_to_pipeline` | `mcp:read` | No | Convert an existing GitHub Actions, GitLab CI, Bitbucket Pipelines or CircleCI definition into an Ankra pipeline |
| `cicd_validate_pipeline_yaml` | `mcp:read` | No | Validate an Ankra pipeline definition (`.ankra/pipeline.yaml`) before proposing or committing it |
| `get_pipeline_step_logs` | `mcp:read` | No | Read an Ankra Pipelines run and one step's archived log tail, to explain why a step failed |
| `watch_pipeline_run` | `mcp:read` | No | Register a watch on an Ankra Pipelines run, so the conversation is woken with its outcome |

## Tickets & Collaboration

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `ticket_list` | `mcp:read` | No | List the organisation's AI work board tickets |
| `ticket_get` | `mcp:read` | No | One ticket in full: plan, review state, timeline, and links |
| `file_ticket` | `mcp:write` | No | File a new ticket on the AI work board |
| `ticket_comment` | `mcp:write` | No | Post a comment on a ticket |
| `ticket_update_status` | `mcp:write` | No | Move a ticket through its lifecycle |
| `ticket_draft_plan` | `mcp:write` | No | Write or revise a ticket's plan document |
| `ticket_request_review` | `mcp:write` | No | Ask for a review of the ticket's drafted plan |
| `ticket_submit_review` | `mcp:write` | No | Deliver a peer-review verdict on a ticket's plan |
| `ticket_attach_demo` | `mcp:write` | No | Attach a demo environment to a ticket |
| `ticket_assign` | `mcp:write` | No | Assign a ticket to an agent, or clear its assignee so the board can staff it again |
| `list_agent_tasks` | `mcp:read` | No | List the organisation's AI agents with a `can_work_board` verdict and, when they cannot, the reason |
| `designate_board_worker` | `mcp:write` | No | Designate an agent as a board worker, or remove that designation |
| `list_agent_runs` | `mcp:read` | No | List the organisation's dispatched AI agent runs, newest first |
| `get_agent_run` | `mcp:read` | No | One agent run in full, optionally with its session transcript tail |
| `cancel_agent_run` | `mcp:write` | No | Cancel a live agent run and its session (organisation admins only) |
| `ticket_decide` | `mcp:write` | No | Answer the choice a blocked ticket is waiting on and resume its agent with that answer |
| `ticket_set_cluster` | `mcp:write` | No | Set or clear the cluster an existing board ticket targets |
| `list_ticket_sync_connections` | `mcp:read` | No | The configured Jira, Linear or webhook destinations that AI work board tickets mirror to |
| `provision_board_identity` | `mcp:write` | No | Provision the organisation's board service principal that platform-created agents act as on board tickets (organisation admins only) |

## Support Tickets

The support desk - the same tickets `ankra support` and the portal's Support page show. These are requests to Ankra's support team, distinct from the AI work board's tickets above. Attachments stay in the portal and CLI because they carry file bytes.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_support_tickets` | `mcp:read` | No | The organisation's support tickets with status, category, severity and cluster; filter by status, cluster or search text |
| `get_support_ticket` | `mcp:read` | No | One ticket in full by number or id: description, the conversation with support, and attachment names |
| `create_support_ticket` | `mcp:write` | No | Raise a support ticket with Ankra's team on the user's behalf (source `agent`); defaults to the session's cluster in chat |
| `comment_support_ticket` | `mcp:write` | No | Reply on a ticket as the customer; a ticket waiting on you moves back to in progress |
| `close_support_ticket` | `mcp:write` | No | Close a ticket from the customer's side, the same action as `ankra support close` |

## Organisation & AI Posture

The organisation a token is bound to, who has access, what is parked awaiting a human decision, and how the organisation's AI is configured. Membership, role, provider-key and endpoint writes stay in the portal and CLI.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `get_organisation` | `mcp:read` | No | The bound organisation: id, name, slug, member counts, organisation-wide settings and the current project |
| `list_organisation_members` | `mcp:read` | No | Who has access: members, pending invites and Ankra's service principals, with roles |
| `list_organisation_roles` | `mcp:read` | No | Built-in and custom roles with the permissions each grants |
| `list_organisation_custom_dns_zones` | `mcp:read` | No | The DNS zones the organisation's clusters serve with their own credentials |
| `list_limit_requests` | `mcp:read` | No | The latest limit-increase request per kind (billing.read) |
| `list_pending_actions` | `mcp:read` | No | AI actions parked for a human decision, with risk, cluster, expiry and the bill of materials |
| `decide_pending_action` | `mcp:write` | No | Approve or reject a parked action on behalf of an organisation admin; approving resumes the session that proposed it. MCP-only: in chat the action's own card is the decision |
| `get_ai_settings` | `mcp:read` | No | The active provider, which providers are configured (never the keys or endpoint addresses), and the autonomy pause state |
| `list_ai_models` | `mcp:read` | No | The model catalog the chat picker offers, with tool, thinking and image support |
| `pause_ai_autonomy` | `mcp:write` | No | Pause autonomous AI actions organisation-wide (ai.manage); chat and diagnosis keep working |
| `resume_ai_autonomy` | `mcp:write` | No | Restore exactly what the pause turned off (ai.manage) |
| `get_remediation_policy` | `mcp:read` | No | The organisation's AI auto-remediation policy, including autonomy level, tier overrides and the cluster allow list |
| `get_ai_environment` | `mcp:read` | No | The organisation's AI environment settings, such as the staging cluster for AI workspaces and PR demos and their TTLs |
| `update_ai_environment` | `mcp:write` | No | Change the organisation's AI environment settings, such as the staging cluster that turns on PR previews (organisation admins only) |
| `request_limit_increase` | `mcp:write` | No | Ask the Ankra team to raise an organisation limit, such as playground memory, the free AI allowance or registry storage |
| `get_registry_storage` | `mcp:read` | No | The organisation's image registry storage limit and usage per project, and the retention policy that decides what is kept |
| `set_registry_retention` | `mcp:write` | No | Change which images the organisation's registry keeps, organisation-wide or per repository |
| `run_registry_retention` | `mcp:write` | No | Run the organisation's registry retention now instead of at its daily time |
| `set_registry_storage_addon` | `mcp:write` | No | Buy or return paid registry storage blocks, billed monthly |

## Projects

Every tool acts in one [project](/concepts/projects): an MCP token minted while the organisation has projects is pinned to the project it was created in, and a chat session follows the member's current project. An MCP token minted before that is not pinned (`get_current_project` answers `pinned: false`) and never follows a switch: for an organisation-wide member it acts in the Default project whatever its owner switches to, and a project-only member's acts in the oldest project they reach. `get_organisation` reports that project, list results carry each resource's `project_id`, and the cost tools below take `project_id` (a project id, `all` for the whole organisation, or nothing for the current project; a pinned token refuses `all` and other projects).

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_projects` | `mcp:read` | No | The organisation's projects with id, name, slug, whether each is the reserved default and which is current |
| `get_current_project` | `mcp:read` | No | The project this token or session acts in, and whether the token is pinned to it |
| `move_cluster_to_project` | `mcp:write` | No | Move a cluster into another project of the organisation (`projects.manage`); its DNS zones, incidents, AI tickets and pinned notification routes follow; confirmed before it runs |
| `move_application_to_project` | `mcp:write` | No | Move an application into another project of the organisation (`projects.manage`); its connected pipeline repositories follow; confirmed before it runs |

## Memory & Miscellaneous

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `search_memories` | `mcp:read` | No | Search past conversation memories for relevant context |
| `save_memory` | `mcp:write` | No | Save a fact, decision, or preference to long-term memory |
| `web_fetch` | `mcp:read` | No | Fetch content from a public HTTPS URL as readable text |
| `get_portal_url` | `mcp:read` | No | The Ankra portal URL for a page (a cluster, stack, add-on, pod, application, pipeline run, ticket, alert, CVE, settings and more); reads and changes nothing. See [Portal URLs](/platform/portal-urls) |
| `ask_question` | `mcp:read` | No | Ask the user a structured multiple-choice question to resolve a genuine ambiguity |
| `todo_write` | `mcp:read` | No | Keep a structured todo list for a multi-step task |
| `propose_plan` | `mcp:read` | No | Produce a structured plan of write operations for the user to review and approve |
| `dispatch_subworker` | `mcp:read` | No | Spawn a focused child agent for a narrowly scoped task |
| `canvas_present` | `mcp:read` | No | Create or update a self-contained HTML, SVG, JavaScript or Markdown artifact on the chat canvas |

## Backups & Restore Points

Scheduled stack protection, restore points and the runs behind them. Available while the organisation's backups feature is enabled.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `get_backup_posture` | `mcp:read` | No | Whether data is protected and if not why, for the organisation, one cluster or one stack |
| `list_stack_data_assets` | `mcp:read` | No | The persistent volume claims and databases a stack actually holds |
| `list_restore_points` | `mcp:read` | No | Restore points newest first, for one stack or the whole organisation, each with what it does not carry |
| `get_restore_point` | `mcp:read` | No | One restore point in full, including its assets, verification and what it does not carry |
| `list_data_runs` | `mcp:read` | No | Backup, restore and clone runs newest first |
| `get_data_run` | `mcp:read` | No | One backup, restore or clone run with every attempt of every step, to explain a failure |
| `protect_stack` | `mcp:write` | No | Turn on scheduled backup protection for a stack, written through GitOps |
| `unprotect_stack` | `mcp:write` | No | Turn off scheduled backup protection for a stack while keeping existing restore points |
| `create_stack_restore_point` | `mcp:write` | No | Take a restore point of a stack now |
| `restore_restore_point_in_place` | `mcp:write` | No | Replace a stack's current data with a restore point's data, confirmed by typing the stack's name |
| `delete_restore_point` | `mcp:write` | No | Delete a restore point and remove its objects from the backup vault |
| `cancel_data_run` | `mcp:write` | No | Cancel a running backup, restore or clone |
| `retry_data_run` | `mcp:write` | No | Retry a failed backup, restore or clone from the step that failed |

## Cost & Usage

Cloud cost estimates, budgets and the cost autopilot, plus the organisation's usage of Ankra.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `get_fleet_cloud_cost` | `mcp:read` | No | The cloud cost rollup of the current project (or `project_id`), split by provider and by project, with the costliest clusters |
| `get_object_cost` | `mcp:read` | No | What one cluster, namespace, stack, application or cloud credential costs |
| `get_namespace_cost_history` | `mcp:read` | Yes | How the cluster's cost was allocated to each namespace over time |
| `get_cloud_savings` | `mcp:read` | No | The organisation's cloud savings recommendations, the same model the portal's Cost page shows |
| `get_cost_reconciliation` | `mcp:read` | No | What each cloud credential's provider billed for a month against Ankra's estimate |
| `get_cost_settings` | `mcp:read` | No | The organisation's cost display currency, discount, egress estimate and analysed cluster limit |
| `update_cost_settings` | `mcp:write` | No | Replace the organisation's cost pricing settings, restating every value |
| `get_cost_budgets` | `mcp:read` | No | The organisation's monthly cost budgets with spend so far and the projected month end |
| `set_cost_budget` | `mcp:write` | No | Create a monthly cost budget for the organisation, a project, a cluster, an environment or an application, or change one |
| `delete_cost_budget` | `mcp:write` | No | Delete one of the organisation's cost budgets (organisation admins only) |
| `get_cost_autopilot` | `mcp:read` | No | The organisation's cost autopilot policy, which decides how much Ankra may do about cost unasked |
| `update_cost_autopilot` | `mcp:write` | No | Change the cost autopilot policy, one project's defaults, or one cluster's tier |
| `get_usage` | `mcp:read` | No | The organisation's usage of Ankra per meter and period, such as worker vCPU-hours, hosted logs and AI tokens |

## Managed Services

Managed services such as PostgreSQL, Valkey and OpenSearch set up for an application, the same surface as `ankra services`. Setup, retirement and disconnecting one application are two steps each, a prepared review and a confirmation.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_service_packages` | `mcp:read` | No | The managed-service packages the organisation may set up, with their package version ids |
| `get_service_package` | `mcp:read` | No | One managed-service package version's contract, with its modes, parameters and secret inputs |
| `get_service_setup_eligibility` | `mcp:read` | No | Which managed services one application environment can set up right now, with the reason and fix when blocked |
| `get_service_cluster_policy` | `mcp:read` | No | A cluster's managed-service placement policy, with its region and data boundary |
| `set_service_cluster_policy` | `mcp:write` | No | Declare a cluster's managed-service placement policy (optional; without one, setup uses the default location) |
| `list_service_consumers` | `mcp:read` | No | One application's consumer bindings for managed services |
| `bind_service_consumer` | `mcp:write` | No | Bind an application namespace on a cluster as a consumer of managed services |
| `unbind_service_consumer` | `mcp:write` | No | Remove a consumer binding that no unretired service still uses |
| `prepare_service_setup` | `mcp:write` | No | Prepare the review of a new managed service, returning its plan without deploying anything |
| `confirm_service_setup` | `mcp:write` | No | Confirm a prepared managed-service review and start its deployment |
| `list_service_instances` | `mcp:read` | No | The organisation's managed services with state, readiness, health and consumers |
| `get_service_instance` | `mcp:read` | No | One managed service with its deployment state, health, readiness evidence, consumers and connection details (never credential values) |
| `prepare_service_retirement` | `mcp:write` | No | Prepare the retirement of a managed service, listing everything it would remove and keep without removing anything |
| `confirm_service_retirement` | `mcp:write` | No | Confirm a prepared retirement and delete the managed service and its data, which cannot be undone |
| `get_service_retirement` | `mcp:read` | No | One retirement of a managed service with its plan, state and outcome |
| `prepare_service_disconnection` | `mcp:write` | No | Prepare disconnecting one application environment from a managed service that keeps running for its other applications, returning the review without changing anything |
| `confirm_service_disconnection` | `mcp:write` | No | Confirm a prepared disconnection: the application keeps working until its next deploy, and Ankra removes its connection Secret once no pod reads it. The shared credential is not revoked |

## Cluster Mesh

Cilium cluster meshes that join two or more Ankra clusters into one flat pod network. Available while the organisation's cluster mesh feature is enabled.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_cluster_meshes` | `mcp:read` | No | The organisation's cluster meshes with status and every member cluster |
| `get_cluster_mesh` | `mcp:read` | No | One cluster mesh with its status and each member's Cilium identity and status |
| `check_cluster_mesh_readiness` | `mcp:read` | No | Whether the given clusters could form one mesh, with the failing checks per cluster |
| `create_cluster_mesh` | `mcp:write` | No | Create a new, empty cluster mesh with a name |
| `join_cluster_to_mesh` | `mcp:write` | No | Add one cluster to a mesh, which reconfigures its Cilium networking |
| `make_cluster_mesh_ready` | `mcp:write` | No | Make an existing cluster mesh-capable in place, without rebuilding it |
| `remove_cluster_from_mesh` | `mcp:write` | No | Remove one cluster from a mesh |
| `delete_cluster_mesh` | `mcp:write` | No | Delete a cluster mesh that has no members left |

## DNS

Cloudflare DNS records in the organisation's own Cloudflare account, and the extra DNS zones a cluster serves with the organisation's DNS credentials.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_cloudflare_domains` | `mcp:read` | No | The Cloudflare domains the organisation's Cloudflare credential can reach, with their ids and status |
| `list_cloudflare_dns_records` | `mcp:read` | No | The DNS records in one Cloudflare domain, each marked as created by Ankra or elsewhere |
| `create_cloudflare_dns_record` | `mcp:write` | No | Create a DNS record in one of the organisation's Cloudflare domains |
| `update_cloudflare_dns_record` | `mcp:write` | No | Change what an existing Cloudflare DNS record points at |
| `delete_cloudflare_dns_record` | `mcp:write` | No | Delete a DNS record from one of the organisation's Cloudflare domains, which Ankra cannot restore |
| `list_cluster_custom_dns_zones` | `mcp:read` | No | The DNS zones one cluster serves with the organisation's own DNS credentials, including inherited ones |
| `add_cluster_custom_dns_zone` | `mcp:write` | No | Declare that a cluster also serves a DNS zone with one of the organisation's DNS credentials |
| `remove_cluster_custom_dns_zone` | `mcp:write` | No | Withdraw a DNS zone a cluster declared, leaving its existing records in place |

## Object Storage

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_object_storage_buckets` | `mcp:read` | No | The object storage buckets Ankra created on the organisation's provider credentials (key material never returned) |
| `get_object_storage_bucket` | `mcp:read` | No | One object storage bucket's provider, region, endpoint and status (key material never returned) |
| `create_object_storage_bucket` | `mcp:write` | No | Create an object storage bucket on a Hetzner, Scaleway, DigitalOcean or UpCloud credential |
| `delete_object_storage_bucket` | `mcp:write` | No | Stop managing an object storage bucket, and optionally empty and delete it at the provider |

## Playgrounds

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `list_playground_plans` | `mcp:read` | No | The orderable playground sizes with prices, availability and the organisation's memory budget |
| `get_playground_status` | `mcp:read` | No | A playground's provisioning phase, expiry, starter app URL, size and price |
| `create_playground` | `mcp:write` | No | Order a hosted playground Kubernetes namespace at a named size, or the free trial |
| `resize_playground` | `mcp:write` | No | Resize a paid playground in place to another size |
| `destroy_playground` | `mcp:write` | No | Permanently destroy a playground and everything deployed in it |

## Agent MCP Tool Servers

External MCP tool servers an organisation registers to give its agent runs extra tools.

| Tool | Scope | Cluster-scoped | Description |
| - | - | - | - |
| `get_mcp_catalog` | `mcp:read` | No | The curated catalog of external MCP integrations an organisation admin can connect |
| `list_mcp_servers` | `mcp:read` | No | The organisation's registered MCP tool servers with state, permission tier and grant counts |
| `register_mcp_server` | `mcp:write` | No | Register an external MCP tool server for the organisation (organisation admins only) |
| `set_mcp_server_enabled` | `mcp:write` | No | Enable or disable a registered MCP tool server (organisation admins only) |
| `grant_mcp_tool` | `mcp:write` | No | Grant one of a registered server's tools to an organisation role so agent runs can call it (organisation admins only) |

## Related

* [MCP Server](/platform/mcp-server) - endpoint, tokens, and client setup
* [Portal URLs](/platform/portal-urls) - the portal page behind each resource
* [AI Assistant](/platform/ai-assistant) - the same tools in the product chat
* [API Tokens](/reference/tokens)
* [Portal Links](/reference/portal-links) - build a portal link from the IDs and names these tools return


# Find out why a deploy failed and retry it
Source: https://docs.ankra.ai/platform/operations

Open the operation behind a failed deploy, read the step that failed, then retry or cancel it from the portal or the CLI.

A Stack deploy or add-on upgrade failed and you need to know which part broke and whether it is safe to run again. Every change Ankra makes to a cluster runs as an **operation**, and each operation is split into **steps** - one per add-on install, manifest apply, GitOps sync and so on. This guide shows how to find the failed step, read its error and retry the operation.

## Prerequisites

* Access to the cluster in the Ankra portal, or the [Ankra CLI](/integrations/ankra-cli) logged in to your organisation.

## Find the failed operation

**1. Open the cluster's operations**

Open the cluster and select **Operations** in the cluster sidebar. The list shows every operation with its status and duration. A failed step also raises an **Execution step failed** card in your [Activity & Inbox](/platform/activity-inbox), which links to the same operation.

**2. Open the operation**

Select the failed operation. Its steps are laid out in **Pending**, **Active** and **Completed** columns (the portal labels the steps **Jobs**), with the total duration at the top. Use **Search jobs...** to find a step by name.

**3. Read the failed step**

Select the step marked as failed. The panel shows the Stack, add-on, chart and namespace it targeted, its **Status events**, and the **Tasks** it ran with their output and error. Steps after a failure show **Not Executed**: they were skipped because an earlier step failed, not because they are broken themselves.

**4. Ask the AI if the error is not obvious**

Select **Ask AI about this operation** to open the [AI Assistant](/platform/ai-assistant) with the operation already in context.

Fix the cause first - a wrong value in the add-on configuration, a missing Secret, a namespace that does not exist - then retry.

## Retry or cancel

* **Retry operation** is available on a failed operation. A retry starts a **new** operation that re-plans only the resources that did not finish; the failed one stays in the history as it was. Retry is refused while the cluster has another operation running, while the cluster is offline, and when a newer operation of the same type already exists - in that case, look at the newer one instead.
* **Cancel operation** is available while an operation is running. It stops the operation.

There is no pause or resume.

```bash theme={null}
# List failed operations on the selected cluster that still need someone
ankra cluster operations list --attention open

# Show the steps of one operation
ankra cluster operations steps <execution-id>

# Retry a failed operation (starts a new one)
ankra cluster operations retry <execution-id>

# Cancel a running operation, or one step of it
ankra cluster operations cancel <execution-id>
ankra cluster operations cancel-step <execution-id> <step-id>
```

## Verify

Open **Operations** again. The retry appears as a new operation at the top; wait for it to finish as successful. The original failed row keeps its failed status, and once the resources it failed on are healthy it shows a **Resolved** label.

## Failed history versus open problems

The operations list is an audit log, not a to-do list. A failed operation keeps its failed status for as long as the record is kept, and nothing acknowledges or deletes it, so a rollout that needed a few attempts leaves its failed attempts in the history for good.

What tells you whether a failure still needs someone is its attention state:

| State | Meaning |
| - | - |
| `none` | The operation did not fail |
| `open` | It failed, was critical or was cancelled, and nothing has fixed it since |
| `resolved` | Every resource its failed steps targeted has recovered - a later run on the same resource succeeded, the resource is up, or it was removed |

The state is worked out each time you read the list, so a successful retry resolves the operation it retried. In the portal a resolved failure carries the **Resolved** label; in the CLI filter with `--attention open` or `--attention resolved`.

The cards in [Activity & Inbox](/platform/activity-inbox) are the attention list: they clear on their own once the underlying problem recovers, or when you dismiss them.

## Next step

If a retry keeps failing on the same step, open a [support ticket](/platform/support) with the operation link, or ask the [AI Assistant](/platform/ai-assistant) about it.


# Organisation Settings
Source: https://docs.ankra.ai/platform/organisation-settings

Configure your organisation's name, agent auto-upgrades, and DNS records - and where to find the AI settings.

> [!NOTE]
>
> Organisation settings apply to all clusters and resources within your organisation. Only administrators can modify these settings.

## Accessing Organisation Settings

1. Click your profile icon in the bottom left corner of the Ankra platform.
2. Select **Organisation** from the menu.
3. Click **Settings** in the organisation view.
4. Navigate to **General** to access these settings.

***

## Projects

**Settings → People and access → Projects** lists the organisation's [projects](/concepts/projects), the Default project first, with each one's short name, description and who reaches it. Members with `projects.manage` (owners and admins) create, rename and delete projects here; everyone else sees the list read-only. A project that still holds resources cannot be deleted, and the refusal names what it holds by kind. Project-scoped resources are moved from their own settings pages, and the project switcher beside the organisation switcher changes the project you are working in. To limit someone to one project, give them the **Project only** membership role on the **People** page; see [Project-only members](/concepts/projects#project-only-members).

***

## General Settings

### Organisation Name

Change the display name of your organisation. This name appears throughout the platform and helps identify your workspace.

**1. Navigate to Settings**

Go to **Organisation Settings** → **General**.

**2. Edit the Name**

Enter a new name in the **Organisation Name** field.

**3. Save Changes**

Click **Save Changes** to apply.

> [!NOTE]
>
> Only administrators can rename organisations. Members will see the rename option disabled.

***

## Agent Settings

Configure default agent behaviour for all clusters in your organisation.

### Auto-upgrade Agents

When enabled, cluster agents automatically upgrade to the latest version when available. This ensures your clusters stay up-to-date with security patches and new features.

| Setting | Description |
| - | - |
| **Enabled** | Agents upgrade automatically when new versions are released |
| **Disabled** | Agents remain at their current version until manually upgraded |

> [!TIP]
>
> Individual clusters can opt-out of auto-upgrades in their own settings, even when the organisation setting is enabled. See [Cluster Settings](/platform/cluster-settings) for details.

**How Auto-upgrade Works:**

1. Ankra releases a new agent version
2. The platform detects clusters running older versions
3. If auto-upgrade is enabled (and the cluster hasn't opted out), the agent is upgraded automatically
4. The upgrade process is seamless with minimal disruption

***

## AI settings

Ankra's AI has its own settings area: open **AI** → **Settings**. Proactive insights, models and cost, connections to Slack, Teams and source control, and how much the AI may do on its own are all set there, not in Organisation Settings. See [Ankra AI](/platform/ai-overview) for what each setting controls, and [AI Insights](/platform/ai-insights) to turn on proactive cluster analysis.

***

## DNS Records

Organisation admins can create manual CNAME, A, and TXT records under your organisation's own delegated Ankra subdomain (under `ankra.cc` by default, or the [Ankra domain your organisation selected](/concepts/applications#the-preview-url)) - useful for aliasing an add-on's auto-generated hostname to something memorable.

![Walkthrough of the DNS records console: adding a CNAME record, filtering the list, editing a record's target in place, deleting a record, and switching between light and dark themes](https://mintcdn.com/ankra/QTIxthxO-T9_QJcI/images/dns-records-walkthrough.gif?s=c6c143928253865027a2f7d4b9e82d1b)

Adding, searching, editing, and deleting DNS records in the organisation console

**1. Navigate to DNS Records**

Go to **Organisation Settings** → **DNS records**.

**2. Add a record**

Click **Add record**, enter a label (for example `logs`), pick a record type (CNAME, A, or TXT), enter the target, and choose a **TTL** (Auto, or 1 minute up to 1 hour). Your organisation's zone is appended to the label automatically.

**3. Track its state**

New records provision asynchronously and show as **Pending** until the record is live in DNS (**Active**), or **Failed** with the reason if provisioning didn't succeed.

**4. Edit or delete a record**

Use the row actions to **edit** a record's target and TTL in place, or **delete** it. Editing re-points the record and returns it to **Pending** until the change is live. To change a record's name or type, delete it and add a new one.

### Cluster domains

The same page lists every cluster's own delegated Ankra domain (`<cluster-id>.<org-id>.<ankra-domain>`) with its provisioning state. **Remove** hands a cluster's domain back for teardown - the step required on every cluster before [switching the organisation's Ankra domain](/concepts/applications#the-preview-url) - and **Enable domain** brings a cluster (back) under the organisation's current Ankra domain; external-dns picks a newly enabled domain up on the cluster's next cloud-provider pass.

> [!NOTE]
>
> **external-dns on a cluster manages that cluster's Ankra domain and nothing else.** The credential Ankra provisions when you create a cluster with public DNS included is scoped to `<cluster-id>.<org-id>.<ankra-domain>`, so an Ingress on any other zone - one of your own domains, or another cluster's - is filtered out by the DNS provider before a record is written. The sync still logs `All records are already up to date`, because from external-dns's point of view there is nothing in scope to publish, so a hostname being dropped looks the same as one being current.
>
> Ingress hostnames on your own domains therefore need a publisher of their own, and an unpublished name also delays cert-manager: an HTTP-01 challenge is answered over the hostname being certified, so no certificate is issued for a name that does not resolve yet. Declare the zone with your own DNS credential - once, for every cluster in the organisation - and Ankra runs a second, zone-pinned external-dns for it on each cluster: see [serving a zone in your own DNS account from every cluster](/concepts/applications#serving-a-zone-in-your-own-dns-account-from-every-cluster). A domain held in Avura is added from **Custom domains** → **Add domain** with **Avura** as the provider, and its records are managed under **Settings** → **Avura**: see [use Avura domains with Ankra](/guides/avura-domains).
>
> When the declared zone covers the organisation's **Preview domain**, that domain becomes the cluster's public domain: `${{ ankra.cluster_domain }}` in stacks and profiles, Ankra AI's hostname advice, the deploy wizard's default hostname and `ankra cluster domain` all report it instead of the generated Ankra domain, and the "hostnames will not resolve" warning on the Preview domain clears.

The CLI carries the same operations, plus the declarations for zones in your own DNS account:

```bash theme={null}
ankra org dns zones                          # list every cluster domain and its state
ankra cluster domain <cluster>               # read one cluster's domain (creates nothing)
ankra cluster domain <cluster> --enable      # create it
ankra cluster domain <cluster> --remove      # hand it back for teardown
ankra org dns credentials create --name my-dns --webhook-provider-url <url>   # your own external-dns webhook credential
ankra org custom-dns-zones add --zone example.dev --credential my-dns         # serve the zone from every cluster, present and future
ankra cluster custom-dns-zones add <cluster> --zone example.dev --credential my-dns   # or from one cluster only
```

> [!NOTE]
>
> Any organisation member can view the record list; only administrators can add, edit, or delete records. A record's own zone must be active before a record can be created under it - new organisations provision this automatically, and the DNS records page shows the zone and its status at the top.

> [!NOTE]
>
> A CNAME record can never share a name with another record (standard DNS behaviour), and each name/type pair can only have one record.

***

## Danger Zone

> [!WARNING]
>
> Actions in the Danger Zone are destructive and cannot be undone. Proceed with extreme caution.

### Delete Organisation

Permanently remove your organisation and all associated data, including:

* All clusters (disconnected, not deleted from your infrastructure)
* All stacks and configurations
* All credentials and integrations
* All user memberships

**1. Navigate to Danger Zone**

Go to **Organisation Settings** → **General** and scroll to the **Danger Zone** section.

**2. Click Delete**

Click the **Delete** button. Only administrators see this option.

**3. Confirm Deletion**

Type the organisation name exactly as shown to confirm, then click **Delete Organisation**.

> [!WARNING]
>
> Deleting an organisation does not delete resources from your Kubernetes clusters. It only removes them from the Ankra platform. Running workloads will continue to run.

***

## Related Settings

> [card] [Variables](/concepts/variables)
>
> Define organisation-wide variables for use in stacks.

> [card] [Encryption (SOPS)](/guides/sops)
>
> Configure SOPS encryption for your organisation.

> [card] [Cluster Settings](/platform/cluster-settings)
>
> Configure individual cluster settings.

> [card] [DNS Records](/platform/organisation-settings#dns-records)
>
> Create custom CNAME, A, and TXT records under your organisation's Ankra subdomain.

> [card] [User Management](/concepts/organisations)
>
> Invite users and manage roles.


# Pod Terminal for Kubernetes in Your Browser
Source: https://docs.ankra.ai/platform/pod-terminal

Open a pod terminal on any running Kubernetes container from the browser or the CLI. Pick the container and shell, with no kubeconfig or port-forward.

A pod terminal is an interactive shell inside a running Kubernetes container, the same thing `kubectl exec -it` gives you. In Ankra you open one from the pod's **Terminal** tab in the browser, or with `ankra cluster terminal` from your own shell, with no kubeconfig and no port-forward.

Choose your shell, select the target container, and debug issues without leaving the browser. Every session is recorded in the audit log.

***

## Opening a Terminal

**1. Navigate to a Pod**

Go to **Clusters → \[Your Cluster] → Kubernetes → Workloads → Pods** and select a running pod.

**2. Open the Terminal Tab**

Click the **Terminal** tab in the pod detail view.

**3. Select Container and Shell**

If the pod has multiple containers, select the target container from the dropdown. Choose your preferred shell (`/bin/sh`, `/bin/bash`, `/bin/zsh`, or `/bin/ash`).

**4. Connect**

Click **Connect** to start the terminal session. You'll see a green "Connected" indicator when the session is active.

### From the CLI

The same terminal is available from the shell you are already in, through the platform - no kubeconfig and no port-forward:

```bash theme={null}
ankra cluster terminal api-6d8f9c7b5-x2kq9 --namespace payments
ankra cluster terminal api-6d8f9c7b5-x2kq9 --namespace payments --container sidecar --shell /bin/bash
```

The local terminal is put in raw mode, so every keystroke (Ctrl-C included) reaches the remote shell and window resizes follow your terminal; leave with `exit` or Ctrl-D. A pod with one container needs nothing more; one with several takes `--container`. The command needs `kubernetes.exec` on the cluster, and the session is recorded and audited exactly like a portal one (see [Recorded sessions](#recorded-sessions)). `ankra cluster debug create --attach` uses it to drop straight into a freshly created [debug pod](/platform/debug-pods).

### One-off commands

To run a single command rather than open a shell - a `psql -c` check, a `curl` from inside the pod, reading a config file - use `ankra cluster exec`. It runs the command, streams its output, and exits with the command's own exit code, so a script or CI job can branch on it:

```bash theme={null}
ankra cluster exec cnpg-cluster-1 -n cnpg-database -c postgres -- psql -U postgres -d appdb -Atc 'select count(*) from users'
ankra cluster exec api-6d8f9c7b5-x2kq9 -n payments -- curl -sf localhost:8080/healthz
ankra cluster exec cnpg-cluster-1 -n cnpg-database -c postgres --stdin -- psql -U postgres -d appdb < query.sql
```

Everything after `--` is passed to the container exactly as given: no shell re-parses it, so quote once for your local shell and not again. For pipes, globs or variables, run a shell explicitly: `-- sh -c 'env | grep ^APP_'`. (`ankra cluster terminal --shell` names a shell binary and cannot carry arguments; `exec` is the way to run a command.)

| Option | Effect |
| - | - |
| `-c`, `--container` | The container to run in; needed only when the pod has several |
| `--stdin` | Forward your input to the command; it sees end-of-file when your input ends. Without it the command gets no input |
| `-o json` / `-o yaml` | Print one `{exit_code, stdout, stderr, stdout_truncated, stderr_truncated}` document when the command ends instead of streaming (each stream capped at 8 MiB) |

The command runs without a TTY. When it ran, `ankra cluster exec` exits with its exit code; otherwise with the CLI's usual codes (`6` for a refused credential, `7` without `kubernetes.exec`, `1` when the command could not be started, for example because the binary does not exist in the image).

`exec` goes through the same platform relay as the terminal: it needs `kubernetes.exec` on the cluster, and each run is [recorded](#recorded-sessions) with an `open_pod_terminal` audit row whose details carry the exact command (`command: [...]`) instead of a shell. It needs a cluster agent recent enough to run one-off commands; an older agent is refused with the version it needs and nothing is run - upgrade it with `ankra cluster agent upgrade`.

***

## Features

| Feature | Description |
| - | - |
| **Multi-container support** | Select any container in a pod, including init containers and sidecars |
| **Shell selection** | Choose between `/bin/sh`, `/bin/bash`, `/bin/zsh`, and `/bin/ash` |
| **Auto-resize** | Terminal automatically adjusts to your browser window size |
| **Connection status** | Clear visual indicator showing disconnected, connecting, connected, or error states |
| **Reconnect** | Quickly reconnect after a disconnection without leaving the page |

***

## Supported Shells

| Shell | Path | Notes |
| - | - | - |
| sh | `/bin/sh` | Available in virtually all containers (default) |
| bash | `/bin/bash` | Available in most full Linux-based images |
| zsh | `/bin/zsh` | Available if installed in the container |
| ash | `/bin/ash` | Common in Alpine-based images |

> [!TIP]
>
> If the container uses an Alpine-based image, use `/bin/sh` or `/bin/ash`. Bash is not included in Alpine by default.

***

## Recorded sessions

Every terminal session opened through Ankra is recorded, and so is every `ankra cluster exec`. Opening a shell writes an `open_pod_terminal` row to the [audit log](/guides/audit-log) naming who opened it, into which container, with which shell (or, for `exec`, the command it ran); while the session runs, everything typed and everything the container answered is stored with it, up to 4 MiB per session (longer sessions are marked truncated).

Anyone with `audit.read` can open the row in the organisation audit log or a cluster's **Audit** tab and see the session's facts - duration, how it ended, how much was recorded - and **replay** the recorded output into a read-only terminal, with the typed input listed beside it. From the CLI, `ankra org terminal-session <session-id> --transcript` prints the same recording.

> [!NOTE]
>
> A recording contains whatever the shell printed, secrets included. Transcript access is gated on `audit.read`; the transcript itself never travels inside the audit row.

If the recording store is unavailable when a session opens, the session still opens and the audit row says `recording_unavailable`; a session whose recording failed part-way through is marked as degraded.

Transcripts are kept for **90 days** by default, then pruned: the session's facts - who, where, when, how it ended, how much was recorded - stay with the audit row, and the replay says the transcript was pruned and when, rather than showing an empty recording.

***

## No shell in the image?

A distroless image has nothing to attach to. Spin up a [debug pod](/platform/debug-pods) instead: a pod that impersonates this one - same service account, node, volumes and environment - under an image that has the tools you need.

***

## Requirements

* The **cluster agent** must be running and connected (cluster state: online).
* The **pod must be in a running state**. Terminal is not available for deleted or terminated pods.
* The selected shell must be available inside the container image.

***

## Troubleshooting

| Issue | Solution |
| - | - |
| "Connection error" on connect | Verify the cluster agent is online and the pod is still running |
| Shell exits immediately | The selected shell may not exist in the container. Try `/bin/sh` |
| Terminal appears blank | Resize the browser window or click **Reconnect** |
| Session ends unexpectedly | The pod may have been restarted or deleted. Check pod status |


# Portal URLs
Source: https://docs.ankra.ai/platform/portal-urls

How Ankra portal addresses are built, the URL for every main page, and how AI clients, the CLI and notifications link you straight to the right screen.

Everything the Ankra CLI, API and MCP tools change is also visible in the portal at [platform.ankra.app](https://platform.ankra.app). Every portal page has a stable address, so you can bookmark it, paste it into a ticket, or have an AI client hand it to you. This page explains how those addresses are built and lists the main ones.

## How addresses are built

* **The organisation comes from your session.** Most pages live under `/organisation/...` and show the organisation you have selected in the top-left switcher. Only the organisation admin pages (members, service tokens and organisation settings) put the organisation id in the path.
* **`?org=` opens a link in the right organisation.** Links from Ankra (notifications, AI answers, MCP results) add `?org=<organisation-id>`. If that is not your current organisation, the portal offers to switch to it instead of showing "Resource not found".
* **`?project=` names the [project](/concepts/projects) beside it.** The same links add `?project=<project-id>`, so a link to a cluster in another project opens in that project rather than in the one you last worked in. If that is not your current project, the portal offers to switch to it. `ankra` commands that print a portal link add it too.
* **Clusters are addressed by id, not by name.** Every cluster page starts with `/organisation/clusters/cluster/imported/<cluster-id>/`. The `imported` segment is used for every cluster, including ones Ankra built. `ankra cluster info -o json`, `ankra cluster list -o json` and the `list_clusters` MCP tool all return the id.
* **Stacks and add-ons are addressed by name** within their cluster. Kubernetes workloads are addressed by namespace and name.

> [!TIP]
>
> You rarely need to build these URLs yourself. `ankra` CLI commands that create a cluster print a **View it in the UI** link, and MCP clients can call [`get_portal_url`](#links-from-ai-and-mcp-clients).

## Organisation pages

| Page | Path |
| - | - |
| [Dashboard](/platform/dashboard) | `/organisation/dashboard` |
| [Activity inbox](/platform/activity-inbox) | `/organisation/activity` |
| Clusters | `/organisation/clusters` |
| Create or import a cluster | `/organisation/clusters/create` |
| Applications | `/organisation/applications` |
| [Stack profiles](/concepts/stack-profiles) | `/organisation/stack-profiles` |
| Add-on catalogue | `/organisation/add-ons` |
| [Credentials](/platform/credentials) | `/organisation/credentials` |
| Your API tokens (CLI and MCP) | `/organisation/profile/api` |
| [Cloud cost](/platform/cloud-cost) | `/organisation/cost` |
| Security Center | `/organisation/security` |
| Security findings | `/organisation/security/findings` |
| One CVE | `/organisation/security/advisories/<cve-id>` |
| Members | `/organisation/<organisation-id>/members` |
| Service tokens | `/organisation/<organisation-id>/service-tokens` |
| [Organisation settings](/platform/organisation-settings) | `/organisation/<organisation-id>/settings/general` |
| DNS and domains | `/organisation/<organisation-id>/settings/dns` |
| Backup vaults | `/organisation/<organisation-id>/settings/backups` |

## Cluster pages

Every path below starts with `/organisation/clusters/cluster/imported/<cluster-id>`.

| Page | Path suffix |
| - | - |
| Overview | `/overview` |
| Stacks | `/stacks` |
| One stack (builder) | `/stacks/<stack-name>/edit` |
| Add-ons | `/add-ons` |
| One add-on | `/add-ons/add-on/<addon-name>` |
| Managed resources | `/resources` |
| [Operations](/platform/operations) | `/operations` |
| One operation | `/operations/<operation-id>/kanban` |
| Nodes and machines | `/nodes` |
| Node groups | `/nodes/groups` |
| One Kubernetes node | `/kubernetes/nodes/<node-name>` |
| Namespaces | `/kubernetes/namespaces` |
| Pods | `/kubernetes/workloads/pods` |
| One pod | `/kubernetes/workloads/pods/<namespace>/<pod-name>` |
| Pod terminal | `/kubernetes/workloads/pods/<namespace>/<pod-name>?activeTab=terminal` |
| One Deployment | `/kubernetes/workloads/deployments/<namespace>/<name>` |
| One StatefulSet | `/kubernetes/workloads/stateful-sets/<namespace>/<name>` |
| One DaemonSet | `/kubernetes/workloads/daemon-sets/<namespace>/<name>` |
| One Job / CronJob | `/kubernetes/workloads/jobs/<namespace>/<name>`, `/kubernetes/workloads/cron-jobs/<namespace>/<name>` |
| Events | `/kubernetes/events` |
| Logs | `/kubernetes/logs` |
| [Metrics](/platform/cluster-metrics) | `/metrics` |
| Security | `/security` |
| Backups | `/backups` |
| [Settings](/platform/cluster-settings) | `/settings/general` |

An operation whose cluster you do not know opens at `/organisation/operations/<operation-id>`.

## Applications and pipelines

| Page | Path |
| - | - |
| One application | `/organisation/applications/<application-id>` |
| Its pipeline runs | `/organisation/applications/<application-id>/pipelines` |
| Where it is deployed | `/organisation/applications/<application-id>/deployments` |
| Pull request previews | `/organisation/applications/<application-id>/previews` |
| Environment secrets | `/organisation/applications/<application-id>/environment` |
| One pipeline run | `/organisation/pipelines/<repository-id>/runs/<run-id>` |
| One stack profile | `/organisation/stack-profiles/<profile-id>` |

## AI

| Page | Path |
| - | - |
| [Chat](/platform/ai-assistant) | `/organisation/ai/chat` (one conversation: `?conversation=<conversation-id>`) |
| [AI board](/platform/ai-board) | `/organisation/ai/board` |
| One ticket | `/organisation/ai/board/<ticket-id>` |
| [Agents](/platform/ai-agents) | `/organisation/ai/agents` |
| One agent run | `/organisation/ai/agents/runs/<run-id>` |
| Actions waiting for approval | `/organisation/ai/inbox` |
| Alerts | `/organisation/ai/alerts` |
| One alert rule | `/organisation/ai/alerts/<alert-id>` |

## Links from AI and MCP clients

The [Ankra MCP server](/platform/mcp-server) tells every connected client to give you a portal link when it reports on a resource, finishes a change, or asks you to review or approve something in the UI.

* `list_clusters` and `get_cluster_details` return each cluster's `portal_url` (its overview page).
* `get_portal_url` returns the link for any page on this list. It takes a `page` (for example `cluster_overview`, `addon`, `pod`, `application`, `pipeline_run`, `ticket` or `cve`) and the ids that page needs, and it reads and changes nothing, so an `mcp:read` token can call it.

```json theme={null}
{
  "name": "get_portal_url",
  "arguments": { "page": "addon", "cluster_id": "5d1f3a52-7e0b-4f3c-9b8f-0f6d3c2a1b4e", "addon_name": "cert-manager" }
}
```

```json theme={null}
{
  "page": "addon",
  "url": "https://platform.ankra.app/organisation/clusters/cluster/imported/5d1f3a52-7e0b-4f3c-9b8f-0f6d3c2a1b4e/add-ons/add-on/cert-manager?org=<organisation-id>",
  "description": "One add-on: status, values, the resources it created and its history."
}
```

If you write your own agent instructions, ask the agent to use these returned URLs rather than composing portal paths from memory.

## Links from the CLI and notifications

* Cluster creation and `ankra cluster apply` print **View it in the UI:** with the cluster's overview URL.
* `ankra cluster debug` prints a link to the debug pod's terminal.
* Slack, Microsoft Teams, email and webhook notifications link to the alert firing, ticket, pipeline run or cluster page they are about, and carry the organisation the page belongs to.

## Related

> [card] [MCP Server](/platform/mcp-server)
>
> Connect Cursor, Claude and other MCP clients to Ankra.

> [card] [MCP Tools](/platform/mcp-tools)
>
> Every tool the MCP server exposes.

> [card] [Command Palette](/platform/command-palette)
>
> Jump to any page with ⌘K.

> [card] [Dashboard](/platform/dashboard)
>
> The organisation landing page.


# Support
Source: https://docs.ankra.ai/platform/support

Raise and track support tickets from inside Ankra, with AI triage that enriches, deduplicates, and routes each request.

When something in Ankra is broken or unclear, you want to reach the Ankra team without leaving the portal and without re-typing which cluster you mean. Support tickets are raised from inside Ankra, tied to the cluster they concern, and checked by an AI review before they are filed so the team has what it needs from the first message.

## Where to open a ticket

* **Portal** - open your profile menu in the sidebar and select **Support**. The Support panel lists your tickets; **New support request** starts one.
* **Command palette** - press `⌘ K` / `Ctrl K` and run **Create Support Ticket**. See [Command Palette](/platform/command-palette).
* **CLI** - `ankra support create`, below.
* **AI Assistant** - ask it to raise a ticket, below.

***

## Raising a ticket

**1. Describe the problem**

Give the ticket a subject and description, pick a category, and optionally link the cluster it relates to. Context about the selected cluster is attached automatically.

**2. AI review**

Before the ticket is filed, Ankra runs an AI review that enriches it - suggesting a summary, severity, and category - checks quality, may ask clarifying questions, and surfaces likely duplicates of existing tickets.

**3. Submit**

Accept the review (or answer its clarifying questions) and submit. If a strong duplicate is found, you can link to the existing ticket instead of opening a new one.

**4. Track and reply**

Follow status changes, read replies from the Ankra team, and add your own comments and attachments as the conversation continues.

***

## Categories

| Category | Use for |
| - | - |
| `technical` | How-to questions and technical problems |
| `bug` | Something is broken or behaving incorrectly |
| `feature_request` | A capability you'd like to see |
| `account` | Access, organisation, and user issues |
| `billing` | Invoices, plans, and payment |
| `other` | Anything that doesn't fit above |

Severity (`low`, `medium`, `high`, `critical`) is suggested by the AI review and can be adjusted. These are the severities the [SLA](https://ankra.ai/sla) sets response times for; `medium` is the SLA's Normal.

***

## Ticket lifecycle

A ticket moves through these statuses:

| Status | Meaning |
| - | - |
| `pending_review` | Created and undergoing AI review |
| `open` | Filed and awaiting triage |
| `triaging` | Being assessed by the Ankra team |
| `in_progress` | Actively being worked on |
| `waiting_customer` | Waiting on a reply from you |
| `resolved` | A resolution has been provided |
| `closed` | Closed |

Each ticket records its `source` (`portal`, `api`, `cli`, or `agent`), an AI summary, the AI review status, comments (from you, the Ankra team, AI, or the system), and any attachments.

***

## Attachments

Attach logs, manifests, or screenshots to give the team what they need. Attachments are validated by type and size, and there is a per-ticket limit. Download an attachment again from the ticket at any time.

***

## From Ankra AI and the MCP server

The assistant and the [MCP server](/platform/mcp-server) work the same tickets. Ask Ankra AI to "raise a support ticket about the ingress 502s" and it proposes a **Raise support ticket** action naming the subject, category, severity and cluster; confirm, and the ticket is filed with source `agent`, tied to the cluster you were chatting about. It can also list your tickets, read one by its number, reply on your behalf, and close one you consider resolved. The tools are `list_support_tickets`, `get_support_ticket`, `create_support_ticket`, `comment_support_ticket` and `close_support_ticket` - see the [MCP Tool Reference](/platform/mcp-tools#support-tickets). Attachments stay in the portal and the CLI.

***

## From the CLI

```bash theme={null}
# Raise a ticket about a cluster
ankra support create \
  --subject "Ingress returns 502 after upgrade" \
  --description "Since the add-on upgrade this morning every request through the ingress returns 502." \
  --category technical \
  --cluster my-cluster

# Follow it
ankra support list
ankra support get <ticket-id>
ankra support comment <ticket-id> -m "Logs attached."
ankra support attach <ticket-id> ./screenshot.png
ankra support close <ticket-id>
```

`create` runs the same AI review as the portal and asks you to confirm when it flags the ticket or finds a likely duplicate; `--force` skips that prompt. See [`ankra support`](/reference/cli/support) for every flag.


# Usage
Source: https://docs.ankra.ai/platform/usage

See what your organisation used of Ankra - worker vCPU-hours, playgrounds, managed services, hosted logs and metrics, and AI - per period, how completely each was measured, and what it costs.

Ankra records what your organisation uses of every metered part of the platform in one usage report: worker vCPU-hours, playgrounds, managed services, Ankra hosted logs and metrics, and AI. You can read it per month or per day, and split it by cluster, by application or by managed service.

Usage is tracked now and charged later. Managed services and Ankra hosted logs and metrics are **included during the pilot**: Ankra publishes no rate for them and charges nothing. Ankra charges for a meter only once it publishes a rate for it (Terms of Service clause 8.8). Worker vCPU and playgrounds are billed as [Billing & Usage](/platform/billing) describes, and the report shows what that billing makes of them.

***

## What is measured

| Meter | Unit | What it counts | Price |
| - | - | - | - |
| `worker_vcpu_hours` | vCPU-hours | Each hour, a cluster's worker vCPUs as last measured that hour | Your [plan's rate](/platform/billing#how-billing-is-calculated) |
| `playground_seconds` | seconds | Time an ordered [playground](/guides/cluster-sandbox) was usable | Its monthly price, pro-rated |
| `service_instance_seconds` | seconds | Time a [managed service](/concepts/managed-services) was deployed, from its deployment until it was deleted, while Ankra could see its cluster | Included during the pilot |
| `service_storage_byte_hours` | byte-hours | Storage requested by the bound volume claims in a managed service's namespace, held over time | Included during the pilot |
| `hosted_logs_ingested_bytes` | bytes | Log bytes [Ankra hosted logs](/guides/hosted-logs) accepted | Included during the pilot |
| `hosted_logs_ingested_lines` | lines | Log lines Ankra hosted logs accepted | Included during the pilot |
| `hosted_metrics_samples` | samples | Samples Ankra hosted metrics accepted | Included during the pilot |
| `hosted_metrics_active_series` | series-hours | Each hour, the distinct series a cluster had | Included during the pilot |
| `ai_requests` | requests | AI model requests, on Ankra's key or your own | No per-unit rate: see [Models and Cost](/platform/ai-provider#usage-and-the-free-allowance) |
| `ai_input_tokens`, `ai_output_tokens` | tokens | The tokens those requests sent and received | No per-unit rate |

A level measured each hour (vCPUs, active series, bytes of storage) adds up to unit-hours over a period: 10 GB held for a day is 240 GB-hours.

***

## Read your usage

### In the portal

* **Billing and limits** has a **Usage** section with every meter for this month and last. Switch between **Meter**, **Cluster**, **Application** and **Service** to split it by what used it.
* A managed service's page has a **Usage** card showing how long it ran this month and the storage it held.
* An application's **Services** card has a **Usage this month** band, one row per service it uses, with a link to the full usage split by application.

The portal reads the same report as the CLI and the API, so a line reads the same everywhere: **Not measured**, **At least**, and the price wording below.

### With the CLI

```bash theme={null}
ankra org usage
```

With no options, this reads the current month so far, one line per meter. The table shows quantities in units a person reads (GB, hours, thousands separators) and a legend for every marker it uses.

| Option | What it does |
| - | - |
| `--period this-month` or `last-month` | A ready-made window |
| `--from <YYYY-MM-DD>` and `--to <YYYY-MM-DD>` | Any window: the first day, and the day after the last one |
| `--granularity day` | One line per day instead of per calendar month |
| `--group-by cluster`, `application` or `instance` | Split each meter by what used it: see [Split it by what used it](#split-it-by-what-used-it) |
| `--group-by project` | Split the organisation's worker vCPU-hours over the window by [project](/concepts/projects), with the hours no project could claim. This is the [showback](/platform/billing#showback-by-project): billing stays one invoice |
| `-o json` or `-o yaml` | The report as the API answers it: raw quantities with their unit, and `null` where nothing was measured |

```bash theme={null}
ankra org usage --period last-month
ankra org usage --from 2026-09-01 --to 2026-10-01 --granularity day
ankra org usage --group-by application
ankra org usage --group-by instance -o json
```

```bash theme={null}
ankra org usage --group-by project --period last-month
```

### With the API

The same report is served at `/api/v1/org/billing/usage`, with the window and grouping as query parameters:

```bash theme={null}
curl -H "Authorization: Bearer <your-token>" \
  "https://platform.ankra.app/api/v1/org/billing/usage?from=2026-09-01&to=2026-10-01&group_by=cluster"
```

Two narrower reads take the same `from`, `to` and `granularity` parameters and answer one line per managed service and period: `/api/v1/org/service-admission/instances/{instance_id}/usage` for one service, and `/api/v1/org/service-admission/applications/{application_id}/usage` for the services one application uses.

A parameter the platform refuses answers `422`, naming the parameter.

### With the AI Assistant

The [AI Assistant](/platform/ai-assistant) reads the same report. Ask it, for example: *Which managed services used the most storage last month?*

***

## The window

* **Days are UTC.** `from` is the first day read and `to` is the day after the last one, so `--from 2026-09-01 --to 2026-10-01` reads all of September.
* **The default is this month so far**: from the first day of the current month to now.
* **At most 93 days per read.** Read a longer stretch in parts. Usage is kept for 400 days.
* **Periods are calendar months or UTC days**, cut to the window at either end.
* **The current period ends now.** Usage that has not happened is not reported, and the last hours of the current period are usually still being counted.

***

## How a line reads

Each line is one meter, over one period, for one group. It carries its quantity, how completely that quantity was measured, and what it costs.

### Coverage

| Coverage | Meaning | In the CLI |
| - | - | - |
| `complete` | Every hour of the period was measured (every day, for AI usage). The quantity is exact. | The quantity |
| `partial` | Some hours were not measured, or are still being counted. The quantity is a lower bound. | `>=` before the quantity |
| `unknown` | No hour was measured: for example, a managed service whose cluster was offline throughout. The quantity is `null`. | `not measured` |

Unknown is not zero. A period nobody measured is reported as unknown, never as 0, so a missing measurement never looks like nothing was used.

### Price

| Price state | Meaning | In the CLI |
| - | - | - |
| `included` | Ankra publishes no rate for this meter and charges nothing for it during the pilot. | `included (pilot)` |
| `priced` | A published rate applies. `amount_minor` is what it makes the quantity cost, in euro cents, as the invoice applies it. | The amount in EUR |
| `unpriced` | No rate applies to the line as it is. `price_basis` says why. | The reason |

`price_basis` says what the price state rests on:

| `price_basis` | Meaning | In the CLI |
| - | - | - |
| `pilot` | Included during the managed services pilot | `included (pilot)` |
| `plan_rate` | Your plan's per-vCPU-hour rate, after its free allowance and annual discount | The amount |
| `price_of_record` | A playground's monthly price recorded when it was ordered, pro-rated over the calendar month | The amount |
| `flat_fee` | Your plan bills a flat monthly fee that covers vCPU usage | `covered by the plan's flat fee` |
| `not_invoiced` | Your plan is not invoiced | `plan not invoiced` |
| `no_rate` | No per-unit rate is published, as for AI usage | `no rate published` |
| `organisation_total` | Split by cluster: your plan rates the organisation's vCPU total each hour, so one cluster's share has no price of its own | `priced on the organisation total` |
| `other_currency` | The playground's recorded price is not in euros | `price not in EUR` |

***

## Split it by what used it

| Grouping | One line per meter and period for | Meters that stay one organisation line |
| - | - | - |
| `meter` (default) | The whole organisation | - |
| `cluster` | Each cluster | AI usage |
| `application` | Each application a managed service serves | Every meter except the two managed service meters |
| `instance` | Each managed service | Every meter except the two managed service meters |

Grouped by meter, every meter has a line for every period, even when nothing was used. Grouped any other way, a group that used none of a meter in a period that was fully measured has no line.

Grouped by application, a service counts toward the applications whose reviewed setup plan names them as consumers. A service that several applications use is counted in full under each of them and marked shared (`is_shared`), so **application lines do not add up to the organisation's total**. A service that no application uses has a line with no application. The CLI shows the application's name, and the same note under its table.

Names are shown as they read now. Two groups with the same name, such as several playground clusters named `playground`, are told apart in the CLI by the start of their id.

***

## Who can read it

Reading usage needs the `billing.read` permission, which every built-in role holds. The read for one managed service also needs access to that service, and the read for one application needs `applications.read`. See [Roles and access](/guides/roles-and-access).

***

## Related

> [card] [Billing & Usage](/platform/billing)
>
> Plans, the vCPU allowance, invoices and playground prices.

> [card] [Managed services](/concepts/managed-services)
>
> The services whose instance time and storage are metered.

> [card] [Ankra hosted logs](/guides/hosted-logs)
>
> Turn on hosted logs for a cluster, and what it keeps.

> [card] [Models and Cost](/platform/ai-provider)
>
> The AI allowance and the daily AI spend cap.


# User Profile
Source: https://docs.ankra.ai/platform/user-profile

Your personal settings - account and connected identities, sign-in security, theme, notifications and API tokens.

Some settings belong to you rather than to an organisation: where Ankra emails you, how you sign in, whether the portal is dark or light, how you are notified, and the tokens your scripts and editor use. They live in your profile and follow you across every organisation you belong to.

Open the profile menu in the sidebar and select **Profile**. The profile sidebar has five tabs.

## General

* **Account** - your name, email and picture, taken from your sign-in provider. Change them there.
* **Contact email** - where Ankra sends account, invitation and notification emails, if that should differ from your sign-in address (for example when you sign in with an Apple private relay address).
* **GitHub Connection** and **Bitbucket Cloud Connection** - link your own GitHub or Bitbucket identity so commits Ankra pushes on your behalf are attributed to you.
* **AI Assistant** - personal AI preferences (tips, auto-approved actions, model and interaction mode) are set in the AI chat panel: **Open AI chat**, then the settings (gear) icon. See [AI Assistant](/platform/ai-assistant).
* **Delete account** - permanently deletes your account and personal data.

## Authentication

Two-factor authentication: authenticator apps, passkeys and recovery codes. See [Account Security & 2FA](/platform/account-security).

## Appearance

Choose **Light**, **Dark** or **System** (follow your operating system). The choice is saved to your account. The profile menu also has a one-click toggle that cycles through the three modes.

## Notifications

* **Email Subscriptions** - choose which emails you receive from Ankra: product updates, platform announcements, and scheduled maintenance and incident notices.
* **Chat completion notifications** - get a Slack or Microsoft Teams message when an AI chat task finishes. The Slack or Teams connection itself is set up in your organisation's Integrations settings.
* **Push notifications** - the mobile devices your notifications are pushed to. Send a test notification or remove a device.

Which alerts go where for the whole organisation is configured separately, in [Notification routing](/guides/notification-routing).

## API Tokens

Create and revoke personal API tokens for the [CLI](/integrations/ankra-cli), scripts and the [MCP server](/platform/mcp-server). **Create** asks for a name and, optionally, MCP access; the token is shown once, so copy it before closing the dialog. The page also gives ready-made MCP set-up for Claude Code and Cursor. See [API tokens](/reference/tokens) for scopes.

## Next step

Create an API token and [log in with the CLI](/integrations/ankra-cli), or use the [command palette](/platform/command-palette) and [keyboard shortcuts](/platform/keyboard-shortcuts) to move around faster.


# Agent Helm Values
Source: https://docs.ankra.ai/reference/agent-helm-values

Every configurable value of the ankra-agent Helm chart - workers, watch tuning, security contexts, metrics, and public IP reporting.

Reference for the `ankra-agent` chart installed from `oci://registry.ankra.cloud/ankra/ankra-agent`. For installation and architecture, see [Cluster Agent](/concepts/cluster-agent).

```bash theme={null}
helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --version <agent-version> \
  --set config.ankra_url=https://platform.ankra.app \
  --set config.token=<your-token> \
  --namespace=ankra --create-namespace
```

Copy the exact install command from the Import dialog: it pins the agent version and carries your cluster's token. Add `--set` flags for the values below to that command.

## Connection

| Value | Default | Description |
| - | - | - |
| `config.ankra_url` | `https://platform.ankra.app` | Platform endpoint the agent connects to |
| `config.token` | `""` | Agent token from the import flow (required unless using an existing secret) |
| `config.existing_secret_name` | `""` | Read the token from an existing Kubernetes Secret instead |
| `config.secret_key` | `""` | Key within that Secret holding the token |

## Workers and Performance

| Value | Default | Description |
| - | - | - |
| `read_worker_count` | `5` | Concurrent worker slots for read jobs |
| `write_worker_count` | `5` | Concurrent worker slots for write jobs (create, update, delete) |
| `nats_worker_max_workers` | `15` | Maximum NATS worker threads for processing commands |
| `resources.requests.cpu` | `200m` | CPU request |
| `resources.requests.memory` | `256Mi` | Memory request |
| `resources.limits.memory` | `1Gi` | Memory limit |
| `replica_count` | `1` | Agent replicas |
| `terminationGracePeriodSeconds` | `600` | Grace period so in-flight work can finish - don't set this low |
| `ci_worker_count` | `0` | Concurrent worker slots for [Ankra Pipelines](/guides/ankra-pipelines) steps. Zero - the default - means the agent runs no pipeline-step scheduler and does not advertise the capability. **Set through Ankra, not here** (below) |
| `ci_storage_class` | `""` | StorageClass for pipeline cache volumes and for a workspace claim that names none; empty is the cluster default. **Set through Ankra, not here** (below) |

> [!WARNING]
>
> `ci_worker_count` and `ci_storage_class` are the two values Ankra owns on the agent's behalf. Set them per cluster through the platform - `PUT /api/v1/org/clusters/{cluster_id}/agent/ci-settings`, or the CLI verb [Ankra Pipelines](/guides/ankra-pipelines#connect-a-repository-push-see-the-run) shows - and Ankra re-renders the agent's own release with them. A value you pass to `helm upgrade` yourself is overwritten the next time Ankra renders that release.

## Kubernetes Watch

Streaming of live resource state to the platform. Only override when you need to tune event volume.

| Value | Default | Description |
| - | - | - |
| `k8s_watch.enabled` | `true` | Enable the resource watch stream |
| `k8s_watch.batch_size` | `20` | Events per batch |
| `k8s_watch.batch_timeout_ms` | `500` | Max wait before flushing a partial batch |
| `k8s_watch.reconnect_delay_ms` | `1000` | Initial reconnect delay |
| `k8s_watch.max_reconnect_delay_ms` | `30000` | Reconnect backoff ceiling |
| `k8s_watch.max_events_per_sec` | `500` | Event rate limit |
| `k8s_watch.strip_fields` | `true` | Strip managed fields to reduce payload size |
| `k8s_watch.timeout_seconds` | `300` | Watch connection timeout |

## Public IP Reporting (Fleet World Map)

Places imported clusters on the [fleet dashboard map](/platform/dashboard) when they run in private networks. Disabled by default; enabling makes the agent perform an outbound HTTP lookup. Leave disabled for air-gapped clusters.

| Value | Default | Description |
| - | - | - |
| `public_ip.reporting_enabled` | `false` | Report the agent's public egress IP on check-in |
| `public_ip.lookup_url` | `https://api.ipify.org?format=json` | Endpoint returning the caller's public IP |
| `public_ip.refresh_seconds` | `3600` | How often the cached IP is refreshed |
| `public_ip.lookup_timeout_seconds` | `5` | Per-lookup HTTP timeout |

## Image

| Value | Default | Description |
| - | - | - |
| `image.repository` | `registry.ankra.cloud/ankra/agent` | Agent image |
| `image.tag` | `""` (follows chart version) | Explicit tag override - empty is the contract the platform auto-upgrade relies on; set only to pin a specific build |
| `image.pull_policy` | `Always` | Image pull policy |
| `image.pull_secrets` | `[]` | Pull secrets |

## Security

The chart enforces non-root defaults matching the image's `ankra` user (UID/GID 1000) with a read-only root filesystem. Don't lower these without a rebuilt image.

| Value | Default | Description |
| - | - | - |
| `pod_security_context` | non-root, UID/GID 1000, `RuntimeDefault` seccomp | Pod-level security context |
| `security_context` | non-root, no privilege escalation, read-only rootfs, all capabilities dropped | Container-level security context |
| `writable_volumes.enabled` | `true` | Mount emptyDir volumes for runtime-writable paths (required with read-only rootfs) |
| `writable_volumes.tmp_size_limit` | `1Gi` | `/tmp` size cap |
| `writable_volumes.cache_size_limit` | `4Gi` | Cache size cap |
| `writable_volumes.config_size_limit` | `16Mi` | Config size cap |

## Scheduling and Service

| Value | Default | Description |
| - | - | - |
| `node_selector` / `tolerations` / `affinity` / `topologySpreadConstraints` | empty | Standard scheduling controls |
| `service_account.name` | `ankra-agent-sa` | Service account name |
| `service_account.annotations` | `{}` | Service account annotations (e.g. IRSA) |
| `service.type` / `service.port` | `ClusterIP` / `8080` | Agent HTTP service |
| `pod_annotations` | `{}` | Extra pod annotations |
| `log_level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` |

## Metrics

| Value | Default | Description |
| - | - | - |
| `metrics.serviceMonitor.enabled` | `false` | Install a Prometheus Operator ServiceMonitor scraping `/metrics` |
| `metrics.serviceMonitor.interval` | `30s` | Scrape interval |
| `metrics.serviceMonitor.scrapeTimeout` | `10s` | Scrape timeout |
| `metrics.serviceMonitor.labels` | `{}` | Extra ServiceMonitor labels |
| `metrics_collect.enabled` | `true` | Ship built-in cluster metrics (nodes, namespaces, workloads) to the Ankra platform; `false` opts this cluster out of platform metrics |
| `metrics_collect.interval_seconds` | `30` | Collection interval |
| `metrics_collect.max_workloads` | `200` | Cap on per-workload series (top by CPU; restarting workloads are always kept) |

## Advanced Environment Tuning

Operator-tunable knobs go in `extra_env`:

```yaml theme={null}
extra_env:
  - name: KUBERNETES_HTTP2_ENABLED          # default "false"
    value: "false"
  - name: KUBERNETES_REQUEST_MAX_ATTEMPTS   # default "3"
    value: "3"
  - name: FORWARD_SERVICE_REQUEST_MAX_TIMEOUT_SECONDS  # default "120"
    value: "120"
```

See [Cluster Agent - Advanced tuning](/concepts/cluster-agent#advanced-tuning-via-extra_env) for when to change these.


# ankra.yaml reference
Source: https://docs.ankra.ai/reference/application-descriptor

Every key of .ankra/ankra.yaml, the application descriptor - metadata, the deploy options that drive the deploy form, the components block that declares a monorepo's deployable apps, and the health block the readiness gate reads.

`.ankra/ankra.yaml` is an [application's](/concepts/applications) descriptor. Ankra writes it into the setup pull request beside `.ankra/manifests/` and [`.ankra/pipeline.yaml`](/guides/pipeline-reference), and reads it back from the tracked branch on every analysis run, so what the file says in Git is what the application is:

* **`metadata`** describes the application, in the shape of a Helm `Chart.yaml`.
* **`options`** is the application's deploy-time contract: the inputs the deploy form asks for and the deploy endpoint validates.
* **`components`** (optional) declares the application's deployable components, for a repository whose layout Ankra cannot infer correctly on its own.
* **`health`** (optional) declares the application's liveness and readiness routes and a latency budget. The readiness gate, a platform setting, reads the readiness routes and the budget.

## Full example

The descriptor of a repository with a Go API at the root, built from `deploy/docker/Dockerfile`, and a web app in `web/`:

```yaml theme={null}
apiVersion: ankra.io/v1
kind: Application
metadata:
  name: "my-app"
  version: "0.1.0"
  app_version: "0.1.0"
  description: "API and web front end"
  home: "https://example.com"
  sources:
    - "https://github.com/my-org/my-app"
  keywords:
    - "go"
    - "nextjs"
  maintainers:
    - name: "my-org"
      url: "https://github.com/my-org"
options:
  - name: "image_tag"
    type: "string"
    required: false
    description: "Container image tag to deploy. Use an immutable tag such as sha-<commit> or a semver release, never 'latest'."
  - name: "replicas"
    type: "number"
    default: "1"
    required: false
    description: "Number of pod replicas."
components:
  - name: api
    subdir: ""
    dockerfile: deploy/docker/Dockerfile
    container_port: 8080
  - name: web
    subdir: web
    container_port: 3000
```

A generated descriptor lists all fourteen default options (below); the example shows two to stay short.

## Top-level keys

| Key | Type | Default | Meaning |
| - | - | - | - |
| `apiVersion` | string | required | `ankra.io/v1`. It is group-qualified so that nothing walking `.ankra/` can mistake the file for an ArgoCD `Application`. |
| `kind` | string | required | `Application` |
| `metadata` | block | required | See [Metadata](#metadata). `metadata.name` is required. |
| `options` | list | none | The deploy options - see [Options](#options) |
| `components` | list | none | The declared components - see [Components](#components) |
| `health` | block | none | The health routes and latency budget - see [Health](#health) |

Any other top-level key is ignored.

Keep the file at `.ankra/ankra.yaml`, outside `.ankra/manifests/`: the files in that directory are the manifests a deploy applies to the cluster.

### A file Ankra cannot read

A descriptor does not parse when it is empty or not valid YAML, has the wrong `apiVersion` or `kind`, has an `options` value that is not a list, has an option without a name or whose name uses anything but letters, digits and underscores, has an option whose `default` or `description` is not a single value, or has a value of the wrong type, such as a list where a string belongs. A refused `components` or `health` block does not stop the rest of the file parsing (see [A declaration Ankra cannot honour](#a-declaration-ankra-cannot-honour) and [Health](#health)).

Every analysis run reads the file from the tracked branch, and what the run could read decides the deploy options and the components:

| `.ankra/ankra.yaml` | Deploy options | Components |
| - | - | - |
| Not in the repository | The option set Ankra generates (see [Default options](#default-options)). The generated file goes into the setup pull request. | Decided by the other signals, in the order under [The declaration outranks inference](#the-declaration-outranks-inference). |
| In the repository, but this run could not fetch it | The option set Ankra generates, until a run reads the file. Nothing is generated or committed over the file, and the run reports the failed task `read_ankra_descriptor`. | The components the application already records. An application with none recorded has them decided by the other signals, as if the file were absent. |
| Fetched, but does not parse | The option set Ankra generates, until the file parses. Nothing is generated or committed over the file, and the run reports the failed task `read_ankra_descriptor`: `.ankra/ankra.yaml could not be parsed: <reason>; falling back to the default option set`. | The components the application already records. An application with none recorded has them decided by the other signals, as if the file were absent. |
| Parses | A non-empty `options` list. An empty or absent one keeps the option set Ankra generates (see [Options](#options)). | See [Components](#components). |

## Metadata

Every field except `name` is optional. Ankra fills them from the repository's GitHub metadata when it generates the file and leaves out the ones it could not read.

| Key | Type | Meaning |
| - | - | - |
| `name` | string | The application's name. Required. |
| `version` | string | The descriptor's version. Generated as `0.1.0`. |
| `app_version` | string | The version of the application it describes. Generated as `0.1.0`. |
| `description` | string | One line about the application. Generated from the repository description. |
| `license` | string | The licence identifier. |
| `home` | string | The project's home page. |
| `icon` | string | An image URL. Generated from the repository owner's avatar. |
| `sources` | list of strings | Source repository URLs. |
| `keywords` | list of strings | Generated from the repository topics. |
| `maintainers` | list | Each entry has `name`, `url` and `email`. |

When you [publish the application as an add-on](/platform/application-addons), the descriptor travels with the manifests into the add-on version.

## Options

`options` is the application's deploy contract. The deploy form renders one input per option, the deploy endpoint validates the values against it, and a manifest under `.ankra/manifests/` reads a value as `${{ ankra.<name> }}`.

| Key | Type | Meaning |
| - | - | - |
| `name` | string | Required. Letters, digits and underscores only, so the option can be referenced as `${{ ankra.<name> }}`. A name used twice keeps its first entry. |
| `type` | string | `string`, `number` or `boolean`. Any other value is read as `string`. |
| `default` | scalar | The default value. `default: 3` and `default: "3"` mean the same thing. Leave the key out for no default, which is different from an empty-string default. |
| `required` | boolean | Whether a deploy must supply a value. `"true"` as a string is read as `true`. |
| `description` | string | The help text the deploy form shows. |

A non-empty `options` list replaces the application's stored contract on the next analysis run, so editing the list in Git and running setup again changes the deploy form. An empty or absent list keeps the contract Ankra generated: there is no way to declare a deliberately empty contract.

### Default options

A generated descriptor declares these fourteen options. `target_port` defaults to the port the analysis detected.

| Option | Type | Default | Meaning |
| - | - | - | - |
| `image_tag` | string | none | Container image tag to deploy. Use an immutable tag such as `sha-<commit>` or a semver release, never `latest`. |
| `replicas` | number | `1` | Number of pod replicas. |
| `target_port` | number | detected | Container port the application listens on. |
| `cpu_request` | string | `100m` | CPU request per pod. |
| `cpu_limit` | string | `500m` | CPU limit per pod. |
| `memory_request` | string | `128Mi` | Memory request per pod. |
| `memory_limit` | string | `512Mi` | Memory limit per pod. |
| `ingress_enabled` | boolean | `false` | Expose the service through an Ingress. |
| `ingress_host` | string | `""` | Ingress hostname, required when the Ingress is enabled. |
| `ingress_class` | string | `""` | IngressClass name, for example `traefik`. Empty uses the cluster's default IngressClass. |
| `ingress_extra_hosts` | string | `""` | Comma-separated extra hostnames the Ingress also serves, each with its own rule and TLS host beside `ingress_host`. At most 5. |
| `redirect_hosts` | string | `""` | Comma-separated hostnames that permanently redirect to `ingress_host`, keeping the path and query, for example an old or misspelled domain. Each gets its own DNS record and certificate. At most 5. Needs the `traefik` ingress class. |
| `env_from_secrets` | string | `""` | Comma-separated names of Secrets in the application's namespace whose keys become environment variables. |
| `ingress_tls_issuer` | string | `letsencrypt-prod` | cert-manager ClusterIssuer that mints the Ingress certificate. Empty serves plain HTTP. Ankra checks the name against the target cluster at deploy time. |

An application with a detected database carries that database's sizing options as well.

## Components

`components` declares the application's deployable components. Without it, Ankra infers them from the repository (see [Monorepos](/concepts/applications#monorepos)). Inference cannot see every layout: a repository whose API builds from `deploy/docker/Dockerfile` at the root and whose web app sits in `web/` reads as one app, because detection needs two subdirectory Dockerfiles and ignores `deploy/`. The declaration is how such a repository states its components.

| Key | Type | Default | Meaning |
| - | - | - | - |
| `name` | string | required | The component's name. It names the component's image repository, `<repository>/<name>`, and its `build-<name>` pipeline stage, so it is lower-case letters and digits joined by hyphens or periods. |
| `subdir` | string | `""` | The component's build context, relative to the repository root. `""` is the root. Alias: `app_subdir`. |
| `dockerfile` | string | resolved from the tree | The repository path the component builds from. |
| `container_port` | number | the analysed port | The port the component listens on, 1 to 65535. Alias: `port`. |

`subdir` and `dockerfile` are both paths from the repository root, like `context` and `dockerfile` in a [pipeline build stage](/guides/pipeline-reference#where-a-builds-paths-are-resolved-from). Neither may be absolute or contain `..`.

### The declaration outranks inference

Ankra decides an application's components in this order, and the first signal that holds wins:

1. The `components` block of `.ankra/ankra.yaml`.
2. The per-component build workflows the repository already carries.
3. The apps the analysis proposed on this run.
4. The repository's structure.

So a declaration outranks the existing workflows, the AI proposal and structural detection. Two signals can leave a monorepo with fewer components than it records: a declaration, and two or more of Ankra's per-component build workflows for fewer components than the record (an application built by Ankra Pipelines has no per-component workflows). The AI proposal and structural detection cannot: when they find fewer components than a monorepo already records, Ankra keeps the recorded ones, because finding less is not evidence that a component is gone. To drop a component, declare the ones you keep.

When a run's components no longer include one the monorepo recorded before, because a signal dropped or renamed it, the run records the new set and reports the change as the failed task `record_components`, naming the components it dropped and the ones it now records. A pipeline stage, image repository or registry mapping key that names a dropped component builds nothing until it is renamed.

A declaration of one component at the repository root is a single-app application, and the component takes the repository's name.

### A declaration Ankra cannot honour

The block is validated on its own and is refused as a whole, never partly applied. Ankra refuses it when:

* `components` is not a list, or is an empty list (remove the key instead to let Ankra infer)
* an entry is not a mapping, has no `name`, or has a key other than `name`, `subdir`, `app_subdir`, `dockerfile`, `container_port` and `port`
* a name is not lower-case letters and digits joined by hyphens or periods
* two entries share a name, or build from the same `subdir`
* an entry sets both `subdir` and `app_subdir`, or both `container_port` and `port`, to different values (the same value in both is accepted)
* `subdir`, `app_subdir` or `dockerfile` is not a single path, such as a list or a mapping
* a path is absolute or leaves the repository with `..`
* a port is not a number from 1 to 65535

Ankra reports the first problem it finds, so a block with several problems shows the next one once the first is fixed.

A refused declaration is reported as the failed setup task `read_declared_components`, with the reason, in the application's jobs. When the application already records components, the run keeps them rather than inferring new ones over a declaration it could not read; an application with none recorded has its components decided by the other signals, as if the block were absent. The deploy options are still read from the same file. Fix the block and reconcile the application. A successful read reports the same task as `Using the 2 component(s) declared in .ankra/ankra.yaml: api, web`.

A declared `dockerfile` that the repository does not contain is reported rather than built, and Ankra does not generate a Dockerfile over it.

When Ankra rewrites the descriptor, for example to change the generated options, it copies your `components` and `health` blocks back exactly as you wrote them, refused or not.

### Declared components and the pipeline

Each declared component gets its own build in `.ankra/pipeline.yaml`, attributed by its `build-<component>` stage name or by [`build.component`](/guides/ankra-pipelines#which-component-a-build-belongs-to). `ankra pipeline validate` reports two `kind: build` stages that publish to the same repository as a fatal `pipeline_build_component:` finding when both always run, because each run's commit tag would be overwritten by whichever stage publishes last. When at least one of them runs only under a condition (`if`, `when` or `matrix`, or an `on_failure` or `finally` stage), the finding is a warning. See [Validation](/guides/pipeline-reference#validation).

## Health

`health` declares the application's liveness and readiness routes and a latency budget. The readiness gate, a platform setting, reads the readiness routes and the budget; liveness routes are kept on the application's contract.

```yaml theme={null}
health:
  liveness:
    - /health
  readiness:
    - /health/db
    - /health/s3
  latency_budget_ms: 1000
```

| Key | Type | Default | Meaning |
| - | - | - | - |
| `liveness` | list of paths | none | Routes that say the process is up. |
| `readiness` | list of paths | none | Routes that each say one dependency is reachable. |
| `latency_budget_ms` | number | no budget | How long, in milliseconds, any readiness route the gate probes may take to answer, from 1 to 5000. The same budget applies to every check the gate makes for the deployment, the asset checks of a single-page application included. |

Ankra adds the declared routes to the health routes it finds in the source and treats each as the kind its list names, whatever the path looks like. A path listed twice in one list counts once.

Where the readiness gate is switched off, nothing is probed. Ankra validates the block either way.

### A health block Ankra cannot honour

The block is validated on its own and is refused as a whole, never partly applied. Ankra refuses it when:

* `health` is empty, is not a mapping, or declares no route and no budget
* `liveness` or `readiness` is not a list, or one of its entries is not a path
* a path is empty, does not start with a single `/` (a relative path or a URL), contains whitespace, or contains any of `{ } [ ] * : < >`, the marks of a template rather than a single path
* one path is in both `liveness` and `readiness`
* `latency_budget_ms` is not a whole number of milliseconds, is zero or less, or is over 5000

Ankra reports the first problem it finds. Keys other than `liveness`, `readiness` and `latency_budget_ms` inside the block are ignored.

A refused block declares nothing: the health routes Ankra finds in the source stand, and the deploy options and components are still read from the same file. The refusal is reported as a `descriptor_health:` finding when Ankra validates the file before a commit of its own (see [Validation](#validation)); an analysis run does not report it.

## Validation

Before Ankra commits a descriptor itself, in the setup pull request or in a commit or pull request Ankra's AI makes, it validates the file and refuses the commit on a problem. Every problem is fatal, and only the first one found is reported, under one of these keys:

| Key | Reported for |
| - | - |
| `descriptor_parse:` | An empty file, invalid YAML, a value of the wrong type, an option whose `default` or `description` is not a single value, a missing `metadata.name` |
| `descriptor_kind:` | The wrong `apiVersion` or `kind` |
| `descriptor_options:` | An `options` value that is not a list, an option without a name, an option name that uses anything but letters, digits and underscores |
| `descriptor_components:` | A refused `components` block - see [A declaration Ankra cannot honour](#a-declaration-ankra-cannot-honour) |
| `descriptor_health:` | A refused `health` block - see [A health block Ankra cannot honour](#a-health-block-ankra-cannot-honour) |

The same validation applies to a file directly under `.ankra/` whose name ends in `-ankra.yaml`, such as `.ankra/web-ankra.yaml`, the per-component descriptor of a multi-app setup. An analysis run reads only `.ankra/ankra.yaml`.

## Related

> [card] [Applications](/concepts/applications)
>
> How Ankra analyses a repository, generates its packaging and deploys it.

> [card] [pipeline.yaml reference](/guides/pipeline-reference)
>
> Every key of the pipeline definition that sits beside the descriptor.


# AWS Reference
Source: https://docs.ankra.ai/reference/aws

Request fields, defaults, catalogs, limits, egress modes, tags, and API endpoints for self-managed Ankra clusters on AWS EC2.

Reference material for [AWS clusters](/guides/aws-clusters) - self-managed kubeadm or k3s clusters on EC2. Amazon EKS is covered by the [managed Kubernetes reference](/reference/managed-kubernetes).

***

## Cluster Configuration Options

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name. Also the suffix of the IAM role names (`ankra-k3s-<name>-cp`, `-node`), truncated to 64 characters |
| `credential_id` | *required* | AWS credential ID: a keys credential, or a role onboarded with the `provisioning` scope (the one write role for EKS and self-managed clusters) or the EC2-only `self_managed` scope. A `cost` role is refused, and so is a provisioning role whose stack predates the self-managed statements - see [AWS Credentials](/platform/credentials/aws#provisioning) |
| `ssh_key_credential_id` | *required* | SSH key credential ID. The public key is imported as the cluster's EC2 key pair |
| `region` | *required* | AWS region, e.g. `eu-north-1` |
| `vpc_id` | | Omitted (or empty): Ankra creates the VPC (`network_ownership: created`). Given: an existing VPC to adopt, never modified; `node_subnet_ids` and `bastion_subnet_id` are then required and the created-network fields are refused |
| `network_ip_range` | `10.0.0.0/16` | Created VPC only. The IPv4 CIDR the VPC is created with, `/16` to `/20` as a network address; it must hold a private `/20` and a public `/24` per availability zone. Refused (`422`) alongside `vpc_id` |
| `availability_zones` | *chosen by preflight* | Created VPC only. The zones the VPC is laid out over, in the order the spread walks them (the bastion and first control plane land in the first). Each must exist and be available in the region; more than one needs `control_plane_count` of at least 3. Omitted: one zone when `control_plane_count` is below 3, three otherwise, from the region's available zones in name order, reported as `resolved_availability_zones` |
| `nat_gateway_single_zone` | `false` | Created VPC with `nat_gateway` egress only. `false` creates one NAT gateway (and Elastic IP) per zone; `true` creates one in the first zone that every private subnet routes through - cheaper, one egress failure domain. Refused (`422`) when `true` alongside `vpc_id` |
| `node_subnet_ids` | | Adopted VPC only. One or more private subnets for control plane and worker instances; their zones become the cluster's zone pool. Refused (`422`) without `vpc_id` |
| `bastion_subnet_id` | | Adopted VPC only. A public subnet (internet-gateway default route) for the bastion. Refused (`422`) without `vpc_id` |
| `egress_mode` | `nat_gateway` (created), *resolved by preflight* (adopted) | `nat_gateway` (created VPC only), `bastion_nat` (either), or `existing` (adopted VPC only) - see [Egress modes](#egress-modes) |
| `bastion_allowed_ips` | `["0.0.0.0/0"]` | CIDRs allowed to reach the bastion on SSH. The default opens it to everyone (key-only, password login off, sshd rate-limited on the host); name your own CIDRs to restrict it. Ankra's own egress addresses are always admitted so provisioning keeps working. Preflight reports the exposure as `bastion_ssh_exposure` |
| `description` | | Free-text description |
| `bastion_instance_type` | `t3.small` | Instance type for the bastion. Size it for bandwidth in `bastion_nat` mode |
| `control_plane_count` | `1` | Number of control plane nodes, 1 to 9. At least 3 when the cluster spans more than one availability zone (an adopted VPC's node subnets, or a created VPC's `availability_zones`); it also decides how many zones a created VPC defaults to (1 below 3, 3 otherwise) |
| `control_plane_type` | `t3.medium` | Instance type for control planes |
| `worker_count` | `1` | Number of worker nodes in the default pool (legacy, use `node_groups` instead) |
| `worker_type` | `t3.medium` | Instance type for the default pool (legacy, use `node_groups` instead) |
| `node_groups` | | Array of node group definitions (see [Node groups](#node-groups)) |
| `distribution` | `kubeadm` | Kubernetes distribution (`k3s` or `kubeadm`). Omitted, it follows the platform default, `kubeadm`, like every other self-managed provider; the portal wizard defaults to `kubeadm` too. kubeadm on AWS is Cilium only |
| `kubernetes_version` | *latest supported* | Kubernetes version (optional) |
| `etcd_topology` | `stacked` | kubeadm only. `stacked` (etcd on the control planes) or `external` (dedicated etcd instances) |
| `etcd_node_count` | `3` | kubeadm `external` topology only (3 or 5) |
| `etcd_type` | `t3.medium` | kubeadm `external` topology only. Instance type for the etcd instances |
| `cni` | `cilium` | CNI plugin, for both distributions (`cilium`, `calico`, `flannel`). kubeadm requires `cilium`. Only Cilium and Calico can enforce the [IMDS guard](#imds-guard): `flannel` is accepted with a preflight `warning` saying the guard cannot be enforced |
| `cni_features` | *all off* | Advanced CNI feature toggles, fixed at creation: `kube_proxy_replacement`, `hubble`, `wireguard_encryption` (Cilium), `ebpf_dataplane` (Calico) - see [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) |
| `k3s_disabled_components` | | k3s only. Built-in components to leave out |
| `ubuntu_series` | `24.04` | Ubuntu LTS series for every instance. The AMI is resolved per region at create time from Canonical's public SSM parameters; the [images catalog](#catalog-api) lists the series that resolve |
| `architecture` | `amd64` | CPU architecture of the AMI and the instance types offered. `arm64` is refused with a `422` naming the pending image-catalogue audit |
| `root_volume_gib` | `40` | Root volume size in GiB, 20 to 2000. Always an encrypted gp3 volume |
| `external_cloud_provider` | `true` | Must be `true` when present - the AWS cloud controller manager is mandatory |
| `retention_policy` | `retain` | What teardown does with the EBS volumes the CSI driver provisioned and the load balancers the cloud controller created: `retain` records and keeps them (the volumes forced or not), `delete` sweeps the ones tagged `ankra.cloud/managed=true` for this cluster - the volumes once you accept it (`accept_volume_data_loss`) |
| `gitops_repository`, `gitops_credential_name` | | Optional GitOps wiring at create |
| `gitops_branch` | `master` | Branch the GitOps repository is committed to |
| `include_networking` | `true` | Deploy Traefik (fronted by a Network Load Balancer), cert-manager and a Let's Encrypt ClusterIssuer |
| `include_dns` | `true` | Give the cluster a delegated subdomain on `ankra.cc` with external-dns wired |
| `environment`, `criticality` | | Optional classification, as on every cluster |

`POST /api/v1/clusters/aws` answers `{"cluster_id", "name", "kind": "aws", "state": "creating", "operation_id"}`; track the operation to see provisioning progress.

### Node groups

Each entry of `node_groups`:

| Field | Default | Description |
| - | - | - |
| `name` | *required* | Node group name |
| `instance_type` | *required* | EC2 instance type, e.g. `t3.large`, `m6i.xlarge` |
| `count` | `1` | Number of nodes (0 to 100) |
| `availability_zone` | | Pin every node of the group to one zone of the node subnets, e.g. `eu-north-1a`. Omitted, each node takes the zone with the fewest instances cluster-wide. Pin a group that runs zonal storage: an EBS volume cannot attach from another zone |
| `labels` | `{}` | Kubernetes node labels |
| `taints` | `[]` | Kubernetes node taints |
| `autoscaling` | *off* | `{"enabled": true, "min_count": n, "max_count": m}` - see [Cluster autoscaling](/guides/cluster-autoscaling) |

***

## Egress modes

Nodes never receive a public IP, so every private subnet must route `0.0.0.0/0` somewhere. Ankra never mixes modes on one cluster.

| Mode | Network | Node default route | What Ankra creates or changes | Cost | Refused when |
| - | - | - | - | - | - |
| `nat_gateway` | Created only (the default there) | An Ankra-created NAT gateway in the node's zone | One NAT gateway with its own Elastic IP per zone, or one in the first zone for all subnets with `nat_gateway_single_zone: true`; the private route tables point at them | About USD 32 per month per gateway plus per-GB data processing ([VPC pricing](https://aws.amazon.com/vpc/pricing/)) | Named on an adopted VPC |
| `bastion_nat` | Either | The bastion's network interface (source/destination check off) | Created VPC: the private route tables point at the bastion. Adopted VPC: one tagged route table with `0.0.0.0/0` to the bastion, associated with the node subnets; each subnet's previous association is recorded and restored at teardown | The bastion instance and its Elastic IP only - the cheapest option | Adopted VPC: any node subnet holds an instance Ankra did not create |
| `existing` | Adopted only | Your NAT gateway, NAT instance or transit path, already on the subnets' route table | Nothing | Your existing path | A node subnet has no `0.0.0.0/0` (or `::/0`) route to such a target; named on a created VPC |

Omitted, it resolves to `nat_gateway` for a created VPC. For an adopted VPC preflight resolves it: subnets with egress select `existing`; empty subnets without it select `bastion_nat`; subnets without egress that hold foreign instances are refused with a message naming them.

***

## What Ankra creates

Everything Ankra creates carries three tags, and the credential's write permissions are conditioned on them:

| Tag | Value |
| - | - |
| `ankra.cloud/cluster-id` | The Ankra cluster ID |
| `ankra.cloud/managed` | `true` |
| `kubernetes.io/cluster/<cluster-id>` | `owned` - the tag the AWS cloud controller manager and EBS CSI driver key on |

| Created | Name or scope | Notes |
| - | - | - |
| VPC | created network only | From `network_ip_range`, DNS support and DNS hostnames enabled |
| Internet gateway | created network only | Attached to the VPC; the public route table's `0.0.0.0/0` target |
| Subnets | created network only | Per availability zone, one private `/20` (nodes) and one public `/24` (bastion, NAT gateway) |
| Route tables | created network only | One public table, one private table per zone carrying that zone's egress route |
| NAT gateways + Elastic IPs | created network, `nat_gateway` mode only | One per zone, or one in the first zone with `nat_gateway_single_zone` |
| Security group (nodes) | in the VPC | All traffic within the group; SSH and Kubernetes API from the bastion group; load balancer health-check rules added by the cloud controller |
| Security group (bastion) | in the VPC | SSH from `bastion_allowed_ips`; in `bastion_nat` mode also all traffic from the VPC CIDR, because the nodes' default route targets the bastion and their forwarded packets arrive as ingress on it (not reachable from the internet: nothing outside the VPC can source a private address) |
| Key pair | `ankra-k3s-<cluster>` | Imported from the SSH key credential |
| Elastic IP | one per cluster | Attached to the bastion |
| Bastion instance | the first zone's public subnet, or `bastion_subnet_id` | IMDSv2 required, hop limit 1 |
| Control plane instances | the private subnets, or `node_subnet_ids` | No public IP; encrypted gp3 root volume; IMDSv2 required, hop limit 3 (the EBS CSI controller runs on the pod network, guarded by the [IMDS guard](#imds-guard)); provider ID `aws:///<zone>/<instance-id>`; node name = EC2 private DNS name |
| Worker instances | the private subnets, or `node_subnet_ids` | No public IP; encrypted gp3 root volume; IMDSv2 required, hop limit 1; provider ID `aws:///<zone>/<instance-id>`; node name = EC2 private DNS name |
| IMDS guard | in the AWS cloud-provider stack | Cluster-wide network policy denying pod egress to `169.254.169.254` except from the EBS CSI controller, rendered for Cilium and Calico; `imds_guard: unavailable` in the create result on flannel |
| IAM role + instance profile | `ankra-k3s-<cluster>-cp` | Control plane: cloud controller manager and EBS CSI controller |
| IAM role + instance profile | `ankra-k3s-<cluster>-node` | Workers: kubelet and EBS CSI node |
| Route table | adopted VPC, `bastion_nat` mode only | `0.0.0.0/0` to the bastion, associated with your node subnets |
| Load balancers, EBS volumes | created by the cloud controller and CSI driver on demand | Tagged with the cluster ID; EBS volumes kept or swept per `retention_policy`; load balancers likewise in an adopted VPC, but always deleted with a created VPC (they cannot outlive it) |

Teardown deletes everything in this table that carries the cluster's tags, the created network included (NAT gateways and their Elastic IPs, route tables, subnets, internet gateway, VPC), in reverse order. A stop keeps the network and its NAT gateways, which keep billing.

**In an adopted VPC, never created, modified or deleted:** your VPC, subnets, internet gateway, NAT gateways, DHCP options set, and any route table Ankra did not create. In `bastion_nat` mode the node subnets' association is moved to the Ankra route table and moved back at teardown; the route tables themselves are untouched.

### Network layout

```mermaid theme={null}
flowchart TB
    Internet((Internet))
    Platform[Ankra Platform]

    subgraph VPC [VPC - created by Ankra, or adopted and never modified]
        subgraph Public [Public subnets - one per zone]
            Bastion[Bastion<br/>Elastic IP + private IP]
        end
        subgraph Private [Private subnets - one per zone]
            CP[Control plane instances<br/>private IP only]
            Workers[Worker instances<br/>private IP only]
            Agent[Ankra Agent<br/>runs in the cluster]
        end
        IGW[Internet gateway]
        NAT[NAT gateway per zone - nat_gateway mode<br/>the bastion - bastion_nat mode<br/>your own path - existing mode]
    end

    NLB[Network Load Balancer<br/>created by the AWS cloud controller]

    Platform -->|SSH from allowed IPs only| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    Agent -->|outbound only - NATS| Platform
    CP -->|default route| NAT
    Workers -->|default route| NAT
    NAT --> IGW
    Bastion --> IGW
    IGW --> Internet
    Internet --> NLB
    NLB --> Workers
```

### Cloud integration

* **Cloud controller manager.** Deployed as a vendored manifest with an exact image tag, matched to the cluster's Kubernetes minor and moved with it on upgrade. Nodes register with `cloud-provider=external`, a provider ID of `aws:///<availability-zone>/<instance-id>`, and their EC2 private DNS name as the node name. `KubernetesClusterID` is the Ankra cluster ID, matching the `kubernetes.io/cluster/<id>=owned` tag on every instance.
* **Load balancers.** A `Service` of type `LoadBalancer` gets an AWS load balancer from the cloud controller. The networking stack's Traefik asks for a Network Load Balancer (`service.beta.kubernetes.io/aws-load-balancer-type: nlb`), and Ankra sets the managed tag on it so the teardown sweep can find it.
* **Storage.** The EBS CSI driver is installed from its upstream chart at a pinned version, after the cloud controller (it needs the provider ID and topology labels the controller sets). The default StorageClass provisions encrypted gp3 volumes.
* **No keys in the cluster.** The cloud controller and the CSI driver use the instance profile of the node they run on; the control-plane and worker profiles are distinct, following the upstream policy split, and the platform credential is never copied into the cluster.

### Preflight checks

Preflight (`ankra cluster aws preflight`, `POST /api/v1/clusters/aws/preflight`) runs every check the create runs. For a created network: whether `network_ip_range` holds a private `/20` and a public `/24` per zone, whether every zone exists and is available, the three-control-plane rule for more than one zone, and the VPC (`L-F678F1CE`), NAT gateway (`L-FE5A380F`) and Elastic IP quotas. For an adopted VPC: whether the VPC and subnets exist in the region, which zones the node subnets cover, and the resolved egress mode (and why `bastion_nat` is refused, if it is). For both: the AMI resolved for the Ubuntu series and architecture, the vCPU quota for the chosen instance families, the security-groups-per-interface quota, and `bastion_allowed_ips`. Each item is `ok`, `warning` or `error`.

### IMDS guard

| Instance | IMDSv2 | Hop limit | Why |
| - | - | - | - |
| Bastion | required | 1 | Nothing on the bastion needs the instance role beyond the host |
| Workers | required | 1 | Pods on the pod network cannot reach the node role |
| Control planes | required | 3 | The upstream EBS CSI chart cannot run its controller on the host network, and the controller needs the control-plane role |

The hop limit of 3 on control planes is compensated by the **IMDS guard**: a cluster-wide network policy in the AWS cloud-provider stack that denies pod egress to `169.254.169.254` for every pod except the EBS CSI controller. It is rendered for Cilium and Calico. Flannel has no policy engine, so on a flannel cluster the guard is not installed, the create result reports `imds_guard: unavailable`, and a pod scheduled onto a control-plane node can reach the control-plane instance role - prefer Cilium (the default) or keep the control planes tainted.

***

## Catalogs

Every catalog loads live from your credential - `ankra cluster aws regions`, `vpcs`, `subnets`, `availability-zones`, `instance-types`, `images` and `pricing`, or the endpoints in the [catalog API](#catalog-api). The tables below are orientation, not the offer.

### Regions

| Region | Location |
| - | - |
| `eu-north-1` | Stockholm |
| `eu-west-1` | Ireland |
| `eu-west-2` | London |
| `eu-central-1` | Frankfurt |
| `us-east-1` | N. Virginia |
| `us-east-2` | Ohio |
| `us-west-2` | Oregon |
| `ca-central-1` | Canada (Central) |
| `ap-southeast-1` | Singapore |
| `ap-southeast-2` | Sydney |
| `ap-northeast-1` | Tokyo |
| `ap-south-1` | Mumbai |
| `sa-east-1` | São Paulo |

Any region your credential can `DescribeRegions` is offered; opt-in regions appear once enabled in your account.

### Instance types

Only `amd64` types are offered. Prices are per region and per hour; `ankra cluster aws pricing` and the wizard show the live figure.

| Type | vCPUs | Memory | Typical use |
| - | - | - | - |
| `t3.small` | 2 | 2 GiB | Bastion |
| `t3.medium` | 2 | 4 GiB | Control plane on a small cluster |
| `t3.large` | 2 | 8 GiB | General workers |
| `m6i.large` | 2 | 8 GiB | Control plane, general workers (non-burstable) |
| `m6i.xlarge` | 4 | 16 GiB | Larger workloads |
| `c6i.xlarge` | 4 | 8 GiB | Compute-heavy workers |
| `r6i.large` | 2 | 16 GiB | Memory-heavy workers, databases |

> [!NOTE]
>
> Burstable `t3` types spend CPU credits under sustained load; use `m6i`/`c6i`/`r6i` for a control plane or workers that run flat out. `ankra cluster aws instance-types` lists what the region offers, with vCPUs, memory, architecture and network performance.

### Images

| `ubuntu_series` | AMI source |
| - | - |
| `24.04` (default) | `/aws/service/canonical/ubuntu/server/24.04/stable/current/amd64/hvm/ebs-gp3/ami-id` |
| `22.04` | `/aws/service/canonical/ubuntu/server/22.04/stable/current/amd64/hvm/ebs-gp3/ami-id` - only listed when its AMI resolves in the region |

The AMI ID is resolved from these public SSM parameters in the target region at create time, so every cluster boots the current stable image of its series. The images catalog (`ankra cluster aws images`, `GET /api/v1/clusters/aws/images`) answers `ubuntu_series`, `architectures` and `default_series`, and lists only the series whose AMI resolves in that region.

***

## Limits

| Limit | Value |
| - | - |
| Control plane count | 1 to 9; at least 3 on more than one availability zone, and a multi-AZ cluster cannot scale below 3 |
| Nodes per node group | 0 to 100 |
| Architecture | `amd64` only (`arm64` refused with `422` until the image-catalogue audit) |
| Root volume | 20 to 2000 GiB, encrypted gp3 |
| Distribution on kubeadm | Cilium CNI only |
| IMDS guard | Cilium and Calico only; `imds_guard: unavailable` on flannel |
| `bastion_allowed_ips` | IPv4 CIDRs, or `0.0.0.0/0` / `::/0`; an empty list means `0.0.0.0/0` |
| Node public IPs | Never assigned |
| Node group user data | Cloud-init document, at most 16 KiB (the EC2 limit) |
| IAM role and instance profile names | Truncated to 64 characters |
| Standalone VMs | Not available on AWS in this release |
| Created VPC range | `/16` to `/20`; must hold a private `/20` and a public `/24` per zone (a `/20` fits one zone) |
| Created VPC zones | One or three by default; any number you name, but more than one needs at least 3 control planes |
| Network fields | `network_ip_range`, `availability_zones`, `nat_gateway_single_zone` are refused alongside `vpc_id`; `node_subnet_ids`, `bastion_subnet_id` are refused without it |
| Account quotas checked | VPCs per region (`L-F678F1CE`), NAT gateways per zone (`L-FE5A380F`), Elastic IPs, vCPUs, security groups per interface |

***

## Catalog API

Every catalog takes `credential_id` and `region` as query parameters (`subnets` also takes `vpc_id`), and every answer is three-state: a value Ankra could not read says so rather than reading as empty or zero.

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/aws/regions` | GET | Regions the credential can reach |
| `/api/v1/clusters/aws/instance-types` | GET | Instance types in a region: `name`, `vcpus`, `memory_gib`, `architecture`, `category` (`general`, `compute`, `memory`, `storage`, `accelerated`, `hpc`, `other`), `current_generation`, `hourly_price_usd` and `monthly_price_usd` (null when unpriced) |
| `/api/v1/clusters/aws/vpcs` | GET | VPCs in a region: `id`, `name`, `cidr`, `is_default`, `dhcp_domain_name`, and `dhcp_domain_name_state` - `set`, `empty` or `unknown` (the DHCP options could not be read) |
| `/api/v1/clusters/aws/subnets` | GET | Subnets of a VPC: `availability_zone`, `map_public_ip_on_launch`, `egress.kind` - `nat_gateway`, `nat_instance`, `internet_gateway`, `transit`, `none` or `unknown` - and `foreign_instance_count`, the instances Ankra did not create (`null` when it could not be counted) |
| `/api/v1/clusters/aws/availability-zones` | GET | Availability zones of a region |
| `/api/v1/clusters/aws/images` | GET | `ubuntu_series` whose AMI resolves in the region, `architectures`, and `default_series` |
| `/api/v1/clusters/aws/pricing` | GET | On-demand `instance_types` prices plus `storage.gp3_gib_month_usd`, with `pricing_complete` and `incomplete_reasons` - a price Ankra could not read is reported as missing, never as `0` |
| `/api/v1/clusters/aws/{cluster_id}/instance-types` | GET | The instance-type catalog in an existing cluster's own region and credential |

## Cluster API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/aws/preflight` | POST | Run every check the create runs, without creating anything. Answers `items` (each `check`, `status` `ok`, `warning` or `error`, `message`), `can_proceed`, `network_ownership` (`created` or `adopted`), `resolved_availability_zones`, and `resolved_egress_mode` (null when it could not be decided). A `warning` is a read Ankra could not perform or a caveat such as flannel not enforcing the IMDS guard |
| `/api/v1/clusters/aws` | POST | Create a cluster. Answers `cluster_id`, `name`, `kind: "aws"`, `state: "creating"`, `operation_id` |
| `/api/v1/clusters/aws/{cluster_id}` | DELETE | Deprovision a cluster (volumes and load balancers follow `retention_policy`; deleting volumes needs `?accept_volume_data_loss=true`, 409 without it) |
| `/api/v1/clusters/aws/{cluster_id}/deprovision-volumes` | GET | The EBS volumes a deprovision deletes, or keeps under `retention_policy` |
| `/api/v1/clusters/aws/{cluster_id}/stop` | POST | Stop every instance; private IPs and root volumes are kept |
| `/api/v1/clusters/aws/{cluster_id}/start` | POST | Start a stopped cluster (`?scope=all` or `control_plane`) |
| `/api/v1/clusters/aws/{cluster_id}/access-info` | GET | `bastion_host`, `bastion_port` (22), `bastion_user` and `target_user` (both `ubuntu`), `control_plane_ips` |
| `/api/v1/clusters/aws/{cluster_id}/quotas` | GET | Answers `404` ("Quota reporting is not available for aws clusters") until the vCPU / Elastic IP report ships |
| `/api/v1/clusters/aws/{cluster_id}/k8s-version` | GET | Current Kubernetes version and distribution |
| `/api/v1/clusters/aws/{cluster_id}/upgrade-k8s-version` | POST | Upgrade Kubernetes (`{"target_version": "..."}`) |
| `/api/v1/clusters/aws/{cluster_id}/worker-count` | GET | Legacy default-pool worker count |
| `/api/v1/clusters/aws/{cluster_id}/scale-workers` | POST | Legacy default-pool scale (`{"worker_count": n}`) |
| `/api/v1/clusters/aws/{cluster_id}/ssh-keys` | GET | SSH key credentials attached to the cluster |
| `/api/v1/clusters/aws/{cluster_id}/ssh-keys` | PUT | Replace the attached SSH key credentials |
| `/api/v1/clusters/aws/{cluster_id}/ssh-keys/resync` | POST | Rewrite `authorized_keys` on every node now |

## Node Group API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/aws/{cluster_id}/node-groups` | GET | List all node groups, with the zones each group's nodes were placed in |
| `/api/v1/clusters/aws/{cluster_id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}/scale` | PUT | Scale a node group (0 to 100) |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}/instance-type` | PUT | Change instance type (replaces every node of the group) |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}/autoscaling` | GET | Read autoscaling bounds |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}/autoscaling` | PUT | Set autoscaling bounds |
| `/api/v1/clusters/aws/{cluster_id}/node-groups/{name}` | DELETE | Delete a node group and its nodes |

## Control Plane API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/aws/{cluster_id}/control-plane` | GET | Control plane count and instance type |
| `/api/v1/clusters/aws/{cluster_id}/control-plane` | PUT | Change the count (1 or 3; a multi-AZ cluster stays at 3) |
| `/api/v1/clusters/aws/{cluster_id}/control-plane/instance-type` | PUT | Change the control plane instance type - live, one controller at a time, with three or more controllers; offline on a stopped cluster otherwise |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/aws/{cluster_id}/nodes` | GET | List all nodes (control plane, workers, bastion), including soft-deleted entries of a stopped cluster |
| `/api/v1/clusters/aws/{cluster_id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/aws/{cluster_id}/nodes/{node_id}/restart` | POST | Restart a node (EC2 reboot, falls back to stop and start) |
| `/api/v1/clusters/aws/{cluster_id}/nodes/{node_id}/cloud-init-log` | POST | Fetch `cloud-init status --long` and the tail of the cloud-init output log over the bastion |
| `/api/v1/clusters/aws/{cluster_id}/bastion/health` | GET | The last verdict of the bastion health loop |
| `/api/v1/clusters/aws/{cluster_id}/bastion/diagnose` | POST | Probe the bastion now, as a tracked operation |
| `/api/v1/clusters/aws/{cluster_id}/bastion/instance-type` | PUT | Resize the bastion (stop, change type, start; the Elastic IP is kept) |

See [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [Bastion](/guides/operate-ankra-managed-clusters#bastion) for usage, and [AWS specifics](/guides/aws-clusters#aws-specifics) for how AWS applies them.

## Credential API

The bearer-token twins of the AWS credential onboarding, for scripts and the CLI. Connecting a credential from the dashboard is documented on [AWS Credentials](/platform/credentials/aws).

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/credentials/aws/onboarding` | GET | `?scope=cost` (default), `provisioning` or `self_managed`: the external ID, the CloudFormation `launch_stack_url`, `template_url` and `trust_principal_arn` for that scope's role. Unknown scopes answer `400` |
| `/api/v1/credentials/aws/role` | POST | Register an STS role credential (`name`, `role_arn`, `external_id`, `region`, `scope`). The role is assumed first; a `self_managed` scope is also proven against EC2 (a dry-run `DescribeVpcs`) and the Canonical AMI SSM parameters. Unknown scope `400`, name clash `409`, failed connection test `400` |
| `/api/v1/credentials/aws/keys` | POST | Register an access-keys credential (`name`, `access_key_id`, `secret_access_key`, `region`) |

Creating a cluster needs a keys credential, or a role credential whose scope is `provisioning` (the `AnkraProvisioning` role, which covers EKS and self-managed clusters) or `self_managed` (the EC2-only `AnkraSelfManagedProvisioning` role); a `cost`-scoped role is refused.

The CLI wraps the three: `ankra credentials aws onboarding [--scope cost|provisioning|self_managed]` prints the external ID, trust principal, launch-stack URL and the follow-up command; `ankra credentials aws create-role --name <name> --role-arn <arn> --external-id <id> [--region <region>] [--scope <scope>]` stores the role; `ankra credentials aws create-keys --name <name> --access-key-id <id> [--region <region>]` stores access keys, asking for the secret on a masked prompt (never a flag); `ankra credentials aws list` shows what is connected.


# ankra agents
Source: https://docs.ankra.ai/reference/cli/agents

Inspect and control AI agent runs

## ankra agents

Inspect and control the organisation's AI agent runs.

Every time an AI agent is dispatched (a board ticket, a schedule, an
alert, or run-now) the platform records a run with a linked session.
These commands list those runs, show one in full, read its transcript,
and cancel a live run — the platform interrupts the in-flight turn
within seconds.

## ankra agents cancel

Cancel a live AI agent run. The run and its session flip to
'cancelled' and the platform interrupts the in-flight turn within
seconds, without pausing the agent itself. Organisation admins only.

```bash theme={null}
ankra agents cancel <run_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra agents run

Show one AI agent run in full

```bash theme={null}
ankra agents run <run_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra agents runs

List the organisation's AI agent runs, newest first

```bash theme={null}
ankra agents runs [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `20` | Maximum runs to return (max 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | `[]` | Filter by run status (pending, running, awaiting\_user, completed, failed, cancelled, expired, skipped); repeatable |
| `--task` | | Filter to one agent task id (UUID) |

## ankra agents transcript

Read an AI agent run's session transcript

```bash theme={null}
ankra agents transcript <run_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `200` | Maximum events to return (max 1000) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--since` | `0` | Return events with a sequence number greater than this |


# ankra ai
Source: https://docs.ankra.ai/reference/cli/ai

Manage AI provider settings and the model catalog

## ankra ai

Configure the organisation's AI provider, credentials, custom
OpenAI-compatible endpoints, and the model catalog the chat picker offers.

Mutations require the ai.manage permission (organisation admins by default);
the provider status and the model listing are available to every member.

## ankra ai anthropic

Manage the custom Anthropic API key

## ankra ai anthropic delete

Remove the custom Anthropic API key

```bash theme={null}
ankra ai anthropic delete [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai anthropic set

Store and validate a custom Anthropic API key (must start with sk-ant-).

```bash theme={null}
ankra ai anthropic set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-key` | | Anthropic API key (starts with sk-ant-) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai autonomy

Read and operate the organisation-wide AI kill switch.

Engaging it stops all AI for everyone in the organisation: running sessions
and agent runs are cancelled, and chat is refused until it is released. Reach
for it during an incident, not to tighten a policy - a narrower stop lives in
the auto-remediation policy, which 'ankra ai remediation policy' reads.

## ankra ai autonomy pause

Pause autonomous actions across the organisation.

Chat, diagnosis and read-only investigation keep working; what stops is the
AI changing anything without a person approving it first. It switches off
auto-remediation and pauses every enabled agent, and records exactly what it
switched off - so resuming restores that and nothing else, from any
terminal or browser, by any administrator.

To stop AI entirely during an incident, use "ankra ai autonomy stop-all".

```bash theme={null}
ankra ai autonomy pause [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why autonomous actions are paused |

## ankra ai autonomy resume

Resume autonomous actions.

Only what the pause switched off is restored: an agent somebody disabled
deliberately stays disabled.

```bash theme={null}
ankra ai autonomy resume [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai autonomy start-all

Let AI run again for the organisation

```bash theme={null}
ankra ai autonomy start-all [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai autonomy status

Show whether AI is stopped for the organisation

```bash theme={null}
ankra ai autonomy status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai autonomy stop-all

Stop all AI for everyone in the organisation.

Every running AI session and agent run is cancelled, pending approvals
expire, and chat is refused until the switch is released. The reason is
shown to administrators alongside the switch.

```bash theme={null}
ankra ai autonomy stop-all [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why AI is being stopped (shown to administrators) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai board-identity

Manage the organisation's board agent identity.

Agents the platform created - the preloaded team - have no user account of
their own, so their headless runs cannot change anything. The board identity
gives them one, with its own role, so their work is attributable to the agent
rather than to whoever set it up. It cannot sign in and has no token.

Without it, a designated board worker is escalated to a human on every ticket
instead of working it.

## ankra ai board-identity provision

Give the board an identity its agents act as

```bash theme={null}
ankra ai board-identity provision [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--role` | | Role the identity carries: operator (default), member, or viewer |

## ankra ai board-identity revoke

Stand the board identity down.

The principal itself is kept so its past actions stay attributable; what it
loses is every grant above the viewer floor, which makes the board's agents
ineligible again on the next dispatcher pass.

```bash theme={null}
ankra ai board-identity revoke [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai board-identity status

Show whether the board has an identity

```bash theme={null}
ankra ai board-identity status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai endpoints

Manage custom OpenAI-compatible endpoints

## ankra ai endpoints create

Add a named OpenAI-API-standard endpoint (OpenRouter, vLLM, LiteLLM,
Ollama, ...). The server validates and probes the endpoint before saving; the
API key is stored server-side and never returned.

Pipe the API key on stdin, or run interactively to be prompted for it (the
prompt masks the input):

```bash theme={null}
ankra ai endpoints create --name vllm --base-url https://vllm.example.com/v1 < key.txt
```

`--api-key` still works but is deprecated: a key on the command line lands in
the shell history and the process list.

```bash theme={null}
ankra ai endpoints create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-key` | | API key for the endpoint (deprecated: lands in shell history; omit to read stdin or be prompted) |
| `--base-url` | | OpenAI-compatible base URL (e.g. [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1)) |
| `--name` | | Endpoint name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai endpoints delete

Delete an endpoint and its stored key. Catalog models on it are removed too.

```bash theme={null}
ankra ai endpoints delete <endpoint_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai endpoints discover

Query the endpoint's /models list so you know which model ids to reference.

```bash theme={null}
ankra ai endpoints discover <endpoint_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai endpoints list

List configured OpenAI-compatible endpoints

```bash theme={null}
ankra ai endpoints list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai endpoints update

Update an endpoint's name, base URL, and optionally rotate its key.
Omit `--api-key` to keep the stored key.

```bash theme={null}
ankra ai endpoints update <endpoint_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-key` | | New API key (omit to keep the stored key) |
| `--base-url` | | OpenAI-compatible base URL |
| `--name` | | Endpoint name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai lanes

Choose the model each AI function runs on.

A lane is one AI function that runs outside chat: deploy analysis,
troubleshooting, CI/CD generation, stack README generation and AI code
review. A lane with no selection follows its default tier in the model
catalog ('ankra ai models list'), so it moves when the catalog does.

## ankra ai lanes clear

Return a lane to its default tier

```bash theme={null}
ankra ai lanes clear <lane> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai lanes list

List each AI lane with the model it runs on

```bash theme={null}
ankra ai lanes list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai lanes set

Run a lane on a catalog model or an exact OpenRouter model.

\<model> is a catalog key from 'ankra ai models list' (for example think or
expert) or an exact OpenRouter model id (for example z-ai/glm-5.2). Changing a
lane requires organisation admin.

```bash theme={null}
ankra ai lanes set <lane> <model> [flags]
```

**Examples**

```bash theme={null}
ankra ai lanes set pr_review think
ankra ai lanes set stack_description z-ai/glm-5.2
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai memories

List or clear what the assistant remembers about you.

Ankra's chat stores short facts from your conversations and recalls them
into later ones, so it does not have to rediscover your clusters, choices and
preferences every time. These commands act on your own memories in the
current organisation only; nobody else's are listed or touched.

## ankra ai memories clear

Delete every memory the assistant has stored for you in the current
organisation. The assistant starts your next conversation with nothing it
learned before. Other members' memories are not affected.

```bash theme={null}
ankra ai memories clear [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra ai memories list

List the memories the assistant has stored for you, newest first

```bash theme={null}
ankra ai memories list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `50` | How many memories to list (1-200) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai models

Manage the organisation model catalog

## ankra ai models create

Add a model to the catalog.

For an Ankra-managed Claude model pass `--model-id` (e.g. claude-opus-5). For a
model served by a custom OpenAI-compatible endpoint, also pass `--endpoint` with
the endpoint id (see 'ankra ai endpoints list').

```bash theme={null}
ankra ai models create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--context-window` | `200000` | Context window in tokens |
| `--description` | | Short description |
| `--enabled` | `true` | Model is selectable in the picker |
| `--endpoint` | | OpenAI-compatible endpoint id (omit for Ankra-managed Claude) |
| `--key` | | Catalog key (lowercase slug; the model\_mode value) |
| `--max-output` | `8192` | Maximum output tokens |
| `--model-id` | | Provider model id (e.g. claude-opus-5 or gpt-4o) |
| `--name` | | Display name shown in the picker |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--sort-order` | `0` | Sort order in the picker (lower first) |
| `--supports-images` | `false` | Model accepts image inputs |
| `--supports-thinking` | `false` | Model supports a thinking/reasoning channel |
| `--supports-tools` | `true` | Model supports tool calling |
| `--tier` | | Auto-routing tier: expert, think, quick, or empty |

## ankra ai models delete

Delete a catalog model

```bash theme={null}
ankra ai models delete <id|key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai models list

List the catalog models the chat picker offers

```bash theme={null}
ankra ai models list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai models reset

Revert the catalog to the built-in defaults

```bash theme={null}
ankra ai models reset [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai models update

Update a catalog model addressed by its row id or catalog key.

Only the flags you pass are changed; the rest keep their current values.
Editing a built-in default the first time materialises the catalog.

```bash theme={null}
ankra ai models update <id|key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--context-window` | `200000` | Context window in tokens |
| `--description` | | Short description |
| `--enabled` | `true` | Model is selectable in the picker |
| `--endpoint` | | OpenAI-compatible endpoint id (omit for Ankra-managed Claude) |
| `--key` | | Catalog key (lowercase slug; the model\_mode value) |
| `--max-output` | `8192` | Maximum output tokens |
| `--model-id` | | Provider model id (e.g. claude-opus-5 or gpt-4o) |
| `--name` | | Display name shown in the picker |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--sort-order` | `0` | Sort order in the picker (lower first) |
| `--supports-images` | `false` | Model accepts image inputs |
| `--supports-thinking` | `false` | Model supports a thinking/reasoning channel |
| `--supports-tools` | `true` | Model supports tool calling |
| `--tier` | | Auto-routing tier: expert, think, quick, or empty |

## ankra ai openai

Manage the legacy single OpenAI-compatible endpoint configuration.

For multiple endpoints and per-model routing prefer 'ankra ai endpoints' and
'ankra ai models'; this command configures the single legacy endpoint the
'openai\_compatible' provider uses.

## ankra ai openai delete

Remove the legacy OpenAI-compatible endpoint

```bash theme={null}
ankra ai openai delete [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai openai set

Store the legacy OpenAI-compatible endpoint

```bash theme={null}
ankra ai openai set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-key` | | API key for the endpoint |
| `--base-url` | | OpenAI-compatible base URL |
| `--model` | | Model id to use |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai openrouter

Manage the organisation's OpenRouter API key (bring your own key).

Store a key with 'set', then activate it with 'ankra ai provider openrouter'.
Removing the key while OpenRouter is the active provider resets the
organisation to the Ankra-managed default.

## ankra ai openrouter remove

Remove the organisation's OpenRouter API key. When OpenRouter is the
active provider the organisation falls back to the Ankra-managed default.

```bash theme={null}
ankra ai openrouter remove [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra ai openrouter set

Store and validate an OpenRouter API key (must start with sk-or-).

Pass the key with `--api-key`, pipe it on stdin, or omit both to be prompted
interactively. The interactive prompt masks the input; the key is never
echoed or logged.

```bash theme={null}
ankra ai openrouter set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-key` | | OpenRouter API key (starts with sk-or-; omit to read stdin or be prompted) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai provider

Set the active AI provider for the organisation.

```bash theme={null}
ankra              Ankra-managed Claude models (the default).
anthropic          Your own Anthropic API key (set it first with 'ankra ai anthropic set').
openai_compatible  Your OpenAI-compatible endpoint (set it first with 'ankra ai openai set').
openrouter         Your own OpenRouter API key (set it first with 'ankra ai openrouter set').
```

```bash theme={null}
ankra ai provider <ankra|anthropic|openai_compatible|openrouter> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai remediation

Read the organisation's AI auto-remediation settings.

Auto-remediation is the lane where an alert trigger opens an AI run that may
change the platform on its own. Its envelope lives in one policy document:
how much the run may do unattended, which tools are exempt from the approval
card, and which clusters it is allowed to touch.

The policy is read-only from the CLI. Changing it is an organisation-admin
action in the portal.

## ankra ai remediation policy

Show the organisation's auto-remediation policy.

An organisation that never saved a policy is not an error: the platform
answers its own defaults, and this command says so rather than presenting
them as a decision somebody made.

Two lines carry most of the risk. A per-tool override of 'auto' means that
tool executes with no approval card at all, and a cluster allow list that was
never set means every cluster is in scope, including Ankra's own.

```bash theme={null}
ankra ai remediation policy [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra ai status

Show the active AI provider and configured credentials

```bash theme={null}
ankra ai status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra alerts
Source: https://docs.ankra.ai/reference/cli/alerts

Manage alert destinations and notification routes

## ankra alerts

Manage where Ankra delivers alerts and platform notifications.

Destinations are the endpoints notifications are sent to: a webhook URL
(Slack, Microsoft Teams, Discord, PagerDuty, or any custom receiver) or a
Slack/Teams channel the Ankra bot posts to directly. Routes decide which
notifications reach which destination, filtered by kind, severity, cluster,
and source, so the whole alerting setup can live in scripts and CI next to
the rest of your platform configuration.

```bash theme={null}
ankra alerts destinations list
ankra alerts destinations create --name ops-slack --url https://hooks.slack.com/services/...
ankra alerts destinations test <destination-id>
ankra alerts routes create --destination-id <destination-id> --severity critical
ankra alerts routes list -o json
```

## ankra alerts destinations

Manage the organisation's alert destinations.

A destination is either a webhook URL or a channel-based Slack/Teams
destination that carries a channel id instead of a URL (list the channels
the Ankra bot can post to with 'ankra alerts destinations channels').
Webhook URLs are shown masked on every read.

## ankra alerts destinations channels

List the channels the Ankra bot can post to, for use with
'ankra alerts destinations create `--channel-id`'. Both providers are shown
unless `--provider` narrows it to one.

A provider whose workspace or tenant is not connected to the organisation
reads "not connected"; one whose bot service is not configured on this
platform reads "not available". Neither is an error.

```bash theme={null}
ankra alerts destinations channels [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Only one provider: slack or teams (default both) |

## ankra alerts destinations create

Create an alert destination.

Pass `--url` for a webhook destination, or `--channel-id` for a channel-based
Slack or Teams destination (find ids with 'ankra alerts destinations
channels'); a Teams channel also needs `--teams-tenant-id`. `--type` records
which receiver the destination targets (slack, teams, discord, pagerduty,
custom; default slack) and selects the default payload format;
`--template-file` overrides the payload with your own template.

```bash theme={null}
ankra alerts destinations create --name ops-slack --url https://hooks.slack.com/services/...
ankra alerts destinations create --name oncall --type pagerduty --url https://events.pagerduty.com/...
ankra alerts destinations create --name ops-teams --type teams --channel-id 19:abc@thread.tacv2 --teams-tenant-id <tenant>
```

```bash theme={null}
ankra alerts destinations create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--channel-id` | | Slack or Teams channel id for a channel-based destination (instead of `--url`) |
| `--channel-name` | | Display name of the channel behind `--channel-id` |
| `--description` | | Free-text description |
| `--disabled` | `false` | Create the destination disabled |
| `--name` | | Destination name, unique within the organisation |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--teams-tenant-id` | | Microsoft Teams tenant id (required with `--channel-id` for `--type` teams) |
| `--template-file` | | File holding a custom payload template |
| `--type` | | Receiver type: slack, teams, discord, pagerduty, or custom (default slack) |
| `--url` | | Webhook URL to deliver to |

## ankra alerts destinations delete

Delete an alert destination. Routes that pointed at it stop delivering;
remove or re-point them with 'ankra alerts routes'.

```bash theme={null}
ankra alerts destinations delete <destination-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra alerts destinations get

Show one alert destination

```bash theme={null}
ankra alerts destinations get <destination-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra alerts destinations list

List the organisation's alert destinations, 20 per page.

Filter by name with `--search` and by state with `--enabled` or `--disabled`. The
ID column is what routes and the other destination commands take.

```bash theme={null}
ankra alerts destinations list --search slack
ankra alerts destinations list --disabled -o json
```

```bash theme={null}
ankra alerts destinations list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--disabled` | `false` | Only disabled destinations |
| `--enabled` | `false` | Only enabled destinations |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `20` | Destinations per page (max 100) |
| `--search` | | Filter destinations by name |

## ankra alerts destinations test

Send a sample notification to a stored destination and report whether
the receiver accepted it. A failed delivery exits non-zero so CI can gate
on it; the details are still printed (or emitted with -o json).

```bash theme={null}
ankra alerts destinations test <destination-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra alerts destinations test-url

Send a sample notification to an ad-hoc webhook URL, optionally with a
custom payload template, without creating a destination. A failed delivery
exits non-zero.

```bash theme={null}
ankra alerts destinations test-url --url https://hooks.slack.com/services/...
ankra alerts destinations test-url --url https://example.com/hook --template-file payload.json
```

```bash theme={null}
ankra alerts destinations test-url [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--template-file` | | File holding a custom payload template |
| `--url` | | Webhook URL to send the test notification to |

## ankra alerts destinations update

Update an alert destination. Only the flags you pass are changed; the
rest keep their current values.

```bash theme={null}
ankra alerts destinations update <destination-id> --url https://hooks.slack.com/services/new
ankra alerts destinations update <destination-id> --disabled
```

```bash theme={null}
ankra alerts destinations update <destination-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--channel-id` | | New Slack or Teams channel id |
| `--channel-name` | | New display name of the channel |
| `--description` | | New description |
| `--disabled` | `false` | Disable the destination |
| `--enabled` | `false` | Enable the destination |
| `--name` | | New destination name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--teams-tenant-id` | | New Microsoft Teams tenant id |
| `--template-file` | | File holding the new payload template |
| `--url` | | New webhook URL |

## ankra alerts ingest-credentials

Ingest credentials are the per-credential secrets an external Alertmanager
or log monitor uses to deliver alerts into Ankra. A credential is pinned to
one cluster (scope cluster), carries the platform's own alerts with no pin
(scope platform), or does both from a self-hosting cluster (scope mixed).

The token is minted once, in the portal, and never shown again. These
commands never touch it: a rebind moves the pin or the scope on the
existing credential, so the notifier keeps delivering.

```bash theme={null}
ankra alerts ingest-credentials list
ankra alerts ingest-credentials rebind <credential-id> --cluster prod-hel1
ankra alerts ingest-credentials rebind <credential-id> --unpin --scope platform
```

## ankra alerts ingest-credentials list

List the organisation's alert ingest credentials with the cluster each one
is pinned to. A pin whose cluster is deleted, archived, slated for deletion
or gone shows as BROKEN: the notifier still delivers, but its alerts have no
cluster to land on until the credential is rebound.

```bash theme={null}
ankra alerts ingest-credentials list
ankra alerts ingest-credentials list -o json
```

```bash theme={null}
ankra alerts ingest-credentials list
```

## ankra alerts ingest-credentials rebind

Rebind an ingest credential: pin it to another cluster, unpin it, or change
its scope. The token is untouched, so the notifier keeps delivering through
the same credential.

Pass `--cluster` with a cluster name to pin, `--unpin` to clear the pin, and
`--scope` with cluster, platform or mixed. A platform-scoped credential
carries no pin; a mixed one must keep one.

```bash theme={null}
ankra alerts ingest-credentials rebind <credential-id> --cluster prod-hel1
ankra alerts ingest-credentials rebind <credential-id> --cluster prod-hel1 --scope mixed
ankra alerts ingest-credentials rebind <credential-id> --unpin --scope platform
```

```bash theme={null}
ankra alerts ingest-credentials rebind <credential-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | cluster name to pin the credential to |
| `--scope` | | credential scope: cluster, platform or mixed |
| `--unpin` | `false` | clear the cluster pin |

## ankra alerts routes

Manage the organisation's notification routes.

A route sends notifications matching every filter it sets (kind, severity,
cluster, source) to one destination; a route with no filters matches
everything. Routes are evaluated in ascending priority, mode "exclude"
withholds matches instead of delivering them, and `--stop-on-match` ends the
walk at that route so lower-priority routes never see the notification.

```bash theme={null}
ankra alerts routes create --destination-id <destination-id> --severity critical
ankra alerts routes create --destination-id <destination-id> --kind execution_failed --cluster-id <cluster-id> --priority 10
ankra alerts routes update <route-id> --disabled
ankra alerts routes test <route-id>
```

## ankra alerts routes create

Create a notification route to a destination. Every filter is optional;
a route with none matches every notification.

Kinds include execution\_failed, resource\_deployment\_failed,
resource\_health\_degraded, alert\_trigger\_fired, gitops\_sync\_failed,
agent\_offline, security\_new\_severe\_cves, and the other platform
notification kinds; severities are critical, warning, and info.

```bash theme={null}
ankra alerts routes create --destination-id <destination-id> --severity critical
ankra alerts routes create --destination-id <destination-id> --kind gitops_sync_failed --mode exclude --stop-on-match
ankra alerts routes create --destination-id <destination-id> --kinds pipeline_run_failed,image_gate_blocked \
  --application cadence --reference-pattern main
```

`--application` limits a route to one application's notifications (pipeline
runs, image gates, previews); `--reference-pattern` to the branches, tags or
pull requests a glob matches. "main" matches pushes to main and never a pull
request targeting main; "pull/*" matches every pull request; "release/*" one
path segment and "release/\*\*" any depth; "refs/tags/v\*" tags.

```bash theme={null}
ankra alerts routes create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Only notifications about this application (name or id) |
| `--cluster-id` | | Only notifications about this cluster (id) |
| `--destination-id` | | Destination to deliver to (see 'ankra alerts destinations list') |
| `--disabled` | `false` | Create the route disabled |
| `--exclude-kinds` | | Every kind EXCEPT these (comma-separated) |
| `--kind` | | Only notifications of this kind (for example execution\_failed) |
| `--kinds` | | Only notifications of these kinds (comma-separated) |
| `--mode` | | include delivers matches, exclude withholds them (default include) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--priority` | `0` | Evaluation order, lowest first (default 100) |
| `--reference-pattern` | | Only notifications about a branch, tag or pull request matching this glob (main, release/*, pull/*) |
| `--severity` | | Only notifications of this severity: critical, warning, or info |
| `--source-id` | | Only notifications from this source id |
| `--stop-on-match` | `false` | Stop evaluating lower-priority routes once this one matches |

## ankra alerts routes delete

Delete a notification route

```bash theme={null}
ankra alerts routes delete <route-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra alerts routes list

List notification routes

```bash theme={null}
ankra alerts routes list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra alerts routes preview

Resolve a hypothetical notification against the organisation's routing
rules and, with `--alert-id`, that alert's own destinations, and print the
destinations it would reach with the reason each one matched.

Nothing is delivered and nothing is changed - this is a dry run.

Pass `--alert-id` whenever you preview an alert firing. A destination reached
by both the alert's own list and a routing rule is delivered to once, and
without the alert id the preview cannot tell you which rule that affects.

```bash theme={null}
ankra alerts routes preview --kind alert_trigger_fired --severity critical
ankra alerts routes preview --kind alert_trigger_fired --severity critical --alert-id <alert-id>
ankra alerts routes preview --kind gitops_sync_failed --severity warning --cluster-id <cluster-id> -o json
ankra alerts routes preview --kind pipeline_run_failed --severity warning --application cadence --reference refs/heads/main
ankra alerts routes preview --kind pipeline_run_failed --severity warning --application cadence --reference pull/55
```

```bash theme={null}
ankra alerts routes preview [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--alert-id` | | Resolve as a firing of this alert, including its own destinations |
| `--application` | | Resolve as a notification about this application (name or id) |
| `--cluster-id` | | Resolve as a notification about this cluster |
| `--kind` | | Notification kind to resolve (for example alert\_trigger\_fired) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reference` | | Resolve as a notification about this reference (refs/heads/\<branch>, pull/\<number>) |
| `--severity` | `critical` | Notification severity: critical, warning, or info |
| `--source-id` | | Resolve as a notification from this source id |

## ankra alerts routes test

Queue a sample notification through a route's destination. Delivery is
asynchronous: the command returns the delivery id once the sample is
queued, not once the receiver has accepted it.

```bash theme={null}
ankra alerts routes test <route-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra alerts routes update

Update a notification route. Only the flags you pass are changed; the
rest keep their current values.

```bash theme={null}
ankra alerts routes update <route-id> --priority 5 --stop-on-match
ankra alerts routes update <route-id> --destination-id <other-destination-id>
ankra alerts routes update <route-id> --disabled
```

```bash theme={null}
ankra alerts routes update <route-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Only notifications about this application (name or id) |
| `--cluster-id` | | Only notifications about this cluster (id) |
| `--destination-id` | | Re-point the route at another destination |
| `--disabled` | `false` | Disable the route |
| `--enabled` | `false` | Enable the route |
| `--exclude-kinds` | | Every kind EXCEPT these (comma-separated) |
| `--kind` | | Only notifications of this kind (for example execution\_failed) |
| `--kinds` | | Only notifications of these kinds (comma-separated) |
| `--mode` | | include delivers matches, exclude withholds them (default include) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--priority` | `0` | Evaluation order, lowest first (default 100) |
| `--reference-pattern` | | Only notifications about a branch, tag or pull request matching this glob (main, release/*, pull/*) |
| `--severity` | | Only notifications of this severity: critical, warning, or info |
| `--source-id` | | Only notifications from this source id |
| `--stop-on-match` | `false` | Stop evaluating lower-priority routes once this one matches |


# ankra application
Source: https://docs.ankra.ai/reference/cli/application

Manage applications

## ankra application

Connect application source repositories to Ankra for analysis, packaging, and deployment.

## ankra application add

Add an application by reading a local Git checkout.

The command detects the GitHub repository from the selected remote, uses the
remote's default branch when available, and falls back to the current branch.
It selects an available GitHub credential automatically when the choice is
unambiguous.

Without `--registry-url` the application publishes to the organisation's own
Ankra registry project, and the command says so on success. Pass it to publish
to a container image registry you already operate instead. Declare it here
rather than afterwards: the setup job generates the build workflow from the
declaration the application is created with, so a registry added later leaves
a workflow that logs in with the wrong one - which is also why, when other
applications in the organisation publish somewhere else, this command names
those registries before the analysis finishes.

```bash theme={null}
ankra application add <path> [flags]
```

**Examples**

```bash theme={null}
ankra application add .
ankra application add ./services/payments --name payments
ankra application add . --credential github-acme --branch main
ankra application add . --registry-url oci://artifact.example.com/commerce \
  --registry-credential example-harbor
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--branch` | | Repository branch (auto-detected when omitted) |
| `--credential` | | GitHub credential name or ID (auto-detected when omitted) |
| `--name` | | Application name (defaults to the repository name) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--registry-admin-credential` | | Registry credential with project administrator rights, for Ankra to mint the application's robot |
| `--registry-api-url` | | Registry management API base (defaults to https\://\<host>) |
| `--registry-component-repository` | `[]` | Repository inside the project for one component, as \<component>=\<repository> (repeatable) |
| `--registry-credential` | | Registry credential of this organisation that authenticates to it |
| `--registry-flat-repositories` | `false` | Publish monorepo components as \<project>/\<component> instead of \<project>/\<app>/\<component> |
| `--registry-manage-actions-secrets` | `false` | Let Ankra write the named credential into the repository's Actions secrets |
| `--registry-password-secret` | | Repository Actions secret holding the registry password |
| `--registry-pull-secret` | | Name of the dockerconfigjson Secret generated manifests reference |
| `--registry-url` | | Registry project the application publishes to, as oci://\<host>/\<project> |
| `--registry-username-secret` | | Repository Actions secret the build workflow logs in with |
| `--remote` | `origin` | Git remote used to identify the GitHub repository |
| `--timeout` | `15m0s` | How long `--wait` waits before giving up |
| `--wait` | `false` | Wait for Ankra to finish analysing the repository, then print the setup pull request |

## ankra application ai-config

Read, set, or reset which AI lanes run on this application's repository
(pull request review, demo URL, and the rest), on which model, and within
what limits. An application follows the organisation's defaults until an
override is set here.

## ankra application ai-config clear

Reset the application to the organisation's AI defaults

```bash theme={null}
ankra application ai-config clear <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application ai-config get

Show the application's effective AI lane configuration

```bash theme={null}
ankra application ai-config get <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application ai-config set

Replace the application's AI lane configuration with a JSON document.
Start from the current one: 'ankra application ai-config get \<id> -o json',
edit it, and pass the file back with `--file` (or '-' to read stdin).

```bash theme={null}
ankra application ai-config set <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application ai-config get <application-id> -o json > lanes.json
ankra application ai-config set <application-id> --file lanes.json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--file` | | AI configuration JSON file, or '-' to read stdin (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application auto-deploy

Inspect and set whether pushes to the tracked branch deploy themselves.

With auto-deploy on, a build Ankra observes on the application's tracked branch
is rolled out to its deployments unattended. With it off, a push still builds -
it just waits for an explicit 'ankra application deploy'.

## ankra application auto-deploy get

Show whether auto-deploy is on, and the newest build seen on the tracked branch.

The newest observed build comes back with the switch so you can tell an
auto-deploy that is off from one that is on but has had nothing to pick up.

```bash theme={null}
ankra application auto-deploy get <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application auto-deploy get 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application auto-deploy set

Turn auto-deploy on or off.

`--enabled` is required and must be given explicitly: turning unattended
deployment on and turning it off are both deliberate acts, and neither is a
safe default to infer from a bare 'set'.

```bash theme={null}
ankra application auto-deploy set <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application auto-deploy set <application-id> --enabled
ankra application auto-deploy set <application-id> --enabled=false
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--enabled` | `false` | Deploy builds observed on the tracked branch without asking (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application backup

Back up one of an application's deployments now.

The capture is dispatched by the platform, so the command answers with the
restore point in 'creating' and the run that will seal it. With `--wait` it
follows that run to completion.

The deployment is named by the cluster it runs on; Ankra resolves which stack
that is, and the restore point it takes is the same artifact
'ankra cluster stacks restore-points list' shows for that stack.

```bash theme={null}
ankra application backup <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application backup shop --cluster production
ankra application backup shop --cluster production --note "before the 3.2 migration" --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster the deployment runs on (name or id, required) |
| `--note` | | Why this backup was taken, recorded on the audit row and the run |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `2h0m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault to write to (name or id; the deployment's own backup policy, then the organisation's only ready vault, when omitted) |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra application backups

Show an application's backup protection, deployment by deployment.

One row per cluster the application is deployed to: whether that deployment
carries a database, whether its data is protected, when it was last backed up
and when it is next scheduled.

The verdict has three values and none of them is a boolean: 'unknown' means
Ankra could not establish whether this deployment is protected, which is not
the same answer as 'unprotected'.

```bash theme={null}
ankra application backups <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application backups shop
ankra application backups shop -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application branch-files

List the tracked files on the setup branch

```bash theme={null}
ankra application branch-files <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application branches

List the application repository branches

```bash theme={null}
ankra application branches <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application build

Build an application's image on Ankra's builders.

Ankra clones the commit, resolves a recipe for it (the repository's own
Dockerfile, else a generated one, else buildpacks), builds it, and pushes the
image to the registry the application publishes to - without the repository's
CI running at all.

The routes answer 404 for organisations without the platform\_builds feature
flag, which is off by default while the lane rolls out. Ask Ankra support to
enable it for your organisation.

## ankra application build get

Show one platform build.

A failed build carries an error\_class saying whose failure it was. build\_failed
is the repository's - the recipe did not build - and is the one worth reading
the error\_message for. clone\_auth and recipe\_missing are the application's
configuration. push\_failed, timeout and capacity are Ankra's, and are already
visible to Ankra without anyone reporting them. build\_unknown is Ankra's too,
but not visible the same way: the build ran and failed in a way the builder
could not classify, and its error\_message - the end of the build's output - is
the only copy of that output, so include it when reporting the failure.

```bash theme={null}
ankra application build get <application-id> <build-id> [flags]
```

**Examples**

```bash theme={null}
ankra application build get <application-id> <build-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application build list

List the application's platform builds, newest first

```bash theme={null}
ankra application build list <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application build list <application-id> -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application build request

Show a queued build request and the build it became.

'start' answers with a request id before there is a build to read: the build
row is created when the scheduler claims the request. This is how a caller
follows the gap - status is pending until it is claimed, and build\_id names
the build from that point on.

```bash theme={null}
ankra application build request <application-id> <request-id> [flags]
```

**Examples**

```bash theme={null}
ankra application build request <application-id> <request-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application build start

Queue a build of the application's image.

`--commit` is required and must be a full 40- or 64-character commit sha. An
abbreviation is refused rather than resolved: the queue deduplicates on the
string it is given, so a full sha and its own prefix would be two keys for one
commit and build it twice.

The queue converges on the commit while a request is live. Asking twice joins
one build, and the answer's already\_requested reports that it did.

With `--wait` the command follows the request through to the finished build and
exits non-zero if the build failed, so a pipeline step can be exactly "build
this commit, and fail if it does not build".

```bash theme={null}
ankra application build start <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application build start <application-id> --commit 9f4a1c2e8b7d6053f1a2b3c4d5e6f708192a3b4c
ankra application build start <application-id> --commit <sha> --ref main --wait
ankra application build start <application-id> --commit <sha> --component api -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--commit` | | Full commit sha to build (required) |
| `--component` | | Component to build, for repositories that build more than one |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the build was asked for: first\_onboard, push, retry (default) or demo |
| `--ref` | | Git ref the commit came from, recorded on the build (e.g. main) |
| `--timeout` | `30m0s` | How long `--wait` waits before giving up on the build |
| `--wait` | `false` | Follow the build until it finishes; exit non-zero if it failed |

## ankra application chart-versions

List an application's published chart versions

```bash theme={null}
ankra application chart-versions <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application code-security

Show source code security findings

```bash theme={null}
ankra application code-security <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application container-security

Show container image vulnerability findings

```bash theme={null}
ankra application container-security <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application credential

Inspect and re-bind the GitHub credential an application's repository calls
ride on.

An application is bound to one GitHub credential of the organisation; its App
installation must reach the repository for builds, deploys and Actions secrets
to work. Move an application onto another credential when its installation
lost - or never had - access to the repository.

## ankra application credential get

Show the GitHub credential an application is bound to

```bash theme={null}
ankra application credential get <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application credential get 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application credential set

Re-bind an application to another GitHub credential of the organisation.

The credential must exist. Whether its App installation reaches the repository
is reported in the answer (resolved / message) rather than refused, since a
re-bind is usually how an application gets off an installation that cannot.

```bash theme={null}
ankra application credential set <application-id> --credential <name> [flags]
```

**Examples**

```bash theme={null}
ankra application credential set 67f4ba9c-2dbe-42e2-8e93-a3431bb464fb --credential github-app-acme
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | GitHub credential of this organisation to bind the application to (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application data-migration

Follow the runs that move an application's data off the vendors it used - a
database, an object store - into services on its cluster, and roll one back.

A run copies the data, makes every vendor source read-only, switches the
application's environment to the in-cluster services in one change, and keeps
the vendor sources read-only for a rollback window. Inside that window,
'ankra application data-migration rollback' puts the previous environment back
and makes the vendor sources writable again. Ankra never deletes data at a
vendor: once the window has closed, the run hands you the teardown checklist.

## ankra application data-migration get

Show one data migration run step by step

```bash theme={null}
ankra application data-migration get <application> <run-id> [flags]
```

**Examples**

```bash theme={null}
ankra application data-migration get shop 6b257030-1d8f-4a9d-92a3-88f346f248bf
ankra application data-migration get shop 6b257030-1d8f-4a9d-92a3-88f346f248bf -o yaml
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application data-migration list

List an application's data migration runs

```bash theme={null}
ankra application data-migration list <application> [flags]
```

**Examples**

```bash theme={null}
ankra application data-migration list shop
ankra application data-migration list shop -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application data-migration rollback

Roll a data migration back: the application's environment goes back to what it
was before the cutover, and every vendor source the run made read-only is made
writable again. Nothing is deleted at the vendor or in the cluster.

A rollback is possible from the moment the cutover starts until the rollback
window closes. The platform records the request and carries it out on its next
pass; follow it with 'ankra application data-migration get'. It is refused
before the cutover (nothing at a vendor changed yet), after the window closed,
for a finished run, and while a rollback is already requested or running.

Requires permission to deploy applications on the run's cluster.

```bash theme={null}
ankra application data-migration rollback <application> <run-id> [flags]
```

**Examples**

```bash theme={null}
ankra application data-migration rollback shop 6b257030-1d8f-4a9d-92a3-88f346f248bf
ankra application data-migration rollback shop 6b257030-1d8f-4a9d-92a3-88f346f248bf --yes -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application delete

Delete an application

```bash theme={null}
ankra application delete <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application demo

Deploy, inspect, and stop short-lived demo workspaces for a branch or pull request of an application.

## ankra application demo build

Check whether a branch has a demo-ready container image

```bash theme={null}
ankra application demo build <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--branch` | | Repository branch to inspect (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo config

Read or update the application's saved demo defaults

## ankra application demo config get

Show the saved demo defaults (env, database, migration command, extensions)

```bash theme={null}
ankra application demo config get <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo config rotate-password

Mint a new shared password for every demo of the application that launches
behind Ankra's edge password guard. The password is printed exactly once: Ankra
keeps only its bcrypt hash and never shows it again. Running demos keep the
previous password until their next redeploy (a pull request push redeploys its
preview). Turn protection on first with 'demo config set `--protected`'.

```bash theme={null}
ankra application demo config rotate-password <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo config set

Update the application's saved demo defaults. The command fetches the
current configuration first and applies only the flags you set: `--env`
entries override by name, everything else is carried forward.

```bash theme={null}
ankra application demo config set <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application demo config set <app-id> --database=true --env DATABASE_URL='${{ ankra.demo_database.url }}'
ankra application demo config set <app-id> --migrate-command 'pnpm run db:migrate' --database-extension vector
ankra application demo config set <app-id> --protected=true   # prints the minted password once
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--database` | `false` | Provision the throwaway per-demo Postgres |
| `--database-extension` | `[]` | Postgres extension the demo database creates at initdb (repeatable; replaces the saved list) |
| `--env` | `[]` | Set an env entry as NAME=VALUE (repeatable; overrides by name) |
| `--migrate-command` | | Command that provisions a fresh demo database's schema (empty clears) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--protected` | `false` | Put every demo behind Ankra's edge password guard (`--protected=false` turns it off); turning it on prints the minted password once |
| `--remove-env` | `[]` | Remove an env entry by name (repeatable) |

## ankra application demo deploy

Deploy a short-lived demo workspace for a branch or pull request.

All flags are optional; only the flags you set are sent, so the backend
applies its own defaults for the rest.

A monorepo demo runs every recorded component as its own pod by default.
`--component` narrows that to the components you name, and the per-component
override flags (`--component-tag`, `--component-port`, `--component-path`) tune
one component each. Because selection and overrides ride the same request
field, an override may only name a component that `--component` selects: to
tune one component of a full launch, list them all.

```bash theme={null}
ankra application demo deploy <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application demo deploy <app-id> --branch feature/login
ankra application demo deploy <app-id> --pr-number 42 --ttl-hours 8
ankra application demo deploy <app-id> --branch main \
  --component crm-frontend --component crm-api \
  --component-port crm-api=8090 --component-path crm-api=/api \
  --entry-component crm-frontend
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--branch` | | Repository branch to deploy |
| `--component` | `[]` | Component of a monorepo to deploy (repeatable; omitted deploys every component) |
| `--component-path` | `[]` | Ingress path prefix for one selected component as NAME=/prefix (repeatable; empty keeps it in-cluster only) |
| `--component-port` | `[]` | Container port for one selected component as NAME=PORT (repeatable) |
| `--component-tag` | `[]` | Image tag for one selected component as NAME=TAG (repeatable) |
| `--container-port` | `0` | Container port to expose |
| `--entry-component` | | Component that owns the demo host's root path (default: the backend's entry heuristic) |
| `--image-tag` | | Explicit container image tag to deploy |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--pr-number` | `0` | Pull request number to deploy |
| `--ttl-hours` | `0` | Lifetime of the demo workspace in hours |

## ankra application demo detail

Show a demo workspace's record, its components, provisioning steps, and
failure detail. The default rendering summarises the demo; -o json or
-o yaml emit the full payload, including the resource inventory and the
Kubernetes events behind a stalled step.

```bash theme={null}
ankra application demo detail <application-id> <workspace-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo fix

Dispatch the AI pre-setup mission for a failed demo

```bash theme={null}
ankra application demo fix <application-id> <workspace-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo fix-build

Fix a branch that has no demo-ready container image.

This is what to run when 'demo build' reports that no image exists for a
branch. Ankra applies its own deterministic fixes first (publish-readiness
auto-fix, failed-run rerun, failed-setup retry) and, when those cannot produce
an image, dispatches a one-shot mission agent that investigates the repository
and opens a pull request with the fix.

The answer points at the dispatched mission rather than carrying its result,
so follow the agent run it names.

```bash theme={null}
ankra application demo fix-build <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application demo build <application-id> --branch feature/checkout
ankra application demo fix-build <application-id> --branch feature/checkout
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--branch` | | Repository branch whose build is missing (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo list

List the application's active demo workspaces, one row each, with the
components every demo runs. -o json or -o yaml emit the full payload,
including the TTL policy and the staging cluster's status.

```bash theme={null}
ankra application demo list <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application demo logs

Fetch a bounded tail of the demo container's logs. One-shot: the command
returns after the fetch instead of following the stream.

A multi-component demo runs one pod per component, and without a selector
the backend reads whichever pod it finds first. `--component` picks the pod
belonging to that component; `--pod` addresses one by name (from
`ankra application demo detail`) when a component has more than one.

```bash theme={null}
ankra application demo logs <application-id> <workspace-id> [flags]
```

**Examples**

```bash theme={null}
ankra application demo logs <app-id> <workspace-id> --tail 500
ankra application demo logs <app-id> <workspace-id> --component crm-api
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--component` | | Read the pod belonging to this component of a multi-component demo |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--pod` | | Read this pod by name (default: the demo's own pod) |
| `--tail` | `200` | Number of log lines from the end |

## ankra application demo stop

Stop and tear down a demo workspace

```bash theme={null}
ankra application demo stop <application-id> <workspace-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application deploy

Deploy a packaged application to a target cluster.

The cluster is identified by ID. Use `--set` key=value (repeatable) to pass
deploy inputs declared by the application's chart.

`--environment` names the environment the deployment belongs to.
`--follow-branches` gives that environment a branch rule from the start, so
pushes to matching branches deploy to it: for example main for production and
develop for development. It needs `--environment`.

```bash theme={null}
ankra application deploy <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application deploy <app-id> --cluster <cluster-id>
ankra application deploy <app-id> --cluster <cluster-id> --namespace prod --set replicas=3
ankra application deploy <app-id> --cluster <cluster-id> --environment production --follow-branches main
ankra application deploy <app-id> --cluster <cluster-id> --environment development --follow-branches develop
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster ID (required) |
| `--environment` | | Environment the deployment belongs to, e.g. production |
| `--follow-branches` | | Comma-separated branch patterns the environment follows, e.g. main or release/\* (needs `--environment`) |
| `--mode` | | Deploy mode: quick or high\_availability |
| `--namespace` | | Target namespace (defaults to the platform default) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--set` | `[]` | Deploy input as key=value (repeatable) |

## ankra application deployments

List an application's cluster deployments

```bash theme={null}
ankra application deployments <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application env-secrets

Manage the environment secrets an application's manifests read.

The keys come from the application's generated manifests. Setting a value
stores it; it is sealed into a running deployment only when you apply it, so a
set followed by no apply changes nothing about the workload.

Values never travel outbound: 'list' reports which keys exist and whether each
has a value, never the value itself.

## ankra application env-secrets apply

Seal the stored environment secrets into the running deployments.

Re-seals the values Ankra already holds into every deployment of the
application and rolls the workloads that read them. It sends nothing: the
values applied are the ones already stored.

The endpoint answers 409 when the request does not apply to this application's
state - nothing set, not deployed yet, tearing down, or a deployment that
cannot be sealed - and the reason is reported as the error message.

```bash theme={null}
ankra application env-secrets apply <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application env-secrets apply 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application env-secrets delete

Clear the stored value of one environment secret.

The key stays declared by the application's manifests; only the value Ankra
holds for it is removed. Deployments already running keep the value that was
sealed into them until the next apply.

```bash theme={null}
ankra application env-secrets delete <application-id> <KEY> [flags]
```

**Examples**

```bash theme={null}
ankra application env-secrets delete <application-id> API_TOKEN
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application env-secrets list

List the environment secret keys an application needs, and their state.

Reports the keys the application's generated manifests declare and whether each
one has a stored value. The values themselves are never returned.

```bash theme={null}
ankra application env-secrets list <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application env-secrets list 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application env-secrets set

Store the value of one environment secret.

Pass the value with `--value`, pipe it on stdin, or omit both to be prompted for
it without echo. Prefer stdin or the prompt: a `--value` on the command line is
recorded in your shell history and, on a shared host, in the process table.

Storing a value does not reach a running workload. Run 'env-secrets apply' to
seal the stored values into the application's deployments and roll them.

```bash theme={null}
ankra application env-secrets set <application-id> <KEY> [flags]
```

**Examples**

```bash theme={null}
ankra application env-secrets set <application-id> DATABASE_URL --value postgres://...

printf '%s' "$TOKEN" | ankra application env-secrets set <application-id> API_TOKEN
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--value` | | Secret value (omit to read stdin or be prompted) |

## ankra application environments

List an application's environments and the branches each one follows.

FOLLOWS shows the environment's branch rule, '\<branch> (tracked)' when it has
no rule and follows the application's tracked branch, or 'manual' when pushes
do not deploy to it.

A branch rule is a list of glob patterns, as in a CI 'branches' filter:
'\*' matches within one path segment, '\*\*' also crosses '/', '!pattern'
removes what earlier patterns matched, the last match wins, and a list that
starts with '!' means every branch except those. An environment without a
rule follows the application's tracked branch.

```bash theme={null}
ankra application environments <application> [flags]
```

**Examples**

```bash theme={null}
ankra application environments my-app
ankra application environments my-app -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application environments set

Set the branches an environment follows, or whether pushes deploy to it.

The environment is named by its name (case-insensitive) or its id, as listed by
'ankra application environments'. `--branches` sets the rule, `--clear` (or
`--branches ""`) removes it so the environment follows the tracked branch again,
and `--enable` or `--disable` turns deploying on push on or off for the
environment. Without `--enable` or `--disable` the environment keeps its current
setting.

Changing a rule never deploys by itself: the next push to a matching branch
does.

A branch rule is a list of glob patterns, as in a CI 'branches' filter:
'\*' matches within one path segment, '\*\*' also crosses '/', '!pattern'
removes what earlier patterns matched, the last match wins, and a list that
starts with '!' means every branch except those. An environment without a
rule follows the application's tracked branch.

```bash theme={null}
ankra application environments set <application> <environment> [flags]
```

**Examples**

```bash theme={null}
ankra application environments set my-app production --branches main
ankra application environments set my-app development --branches develop
ankra application environments set my-app development --branches '**,!main'
ankra application environments set my-app staging --branches 'release/*'
ankra application environments set my-app staging --clear
ankra application environments set my-app production --disable
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--branches` | | Comma-separated branch patterns, e.g. main or 'release/\*' ("" removes the rule) |
| `--clear` | `false` | Remove the branch rule so the environment follows the tracked branch |
| `--disable` | `false` | Stop deploying pushes to this environment |
| `--enable` | `false` | Deploy pushes to this environment |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application files

Commit changes to the application's setup pull request.

Each `--file` maps a repository path to a local file whose contents are
uploaded. Use `--delete` to remove a tracked path.

```bash theme={null}
ankra application files <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application files <app-id> --file Dockerfile=./Dockerfile --message "Update image"
ankra application files <app-id> --delete .ankra/manifests/app.yaml
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--delete` | `[]` | Repository path to delete (repeatable) |
| `--file` | `[]` | Repository path mapped to a local file as path=local-file (repeatable) |
| `--message` | | Commit message |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application get

Show an application's detail

```bash theme={null}
ankra application get <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application import

Import an application from a source that has no Git repository of its own.
Ankra converts what you give it, creates a GitHub repository for it, commits
the result and registers the application, so the same setup pull request,
build and deploy lane that follows every registration takes over.

## ankra application import claude-design

Turn a Claude Design export into a deployable application.

\<path> is what you exported from claude.ai/design: a directory holding the
artboards (\<Name>.dc.html), canvas.json and images, a zip of them, a single
artboard, or a saved canvas page (.html). Ankra converts the artboards into a
static site, creates a GitHub repository under the credential's account (or
`--owner`), commits the site with a Dockerfile, and registers the application.

Artboards that depend on the Claude Design runtime - template holes, sc-for,
sc-if, dc-import or a data-dc-script - are kept as authored and reported as
warnings; they may not render as they did on the canvas.

Running the same import again is safe: the repository keeps a provenance
record, and an unchanged export registers without a second commit.

The lane ships behind the claude\_design\_import organisation feature flag,
which is off by default while it rolls out: the platform answers 404 for
organisations without it, and this command says so. Ask Ankra support to
enable it for your organisation.

```bash theme={null}
ankra application import claude-design <path> [flags]
```

**Examples**

```bash theme={null}
ankra application import claude-design ./neighborly-export --name neighborly
ankra application import claude-design neighborly.zip --credential github-acme --owner acme
ankra application import claude-design Neighborly.html --source-url https://claude.ai/design/p/<id> --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | GitHub credential name or ID (auto-detected when omitted) |
| `--name` | | Application name (defaults to the export's directory or file name) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--owner` | | GitHub user or organisation to create the repository under (defaults to the credential's account) |
| `--repository` | | Repository name (defaults to a slug of the application name) |
| `--source-url` | | The claude.ai/design link the export came from, recorded in the repository |
| `--timeout` | `15m0s` | How long `--wait` waits before giving up |
| `--visibility` | `private` | Repository visibility: private or public |
| `--wait` | `false` | Wait for Ankra to finish analysing the repository, then print the setup pull request |

## ankra application installations

List an application's installation intents

```bash theme={null}
ankra application installations <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application jobs

List an application's platform jobs

```bash theme={null}
ankra application jobs <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `0` | Page number (1-based) |
| `--page-size` | `0` | Page size (1-100) |

## ankra application list

List applications

```bash theme={null}
ankra application list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `0` | Page number (1-based) |
| `--page-size` | `0` | Page size (1-100) |
| `--search` | | Filter applications by name |

## ankra application manifest-addon

Inspect, install and withdraw add-ons published from an application's manifests.

Publish one with 'ankra application publish-addon \<application-id>' and find its
id with 'ankra application published-addon \<application-id>'. These commands
take that add-on id, not an application id.

## ankra application manifest-addon delete

Delete a manifest add-on and undeploy every installation of it.

This is the most consequential of the three and the least reversible: it does
not only withdraw the catalog entry, it undeploys the workloads installed from
it on every cluster. Use 'unpublish' to withdraw the entry and leave those
running.

```bash theme={null}
ankra application manifest-addon delete <addon-id> [flags]
```

**Examples**

```bash theme={null}
ankra application manifest-addon delete <addon-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application manifest-addon diff

Compare two published versions of a manifest add-on.

`--to` names the version to compare; `--from` names what to compare it against,
defaulting to the version published before it. `--path` narrows the comparison to
the named manifests and may be repeated.

```bash theme={null}
ankra application manifest-addon diff <addon-id> [flags]
```

**Examples**

```bash theme={null}
ankra application manifest-addon diff <addon-id> --to 1.4.0
ankra application manifest-addon diff <addon-id> --to 1.4.0 --from 1.2.0 --path deployment.yaml
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from` | | Version to compare against (defaults to the one published before `--to`) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--path` | `[]` | Limit the comparison to this manifest path (repeatable) |
| `--to` | | Published version to compare (required) |

## ankra application manifest-addon get

Show a published manifest add-on: its catalog entry, published versions, and what it declares.

```bash theme={null}
ankra application manifest-addon get <addon-id> [flags]
```

**Examples**

```bash theme={null}
ankra application manifest-addon get 8f2c1b90-4d6e-4a11-9c33-2f7a5b0e91d4
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application manifest-addon install

Install a published manifest add-on onto a cluster.

`--cluster-id` is required. `--namespace` and `--version` default from the add-on's
own descriptor. `--input` answers an input the published manifests declare and
may be repeated as `--input` key=value.

```bash theme={null}
ankra application manifest-addon install <addon-id> [flags]
```

**Examples**

```bash theme={null}
ankra application manifest-addon install <addon-id> --cluster-id <cluster-id>
ankra application manifest-addon install <addon-id> --cluster-id <cluster-id> \
  --namespace commerce --version 1.4.0 --input replicas=3
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster-id` | | Cluster to install the add-on onto (required) |
| `--input` | `[]` | Answer a declared input as key=value (repeatable) |
| `--namespace` | | Namespace to install into (defaults to the add-on's own) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--version` | | Published version to install (defaults to the newest) |

## ankra application manifest-addon unpublish

Withdraw a manifest add-on from the catalog, leaving installations running.

Nobody can install it again afterwards. What is already installed from it keeps
running - use 'delete' if you want those undeployed too.

```bash theme={null}
ankra application manifest-addon unpublish <addon-id> [flags]
```

**Examples**

```bash theme={null}
ankra application manifest-addon unpublish <addon-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application pipeline

Manage the application's pipeline

## ankra application pipeline artifacts

List a pipeline run's stored artifacts

```bash theme={null}
ankra application pipeline artifacts <application-id> <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cursor` | | Page cursor from a previous listing's next\_cursor |
| `--limit` | `0` | Maximum number of artifacts to return (server default 50, max 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pipeline artifacts download

Download a stored artifact

```bash theme={null}
ankra application pipeline artifacts download <application-id> <artifact-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--out` | | Local file to write the artifact to (default: the artifact id, in the current directory) |

## ankra application pipeline cancel

Cancel a pipeline run that has not concluded.

A run that had started stops its main and on\_failure stages, then runs its
finally stages before it concludes cancelled. While they run the run reads
"running" and "cancelling". A run that never started concludes at once.

`--force` skips the finally stages: the run concludes cancelled at once. On a
run that is already cancelling it stops the finally stages still running.
Cancelling such a run again without `--force` is refused.

```bash theme={null}
ankra application pipeline cancel <application-id> <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Skip the run's finally stages, or stop them if the run is already cancelling |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pipeline convert

Convert an application that still builds from a GitHub Actions workflow onto
Ankra Pipelines, with one call.

Ankra reads the workflow, converts it to a .ankra/pipeline.yaml, stores that as
the application's pipeline definition of record and builds the next push
through it. It switches the generated workflow off on GitHub so the two never
build the same commit twice, and opens a pull request that commits the pipeline
file and removes Ankra's generated workflow file. A workflow the repository
wrote itself is never touched. Nothing about building waits on the pull
request merging.

`--keep-workflows` leaves the generated workflow file in the repository (it stays
switched off). Calling again while the pull request is still open answers the
same conversion; an application already on Ankra Pipelines is refused with
nothing to convert.

```bash theme={null}
ankra application pipeline convert <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application pipeline convert <application-id>
ankra application pipeline convert <application-id> --keep-workflows
ankra application pipeline convert <application-id> -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--keep-workflows` | `false` | Leave Ankra's generated workflow file in the repository instead of removing it in the pull request |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pipeline definition

Manage the application pipeline's definition of record

## ankra application pipeline definition get

Show the pipeline definition of record

```bash theme={null}
ankra application pipeline definition get <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pipeline definition put

Store a pipeline definition as the definition of record

```bash theme={null}
ankra application pipeline definition put <application-id> <file> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pipeline get

Show a pipeline run's detail - or wait for it to conclude, or watch it.

Name the run by its id, or select it by what you know about it. Push and pull
request runs are started by the webhook, so a CI job or an agent usually knows
the commit rather than the run id: `--head-sha`, `--branch` and `--trigger` narrow
the pipeline's runs the way 'pipeline list' filters them. Exactly one match is
that run; when several match, `--latest` takes the newest, and without it the
command lists them instead of guessing. `--latest` on its own is the pipeline's
newest run.

`--wait` blocks until the run concludes, then prints its final detail. `--watch`
prints every state change of the run and of each of its steps as it is seen,
until the run concludes; with -o json each change is one JSON object on its
own line, carrying the run or step as the platform answered it. `--timeout`
bounds either one; without it they wait as long as the run takes. When a
selection matches no run yet, `--wait` and `--watch` wait for one to appear - the
webhook that creates it can land a moment after you ask - for up to
`--timeout`, or ten minutes when no `--timeout` is set.

Exit codes: 0 when the run succeeded; 1 when it concluded any other way, or
the platform could not be read; 2 when a selection matches several runs and
`--latest` was not given; 3 when nothing matches; 5 when `--timeout` ran out or,
with `--exit-code`, when the run has not concluded yet. Without `--wait`, `--watch`
or `--exit-code` the command exits 0 whatever the run's outcome, as it always
has.

Status and outcome (-o json): 'status' is the lifecycle, never the verdict.
A run's status is queued, running or concluded; a step's is blocked (waiting
on its dependencies), pending (ready, not yet claimed), running or concluded.
How the work ended is the separate 'outcome' field, which is null until the
status is concluded and then always one of: success, failure (the work
itself failed), cancelled, timed\_out, skipped (it never ran - a dependency
did not succeed, a condition or the trigger filter excluded it) or
infra\_error (Ankra failed, not the work). The same two fields with the same
vocabulary sit on the run and on each step, mirroring GitHub Actions'
status/conclusion split - so a monitor that filters on status finds every
finished run under concluded, and must read outcome for whether it passed.
The human-readable Status line and STATUS column print the outcome once
there is one and the status until then, with a glyph that says which:
✓ success, ✗ failure / timed\_out / infra\_error, ⊘ cancelled, ○ skipped, and
⟳ only for a run or step that has not concluded (○ for a blocked step).

Superseded runs: a run cancelled because a NEWER run took its concurrency
group reads 'superseded' rather than 'cancelled' - on the Status line, in
the STATUS column, on the last line of `--watch` and in the conclusion `--wait`
reports - and 'pipeline get' names the run that took its place. Nobody
stopped that run, and the run worth looking at is the newer one. Only the
word differs: `--wait`, `--watch` and `--exit-code` exit 1 for a superseded run as
for any cancelled one. In -o json the fields are 'error\_class'
("superseded"), 'superseded\_by\_run\_id' and 'superseded\_by\_run\_number';
'outcome' stays "cancelled", so a script filtering on outcome alone still
finds these runs and must read the class to tell them from a run somebody
cancelled.

Cancelled runs (-o json 'cancelled\_by', 'cancel\_reason', 'cancelled\_at';
the Cancelled line): who stopped a run, why and when. 'cancelled\_by' is the actor
in the same form 'requested\_by' uses - "user:\<id>" for a cancel pressed in
the portal, the CLI or the API, "github:\<login>" for the Cancel action on a
pull request's check run, "concurrency:\<run id>" for a supersession,
"merge\_train:\<entry id>" for the merge train - and 'cancel\_reason' is one of:

```text theme={null}
user_requested       somebody cancelled it in the portal, the CLI or the API
source_control       the Cancel action on its check run
superseded           a newer run took its concurrency group
queued_replaced      a newer commit replaced it before it started
merge_train          the merge train no longer needed this change tested
pull_request_closed  its pull request merged or closed (no actor)
step_cancelled       nobody cancelled it: a step was stopped where it ran,
                     for example when the cluster's agent shut down, and
                     the Error line carries that step's sentence (no actor)
```

superseded, queued\_replaced and merge\_train runs read 'superseded' (above).
A reason this list does not name yet is printed as it is.
All three fields are null for a run nobody cancelled and for one cancelled
before Ankra recorded this, which is "not recorded", never "the platform
did it".

Steps that never started (error\_class "never\_scheduled"): a step whose time
ran out while no node had room for what it requests concludes timed\_out,
and so does its run, but nothing ran. The Class line says so; free capacity
on the cluster, add a node, or lower the stage's resources, then rerun.

Authority (-o json 'authority\_state', the Authority line): the protected
authority the run executed under. 'approved' - the default branch's
definition declares no protected section, or an administrator approved
exactly what it declares, and the head changes nothing. 'unapproved' - a run
of the default branch whose definition changed authority no administrator
has approved yet; it executes under the last approved authority, or under
none when nothing was ever approved. 'changed\_on\_head' - a run of another
branch or a pull request whose definition declares different authority; it
executes under the default branch's, and the head's change is ignored and
reported. null - the planner never resolved authority for this run: it is
still queued, it concluded skipped because its trigger filter excluded every
stage before planning, or it was planned before authority was recorded.
null is "not recorded", never "no authority".

```bash theme={null}
ankra application pipeline get <application-id> [run] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--branch` | | Select the run for this trigger branch instead of naming its id |
| `--exit-code` | `false` | Exit 1 when the run concluded without succeeding, and 5 while it has not concluded (`--wait` and `--watch` always exit this way) |
| `--head-sha` | | Select the run for this full commit sha instead of naming its id |
| `--latest` | `false` | Take the newest matching run when several match (on its own: the pipeline's newest run) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--step` | | Also print the per-cache table of the step with this key: each cache's outcome, reason, size and save |
| `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) |
| `--trigger` | | Select the run with this trigger: push, pull\_request, tag, schedule, manual, api, agent, or rerun |
| `--wait` | `false` | Wait for the run to conclude, then print its final detail; exits non-zero unless it succeeded |
| `--watch` | `false` | Print each run and step state change as it happens until the run concludes (-o json: one JSON object per line) |

## ankra application pipeline list

List the application's pipeline runs

```bash theme={null}
ankra application pipeline list <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | With `--latest-per-branch`, include branches with no run in the last 14 days |
| `--branch` | | Filter by trigger branch |
| `--cursor` | | Page cursor from a previous listing's next\_cursor |
| `--head-sha` | | Filter by the exact full commit sha |
| `--latest-per-branch` | `false` | List one row per branch with the newest run on each, the table 'ankra pipeline branches' prints |
| `--limit` | `0` | Maximum number of runs to return (server default 50, max 100); with `--latest-per-branch`, the number of branches (server default 20) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | | Filter by run status: queued, running, or concluded |
| `--trigger` | | Filter by trigger: push, pull\_request, tag, schedule, manual, api, agent, or rerun |

## ankra application pipeline logs

Show a pipeline step's output

```bash theme={null}
ankra application pipeline logs <application-id> <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--follow` | `false` | Wait for the step to start if it has not, then keep streaming, reconnecting through transient stream faults, until it concludes; for a step on Ankra's platform builders, which has no live stream, wait for it to conclude and print its archived log |
| `--replay` | `false` | Also show the output a running step produced before this command connected (a concluded step's log is always shown whole) |
| `--step` | | Step key to follow (required when the run has more than one step), or the id of one attempt of it as 'ankra pipeline get' prints for a retried step |

## ankra application pipeline rerun

Open a new run from a run that already happened.

The new run is a fresh run, not a retry of the old one: the old run's outcome
stays the record of what happened. The new run is recorded with trigger
'rerun', and 'rerun\_of\_run\_id' ties the two together.

A re-run repeats the original event. A re-run of a push run is planned as a
push, so its push-only stages run. A re-run of a pull request run (or of a
merge train car) is planned as a pull request, and a re-run of a schedule run
as that schedule. A re-run of a tag run or of a manual or API dispatch is
planned as a plain re-run, so stages limited to other events are skipped.

A re-run's publish pushes the sha- image, but that image does not become the
push-to-deploy candidate, so a re-run does not roll the deployment.

`--failed-only` restricts the new run to the steps that failed, the steps that
were skipped because of a failure, whatever depends on them, and the steps
they build on. The new run starts from an empty workspace, so the checkout and
every upstream step whose output a repeated step reads run again with it;
steps that succeeded and that nothing repeated needs do not. A failed-only
re-run that would still skip one of those steps (for example a tag-only
release behind a failed build, on a re-run of a tag run) is refused with the
reason rather than passing without it.

`--full` sets the pipeline's path filters aside for the new run, so every stage
whose filters left it out runs, and the run records that you asked. A re-run
of a run that was already a full run is one again without the flag.

```bash theme={null}
ankra application pipeline rerun <application-id> <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--failed-only` | `false` | Re-run only the steps that did not succeed, whatever depends on them, and the steps they build on (checkout included) |
| `--full` | `false` | Run every stage: set the pipeline's path filters aside for the new run |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) |
| `--wait` | `false` | Wait for the new run to conclude before returning |

## ankra application pipeline run

Dispatch a manual run of the application's pipeline

```bash theme={null}
ankra application pipeline run <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--full` | `false` | Run every stage: set the pipeline's path filters aside for this run |
| `--input` | `[]` | Dispatch input as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Human note recorded on the run |
| `--ref` | | Git reference to run at (defaults to the repository's default branch) |
| `--sha` | | Full commit sha to run (defaults to HEAD of a checkout of this pipeline's repository, else the tip of `--ref`) |
| `--spec-file` | | Run this pipeline definition instead of the stored one (requires pipelines.manage) |
| `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) |
| `--wait` | `false` | Wait for the run to conclude before returning |

## ankra application pipeline schedules

Manage the application pipeline's cron schedules

## ankra application pipeline schedules create

Add a cron schedule

```bash theme={null}
ankra application pipeline schedules create <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cron` | | Cron expression (required) |
| `--enabled` | `true` | Whether the schedule fires |
| `--input` | `[]` | Dispatch input as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ref` | | Git reference the schedule runs at (default the repository's default branch) |
| `--timezone` | | IANA timezone the cron is evaluated in (default UTC) |

## ankra application pipeline schedules delete

Remove a cron schedule

```bash theme={null}
ankra application pipeline schedules delete <application-id> <schedule-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application pipeline schedules list

List the pipeline's cron schedules

```bash theme={null}
ankra application pipeline schedules list <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pipeline schedules update

Change a cron schedule

```bash theme={null}
ankra application pipeline schedules update <application-id> <schedule-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cron` | | New cron expression |
| `--disabled` | `false` | Disable the schedule |
| `--enabled` | `false` | Enable the schedule |
| `--input` | `[]` | Replace the dispatch inputs entirely, as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ref` | | New git reference |
| `--timezone` | | New IANA timezone |

## ankra application pipeline validate

Dry-run a pipeline definition without writing anything

```bash theme={null}
ankra application pipeline validate <application-id> [file] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--changed-file` | `[]` | Plan as if this repository-relative path changed (repeatable), so path filters decide instead of passing |
| `--no-local-graph` | `false` | Do not read the dependency graph of the local checkout for affected: stages |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ref` | | Read the definition from this git reference in the current checkout (for example origin/my-branch) instead of the working tree |
| `--spec-file` | | Validate this definition file, the same as passing it as the argument |

## ankra application platform

Detect platform operators already present on a target cluster

```bash theme={null}
ankra application platform <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application protect

Protecting a deployment writes its whole backup policy: the vault, the
schedule, the retention and which volumes are carried. Running it again
replaces the policy that is there, so restate `--schedule`, `--retention` and
`--include-pvc` when they must survive; anything omitted takes the default,
not the previous value.

Turn scheduled backups on for one of an application's deployments.

The deployment is named by the cluster it runs on; Ankra resolves which stack
that is. Without `--vault` the organisation's single verified backup vault is
used, and an organisation with more than one is refused rather than chosen
for - where a restore point lives is not a decision to make on somebody's
behalf.

```bash theme={null}
ankra application protect <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application protect shop --cluster production
ankra application protect shop --cluster production --vault production-backups --backup-now
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--backup-now` | `false` | Take the first restore point immediately instead of waiting for the schedule |
| `--cluster` | | Cluster the deployment runs on (name or id, required) |
| `--confirm-exclude-databases` | `false` | Acknowledge that `--exclude-databases` means no database contents are carried |
| `--exclude-databases` | `false` | Leave this stack's database contents out of the capture |
| `--include-pvc` | `[]` | Persistent volume claim to carry, as namespace/name (repeatable). Volumes are carried only where named |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--retention` | | Restore points to keep, as key=value pairs: hourly, daily, weekly, monthly, yearly, minimum-count, minimum-age (for example daily=7,weekly=4,monthly=6); the platform default when omitted |
| `--schedule` | | hourly, daily, weekly, or a five-field cron expression (daily when omitted) |
| `--vault` | | Backup vault the restore points are written to (name or id; the organisation's only ready vault when omitted, refused when it has several) |

## ankra application provenance

An application can refuse to deploy an image unless the image carries signed
provenance showing it passed this organisation's pipeline gate. A pipeline's
publish step signs a statement about every image it publishes; the deploy
verifies it before rolling the image.

Modes:

```text theme={null}
off      nothing is checked at deploy, exactly as before
warn     every image in the application's registry is checked; the deploy
         goes ahead whatever the result, and an image that is not verified
         files a finding on the application's installation
enforce  the deploy is refused unless every image in the application's
         registry carries a valid attestation from this organisation's
         pipeline, and each verified image is pinned to its digest
```

An application's own mode wins; without one it follows the organisation default
('ankra org provenance'), and without that Ankra's default applies.

Third-party images (a public database image, a chart's sidecar) are outside the
application's registry, so they are listed as unchecked and never refused.

## ankra application provenance get

Show the mode deploys of the application run under, whether it is the
application's own setting, the organisation default or Ankra's default, and what
that mode means for rollbacks.

To see what the next deploy of specific images would do, use
'ankra application provenance verify'.

```bash theme={null}
ankra application provenance get <application> [flags]
```

**Examples**

```bash theme={null}
ankra application provenance get shop
ankra application provenance get 23298741-6a5a-401a-a681-66f31fbdebe1 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application provenance set

Set the mode deploys of the application run under, or clear the application's
own choice with `--clear` so it follows the organisation default again. Needs the
security.manage permission.

Modes:

```text theme={null}
off      nothing is checked at deploy, exactly as before
warn     every image in the application's registry is checked; the deploy
         goes ahead whatever the result, and an image that is not verified
         files a finding on the application's installation
enforce  the deploy is refused unless every image in the application's
         registry carries a valid attestation from this organisation's
         pipeline, and each verified image is pinned to its digest
```

Turn warn on first and read the findings: an application whose images are built
outside Ankra pipelines is unsigned, and enforce would refuse every deploy of
it. Set enforce once the images you would deploy, and the rollback targets you
might need, were published by a pipeline run that attests them.

Under enforce, versions published before the first attested publish cannot be
deployed or rolled back to. Switching to warn lifts that; this command asks
before turning enforce on (`--yes` skips the question).

```bash theme={null}
ankra application provenance set <application> --mode off|warn|enforce [flags]
```

**Examples**

```bash theme={null}
ankra application provenance set shop --mode warn
ankra application provenance set shop --mode enforce --yes
ankra application provenance set shop --clear
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Clear the application's own mode so it follows the organisation default |
| `--mode` | | Provenance mode: off, warn or enforce |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation asked before turning enforce on |

## ankra application provenance verify

Verify images the way a deploy would and report what a deploy under the
application's mode would do, without deploying anything or filing a finding.

Each image is checked for a signed attestation from this organisation's
pipeline: that it exists, that its signature verifies against a key the
organisation trusts, and that it names this application, repository and digest.
Images outside the application's registry are listed as unchecked and are never
refused. An image that could not be checked (the registry or key store did not
answer) is reported as unknown, never as refused.

The decision is one of: deploy, deploy\_with\_finding (warn, an image is not
verified), refuse (enforce, an image is not verified) or not\_checked (off).
The command exits 1 when the decision is refuse, so it can gate a script.

```bash theme={null}
ankra application provenance verify <application> --image <ref> [--image <ref>...] [flags]
```

**Examples**

```bash theme={null}
ankra application provenance verify shop --image registry.ankra.cloud/org-1234/shop:sha-1a2b3c4
ankra application provenance verify shop --image <current> --image <rollback target> -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--image` | `[]` | Image reference to verify (repeatable, 1 to 32) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application publish-addon

Publish the application's generated manifests to the organisation
catalogue as a manifest add-on. Publishing again with a new `--version` adds
a version; other clusters install the add-on from the catalogue.

```bash theme={null}
ankra application publish-addon <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application publish-addon <application-id> \
  --version 1.2.0 --display-name "Website" --category web --changelog "TLS defaults"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--category` | | Catalogue category |
| `--changelog` | | Changelog note for this version |
| `--description` | | Catalogue description |
| `--display-name` | | Catalogue display name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--version` | | Add-on version to publish (defaults from the descriptor) |

## ankra application publish-readiness

Report whether the repository can publish to the private Ankra registry

```bash theme={null}
ankra application publish-readiness <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application published-addon

Show the add-on this application published to the catalogue

```bash theme={null}
ankra application published-addon <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application pull-request-reviews

Show the AI reviews of the application's pull requests

```bash theme={null}
ankra application pull-request-reviews <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `0` | Maximum number of reviews (1-20) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application reconcile

Request an application refresh

```bash theme={null}
ankra application reconcile <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application registry

Inspect and set the container image registry an application publishes to.

An application with no declaration publishes into the organisation's own Ankra
registry project. Declare a registry you already operate to have Ankra read
image tags, verify builds, and pull demo images from there instead.

## ankra application registry clear

Return an application to the organisation's own Ankra registry.

Clears the declaration, so the application publishes into - and is read back
from - the organisation's provisioned registry project again.

```bash theme={null}
ankra application registry clear <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry clear 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application registry get

Show the image registry an application publishes to.

Reports the stored declaration, whether it is one at all, the host and project
it resolves to, and the image repository each component is expected to publish
to - so you can compare them against where your builds actually push.

```bash theme={null}
ankra application registry get <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry get 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application registry robot

Manage the registry robot account minted for an application.

Ankra mints one push robot per application on the registry it publishes to,
stores it as a managed registry credential, and writes it into the repository's
Actions secrets as the login the build workflow uses. On the organisation's own
Ankra registry that happens automatically; on a registry you operate it needs
the declaration to name a credential with project administrator rights
(ankra application registry set `--admin-credential`).

## ankra application registry robot ensure

Mint the application's registry robot if it has none, and store its login in
the repository's Actions secrets.

An application that already has a robot keeps it; only its login is re-written
into the repository. A registry Ankra may not administer answers with
provisioned false and a message naming what would let it.

```bash theme={null}
ankra application registry robot ensure <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry robot ensure 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application registry robot get

Show the registry robot account minted for an application.

Reports whether a robot backs the application's registry login, its name, the
registry it lives on, when it was created and last rotated - and when none
does, why, and what would let Ankra mint one. Never contacts the registry.

```bash theme={null}
ankra application registry robot get <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry robot get 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application registry robot revoke

Delete the application's registry robot from the registry and drop the
credential holding its login.

The repository's Actions secrets are left holding a login that no longer works,
which is the point of a revoke; run 'ensure' afterwards to mint a fresh robot
and store it. Prefer 'rotate' when the application should keep working.

```bash theme={null}
ankra application registry robot revoke <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry robot revoke 23298741-6a5a-401a-a681-66f31fbdebe1 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application registry robot rotate

Rotate the application's registry robot secret and store the new login in the
repository's Actions secrets.

The previous secret stops working the moment the registry answers, which makes
this the response to a leaked repository secret. A build that starts before the
new login is stored fails at the registry login; re-run it afterwards. An
application with no robot yet gets one minted.

```bash theme={null}
ankra application registry robot rotate <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry robot rotate 23298741-6a5a-401a-a681-66f31fbdebe1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application registry set

Point an application at a container image registry you operate.

`--url` is the registry project, as oci://\<host>/\<project> (the scheme is
optional). `--credential` names an existing registry credential of this
organisation; without one Ankra can describe where the images live but cannot
read or pull them, so builds keep reporting as never published.

Ankra never mints robots for a registry it was not handed the keys to. Name a
credential with project administrator rights as `--admin-credential` to have
Ankra mint, rotate and revoke a push robot for the application there and
store it in the repository's Actions secrets; without one it leaves the
secrets to you unless you ask it to write the declared credential with
`--manage-actions-secrets`.

With `--admin-credential` Ankra also checks that the project exists before it
accepts the declaration. A project the registry does not have is created with
that credential - private, or public with `--project-public` - when the
credential may create projects; otherwise the declaration is refused with the
project and host named, instead of being accepted for every later build to
fail against. Without `--admin-credential` the project is not checked.

```bash theme={null}
ankra application registry set <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra application registry set 23298741-6a5a-401a-a681-66f31fbdebe1 \
  --url oci://artifact.example.com/commerce --credential example-harbor

ankra application registry set <application-id> \
  --url artifact.example.com/commerce --credential example-harbor \
  --username-secret HARBOR_USERNAME --password-secret HARBOR_PASSWORD

ankra application registry set <application-id> \
  --url oci://artifact.example.com/commerce --credential example-harbor-pull \
  --admin-credential example-harbor-admin

# Create the project on the registry if it is missing, and make it public
ankra application registry set <application-id> \
  --url oci://artifact.example.com/collector --credential example-harbor-pull \
  --admin-credential example-harbor-admin --project-public
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--admin-credential` | | Registry credential with project administrator rights, for Ankra to mint the application's robot |
| `--api-url` | | Registry management API base (defaults to https\://\<host>) |
| `--component-repository` | `[]` | Repository inside the project for one component, as \<component>=\<repository> (repeatable) |
| `--credential` | | Registry credential of this organisation that authenticates to it |
| `--flat-repositories` | `false` | Publish monorepo components as \<project>/\<component> instead of \<project>/\<app>/\<component> |
| `--manage-actions-secrets` | `false` | Let Ankra write the named credential into the repository's Actions secrets |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--password-secret` | | Repository Actions secret holding the registry password |
| `--project-public` | `false` | With `--admin-credential`: create the project public when the registry does not have it yet (default: private) |
| `--pull-secret` | | Name of the dockerconfigjson Secret generated manifests reference |
| `--url` | | Registry project as oci://\<host>/\<project> (required) |
| `--username-secret` | | Repository Actions secret the build workflow logs in with |

## ankra application remove

Remove an application from one cluster, leaving the application and its other
deployments in place.

Ankra uninstalls the application's workloads in that cluster and namespace -
and with them any data in that deployment's database and volumes - and
deletes the installation once the cluster has it. The application, its
settings, secrets, images and release history, and its deployments on other
clusters stay, so you can deploy it there again.

An application deployed with the deploy wizard has no installation: it runs as
a stack. Name that stack with `--stack` and Ankra removes it from the cluster.
The other stacks that deploy created stay, and the command lists them.

The removal runs in the background: 'ankra application installations' shows the
deployment as "removing" until it is gone, or "failed" with the reason. A
stack's removal is a platform job: 'ankra application jobs' shows its
undeploy\_application job, "success" once the stack is gone or "failed" with
the reason.

To stop it for a while without losing anything, park it instead. To delete the
application everywhere, use 'ankra application delete'.

```bash theme={null}
ankra application remove <application> --cluster <cluster> [--namespace <namespace> | --stack <stack>] [flags]
```

**Examples**

```bash theme={null}
ankra application remove shop --cluster staging
ankra application remove shop --cluster production --namespace shop-prod --yes
ankra application remove shop --cluster staging --stack shop-web
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster to remove the application from (name or id, required) |
| `--namespace` | | Namespace of the deployment (needed only when the application runs in more than one namespace on that cluster) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stack` | | Stack a deploy-wizard deployment runs as (for an application deployed with the deploy wizard, which has no installation) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra application rerun-workflow

Re-trigger a failed workflow run

```bash theme={null}
ankra application rerun-workflow <application-id> <run-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application retry

Re-trigger a failed application's setup

```bash theme={null}
ankra application retry <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application security-versions

List the tags the application has published, joined to the bill of
materials and vulnerability findings the platform holds for each, and the
clusters running it now. A tag with no report reads "not scanned", which
is not the same as clean, and a registry the platform could not list reads
unavailable rather than empty.

The licence verdict at the end says whether a private repository links a
component whose licence obliges publishing the source (AGPL, SSPL and the
other network copyleft licences) or a commercial licence to host as a
service.

`--component` narrows a monorepo to one image.

```bash theme={null}
ankra application security-versions <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--component` | | Narrow a monorepo to one component (image) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application settings

Inspect and set the organisation's application CI settings.

These apply to every application in the organisation, not to one of them. The
CI runner label decides which GitHub Actions runner the pipelines Ankra
generates request - change it when GitHub-hosted runners are unavailable to
you and your builds run on self-hosted ones.

## ankra application settings get

Show the organisation's application CI settings.

Readable by any member: a member who cannot explain why a build never started
is the reason this setting exists.

```bash theme={null}
ankra application settings get [flags]
```

**Examples**

```bash theme={null}
ankra application settings get
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application settings set

Set or clear the GitHub Actions runner label generated pipelines run on.

Pass `--ci-runner-label` to choose the label, or `--clear` to drop the
organisation's choice and put every future generation back on the default.
Existing pipelines are not rewritten by either.

Only organisation admins may change this.

```bash theme={null}
ankra application settings set [flags]
```

**Examples**

```bash theme={null}
ankra application settings set --ci-runner-label self-hosted
ankra application settings set --clear
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--ci-runner-label` | | GitHub Actions runner label generated pipelines request |
| `--clear` | `false` | Drop the organisation's choice and return to the default runner |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application ship

Take a local checkout to a live deployment in one command.

Ship composes the existing application lanes: it registers the repository as
an application when the organisation does not have it yet (with exactly the
'application add' flags), waits for the setup analysis, waits for a green
image build of the tracked branch, deploys to the target cluster, and follows
the installation until the workload is running - then prints the published
URL when one exists. The URL is printed as Live only once the Ingress that
carries it is shown to route: every backend Service it names exists, exposes
the port asked for and has a ready endpoint. A backend that does not resolve
fails ship with what is wrong (state "unroutable" in -o json, with
url\_problem); a route ship cannot read is reported and left unverified.

An existing application is reused only when it is registered for the same
repository AND tracks the requested branch (`--branch`, else the checkout's
branch); ship never builds or deploys a branch other than the one requested.
When the repository's applications all track other branches, ship stops and
names them: pass `--name` \<app> `--branch` \<its branch> to ship one of them, or
`--name` \<new-name> to register a separate application for the branch. `--name`
selects among several applications on the same branch.

The build it waits for is the one that actually builds the application:

* Ankra Pipelines (the default for new applications): the pipeline run for
  the tracked branch's head commit, until its publish steps succeed. When no
  run for that commit appears within a minute - nothing has been pushed
  since the application was registered - ship starts the branch's push run
  for it, the run a push would have started, which publishes the image.
  That needs the applications.deploy permission. A push during the wait
  moves ship on to the new head commit. A run whose publish step is skipped
  stops ship and asks for a push. A run the pipeline skipped outright - no
  trigger it declares accepts the push, typically because the setup pull
  request that adds .ankra/pipeline.yaml is not merged yet - stops ship
  with the pull request to merge, or the trigger the branch needs.
* The repository's own GitHub Actions workflow: its latest run on the
  tracked branch.
* The workflow Ankra generated: its latest run on the tracked branch, once
  you have merged the setup pull request that adds it. Only this lane waits
  on the merge.

Every wait step says what it is waiting on and where to look. Re-running ship
is safe at any point: it re-reads where the flow actually is and continues
from there, so an interrupted or timed-out run is resumed, not repeated.

With `--ankra-build` the first image is built on Ankra's builders from the head
commit of the tracked branch, so ship does not wait for the setup pull
request to merge or for the repository's own CI. The platform-build routes
answer 404 for organisations without the platform\_builds feature flag.

The image tag and ingress publication are the platform's defaults: the latest
green build is deployed, and ingress is derived server-side. Pass `--set` only
for deploy inputs you want to pin.

```bash theme={null}
ankra application ship [path] [flags]
```

**Examples**

```bash theme={null}
ankra application ship .
ankra application ship . --cluster production
ankra application ship ./services/payments --cluster staging --namespace payments
ankra application ship . --cluster staging --ankra-build --set replicas=2 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--ankra-build` | `false` | Build the first image on Ankra's builders instead of waiting for the setup PR merge and repository CI |
| `--branch` | | Repository branch (auto-detected when omitted) |
| `--cluster` | | Target cluster name or ID (defaults to the selected cluster, echoed before acting) |
| `--credential` | | GitHub credential name or ID (auto-detected when omitted) |
| `--name` | | Application name (defaults to the repository name) |
| `--namespace` | | Target namespace (defaults to the namespace the platform derives from the application name) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--registry-admin-credential` | | Registry credential with project administrator rights, for Ankra to mint the application's robot |
| `--registry-api-url` | | Registry management API base (defaults to https\://\<host>) |
| `--registry-component-repository` | `[]` | Repository inside the project for one component, as \<component>=\<repository> (repeatable) |
| `--registry-credential` | | Registry credential of this organisation that authenticates to it |
| `--registry-flat-repositories` | `false` | Publish monorepo components as \<project>/\<component> instead of \<project>/\<app>/\<component> |
| `--registry-manage-actions-secrets` | `false` | Let Ankra write the named credential into the repository's Actions secrets |
| `--registry-password-secret` | | Repository Actions secret holding the registry password |
| `--registry-pull-secret` | | Name of the dockerconfigjson Secret generated manifests reference |
| `--registry-url` | | Registry project the application publishes to, as oci://\<host>/\<project> |
| `--registry-username-secret` | | Repository Actions secret the build workflow logs in with |
| `--remote` | `origin` | Git remote used to identify the GitHub repository |
| `--set` | `[]` | Deploy input as key=value (repeatable) |
| `--set-up-database` | `false` | Let Ankra install PostgreSQL support (the CloudNativePG operator) on the cluster when the application's database needs it and the cluster has none |
| `--timeout` | `1h0m0s` | Overall budget for every wait step combined |
| `--wait` | `false` | Wait for Ankra to finish analysing the repository, then print the setup pull request |

## ankra application upgrade-workflow

Add security scanning steps to the build workflow

```bash theme={null}
ankra application upgrade-workflow <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application workflow-run-jobs

List the jobs of a workflow run

```bash theme={null}
ankra application workflow-run-jobs <application-id> <run-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra application workflow-runs

List the application's GitHub Actions workflow runs

```bash theme={null}
ankra application workflow-runs <application-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `0` | Page number (1-based) |
| `--page-size` | `0` | Page size (1-50) |
| `--status` | | Filter by GitHub run status |


# ankra backup
Source: https://docs.ankra.ai/reference/cli/backup

Backup operations

## ankra backup

Commands for managing the organisation's backup infrastructure.

## ankra backup restore-points

List the organisation's restore points across every cluster

## ankra backup restore-points list

List every restore point the organisation holds, newest first, across
every cluster and stack.

Examples:

```bash theme={null}
ankra backup restore-points list
ankra backup restore-points list --cluster production --status complete
ankra backup restore-points list --stack shop
```

```bash theme={null}
ankra backup restore-points list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only restore points taken from this cluster (name or id) |
| `--cursor` | | Continue from a previous page's cursor |
| `--limit` | `0` | Page size (server default, maximum 200) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stack` | | Only restore points taken of this stack |
| `--status` | `[]` | Only restore points in these statuses (creating, complete, failed, expiring, expired, deleted) |
| `--trigger` | `[]` | Only restore points with these triggers (manual, scheduled, clone, migrate, pre\_restore, verification) |
| `--vault` | | Only restore points in this backup vault (name or id) |

## ankra backup vaults

Manage the organisation's backup vaults: S3-compatible object-storage targets that cluster backups are written to. The platform verifies each vault's credentials against its bucket and reports the outcome as the vault's status.

## ankra backup vaults contents

List what a backup vault's bucket actually holds, per restore point.

This reads the object store, not Ankra's rows, so it can disagree with the
platform - which is the point. Use it to confirm that deleting a restore point
removed its objects, and to find objects no restore point accounts for.

Two prefixes are reported per restore point because they differ:

```text theme={null}
declared  the prefix the restore point records, and that a delete sweeps
located   where the objects actually are, written by the backup data plane
```

Volume data lives in a SHARED repository per cluster and namespace. Its bytes
are reported separately and never counted into a single restore point: the
blocks are deduplicated across every backup of that namespace, so no restore
point owns them and deleting the prefix would destroy other restore points'
data.

A vault whose bucket cannot be read fails with an error rather than printing an
empty listing. An unreadable vault and an empty vault are different facts.

```bash theme={null}
ankra backup vaults contents [vault-name|vault-id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--objects` | `false` | List every object key the listing read |
| `--orphans-only` | `false` | Print only the objects no restore point accounts for |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--prefix` | | Only read objects under this prefix (narrows a large vault; orphan detection is withheld for a partial read) |
| `--restore-point` | | Report only this restore point (accepts an id prefix) |

## ankra backup vaults create

Create a backup vault: an S3-compatible bucket cluster backups are written to.

The access keys are prompted for interactively when not passed as flags, so
they never have to appear in your shell history. The platform verifies the
keys against the bucket immediately and the command reports the outcome.

Example:

```bash theme={null}
ankra backup vaults create offsite --endpoint https://s3.example.com --bucket cluster-backups
```

```bash theme={null}
ankra backup vaults create <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--access-key-id` | | Access key ID (prompted for when omitted) |
| `--bucket` | | Bucket the backups are written to (required) |
| `--endpoint` | | S3-compatible endpoint URL (required) |
| `--path-style` | `true` | Address the bucket path-style ([https://endpoint/bucket](https://endpoint/bucket)) instead of virtual-hosted-style |
| `--provider` | `other` | Object-storage provider |
| `--region` | | Bucket region (leave empty when the endpoint implies it) |
| `--secret-access-key` | | Secret access key (prompted for hidden when omitted; prefer the prompt so the key stays out of your shell history) |

## ankra backup vaults delete

Delete a backup vault.

By default this removes only Ankra's record of the vault and the access keys
it stored: the bucket, everything in it, and any provider resource Ankra
created for it are left in your cloud account.

`--destroy-provider-resources` also destroys what Ankra created for an
Ankra-provisioned vault - it empties and deletes the bucket, and removes the
UpCloud object storage service or DigitalOcean Spaces key that was minted
for it. Restore points in that bucket are gone for good. It is refused for a
vault that registers a bucket you created yourself.

```bash theme={null}
ankra backup vaults delete [vault-name|vault-id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--destroy-provider-resources` | `false` | Also destroy what Ankra created for this vault: empty and delete the bucket (every restore point in it is lost) and remove the provider resource minted for it. Ankra-provisioned vaults only |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra backup vaults get

Describe a backup vault: its endpoint, bucket, verification status, and - when the last credential check failed - the failure excerpt.

```bash theme={null}
ankra backup vaults get [vault-name|vault-id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra backup vaults list

List the organisation's backup vaults

```bash theme={null}
ankra backup vaults list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra backup vaults provision

Create a backup vault and let Ankra create the bucket for it, using one of
the organisation's provider credentials (Hetzner, UpCloud, DigitalOcean or
Scaleway). Ankra creates the bucket, mints or stores the access keys,
verifies the bucket and registers the vault; the vault shows "provisioning"
until that finishes.

Everything is decided for you unless you say otherwise: the name defaults to
"backups" (then "backups-2" and so on), the credential to the only one Ankra
can provision from, and the region to that provider's usual one. The command
prints what it chose before it creates anything.

Hetzner alone needs its Object Storage key pair passed in (or prompted for):
Hetzner issues those in the Cloud Console (Object Storage > Manage
credentials) and its Cloud API cannot mint them. The other providers need
nothing beyond the credential.

Examples:

```bash theme={null}
ankra backup vaults provision
ankra backup vaults provision offsite --credential upcloud-main --region europe-1 --wait
ankra backup vaults provision offsite --credential hetzner-main --region fsn1
```

```bash theme={null}
ankra backup vaults provision [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--access-key-id` | | Hetzner Object Storage access key (Hetzner only; prompted for when omitted) |
| `--bucket` | | Bucket name (default: a unique name derived from the vault name) |
| `--credential` | | Provider credential (name or id) Ankra creates the bucket with (default: the only one it can provision from) |
| `--region` | | Provider region for the bucket (default: that provider's usual one - fsn1, europe-1, fra1, fr-par) |
| `--secret-access-key` | | Hetzner Object Storage secret key (Hetzner only; prompted for hidden when omitted) |
| `--timeout` | `25m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra backup vaults verify

Re-run the platform's credential check against the vault's bucket and report the new status. Use this after rotating or fixing the access keys.

```bash theme={null}
ankra backup vaults verify [vault-name|vault-id]
```


# ankra bucket
Source: https://docs.ankra.ai/reference/cli/bucket

Manage object storage buckets Ankra creates on your provider credentials

## ankra bucket

Create, list, inspect and delete object storage buckets on the organisation's Hetzner, Scaleway, DigitalOcean or UpCloud credentials. Ankra creates the bucket, verifies it and keeps its access keys; the keys are never printed.

## ankra bucket create

Create an object storage bucket on one of the organisation's provider
credentials (Hetzner, Scaleway, DigitalOcean or UpCloud). Ankra creates the
bucket, verifies it and keeps its access keys; the bucket shows "provisioning"
until that finishes.

The credential defaults to the only one Ankra can create buckets with, the
region to that provider's usual one (fsn1, fr-par, fra1, europe-1) and the
provider-side bucket name to a unique one derived from \<name>.

Hetzner's Cloud API cannot mint Object Storage keys. Store the key pair on the
Hetzner credential once and every bucket after that needs nothing more, or
pass `--access-key-id` here: the secret key is then prompted for, hidden, so it
stays out of your shell history. `--secret-access-key` exists for automation;
a value passed that way is recorded wherever the command line is.

Examples:

```bash theme={null}
ankra bucket create registry-storage --credential hetzner-main --region fsn1 --wait
ankra bucket create custody --credential upcloud-main --region europe-1 --bucket acme-custody
```

```bash theme={null}
ankra bucket create <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--access-key-id` | | Hetzner Object Storage access key (Hetzner only; omit to use the pair stored on the credential) |
| `--bucket` | | Provider-side bucket name (default: a unique name derived from \<name>) |
| `--credential` | | Provider credential (name or id) the bucket is created with (default: the only one Ankra can use) |
| `--region` | | Provider region (default: that provider's usual one - fsn1, fr-par, fra1, europe-1) |
| `--secret-access-key` | | Hetzner Object Storage secret key (Hetzner only). Prefer the hidden prompt you get by passing only `--access-key-id`: a flag value lands in your shell history and process list. Use the flag for automation |
| `--timeout` | `25m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra bucket delete

Stop managing an object storage bucket in Ankra.

By default this removes only Ankra's record of the bucket and the access keys
it kept: the bucket and every object in it stay in your cloud account.

`--destroy-provider-resources` also empties and deletes the bucket and removes
the UpCloud object storage service or DigitalOcean Spaces key Ankra created
for it. Everything in the bucket is gone for good. A bucket that is still
being created is always torn down, because the half-finished run may already
have made something billable.

```bash theme={null}
ankra bucket delete [bucket-name|bucket-id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--destroy-provider-resources` | `false` | Also empty and delete the bucket at the provider (everything in it is lost) and remove what Ankra created for it |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra bucket get

Show a bucket's details and status

```bash theme={null}
ankra bucket get [bucket-name|bucket-id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra bucket list

List the organisation's object storage buckets

```bash theme={null}
ankra bucket list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra canvas
Source: https://docs.ankra.ai/reference/cli/canvas

Publish canvas pages at a public, unguessable URL

## ankra canvas

Publish an HTML, SVG or Markdown file as a static page on the Ankra pages
host, list the pages your organisation has published, and unpublish them.

```bash theme={null}
ankra canvas publish report.html --title "Q3 report"
ankra canvas list
ankra canvas unpublish 3f0a2f7e-0000-4000-8000-000000000001
```

Anyone holding the URL can open the page, so publish nothing you would not
hand to that audience. Pages are static snapshots, expire after a retention
period (`--ttl-hours`) and can be unpublished at any time.

## ankra canvas list

List the canvas pages your organisation has published

```bash theme={null}
ankra canvas list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cursor` | | Continue from the cursor printed by a previous list |
| `--limit` | `0` | Maximum number of pages to return (default: the platform's page size) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra canvas publish

Publish an HTML, SVG or Markdown file and print its public URL.

The language is inferred from the file extension (.html and .htm, .svg, .md)
and can be set with `--language`. Other languages are refused, as is a file over
200000 characters.

Publishing the same file again updates the same page and keeps its URL: when
`--conversation-id` and `--artifact-id` are not given, both are derived from a hash
of the file's absolute path, so the page is identified by where the file lives.
Moving or renaming the file publishes a new page. Pass both ids to take control
of the identity yourself, for example to update a page published from the portal
canvas.

The URL is printed last, on its own line, so scripts can take the final line of
output; with -o json the publication is printed as a JSON document instead.

```bash theme={null}
ankra canvas publish <file> [flags]
```

**Examples**

```bash theme={null}
ankra canvas publish report.html
ankra canvas publish notes.md --title "Release notes" --ttl-hours 24
URL=$(ankra canvas publish diagram.svg | tail -n 1)
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--artifact-id` | | Artifact id identifying the page; give together with `--conversation-id` (default: derived from the file's absolute path) |
| `--conversation-id` | | Conversation id identifying the page; give together with `--artifact-id` (default: derived from the file's absolute path) |
| `--language` | | Page language: html, svg or markdown (default: inferred from the extension) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--title` | | Page title (default: the file name without its extension) |
| `--ttl-hours` | `0` | Hours the page stays live (default and maximum are set by the platform) |

## ankra canvas unpublish

Unpublish a page by its id (shown by 'ankra canvas list'). Its URL stops
serving the page immediately.

```bash theme={null}
ankra canvas unpublish <id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |


# ankra charts
Source: https://docs.ankra.ai/reference/cli/charts

Browse Helm charts

## ankra charts

Commands to list, search, and get information about Helm charts.

## ankra charts info

Get detailed information about a Helm chart.

Requires either `--repository` flag or finding the chart in the catalog first.

```bash theme={null}
ankra charts info <chart_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Repository URL for the chart |

## ankra charts list

List available Helm charts

```bash theme={null}
ankra charts list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `25` | Number of items per page |
| `--subscribed` | `false` | Show only subscribed charts |

## ankra charts search

Search for Helm charts

```bash theme={null}
ankra charts search <query> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra charts template

Render a chart version's Kubernetes manifests server-side, without
deploying anything - the 'helm template' equivalent for the Ankra catalog.

The manifests are printed to stdout as a '---' separated multi-doc YAML
stream with a '# Source:' header per document, so the output pipes straight
into kubectl diff, kubeconform, or a file. Chart NOTES.txt output goes to
stderr.

Values problems (bad YAML, schema violations, template errors) fail with the
exact Helm error a deploy would have produced - validate values before they
reach production:

```bash theme={null}
ankra charts template nginx --version 1.2.3
ankra charts template nginx --version 1.2.3 -f values.yaml
ankra charts template nginx --version 1.2.3 --release-name web --namespace edge
```

```bash theme={null}
ankra charts template <chart_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--namespace` | | Release namespace for the render (default: "default") |
| `--release-name` | | Release name for the render (default: the chart name) |
| `--repository` | | Repository name for the chart |
| `-f`, `--values` | | YAML file overriding the chart's default values |
| `--version` | | Chart version (required) |

## ankra charts values

Print the default values document shipped inside a chart version.

By default the decoded YAML is written to stdout, making it easy to pipe into
a file, edit, and feed back to 'ankra charts template -f':

```bash theme={null}
ankra charts values nginx --version 1.2.3 > values.yaml
ankra charts values nginx --version 1.2.3 -o raw   # base64-encoded form
```

The repository is resolved automatically when the chart name is unambiguous;
pass `--repository` to pin it.

```bash theme={null}
ankra charts values <chart_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: yaml (decoded, default) or raw (base64) |
| `--repository` | | Repository name for the chart |
| `--version` | | Chart version (required) |


# ankra chat
Source: https://docs.ankra.ai/reference/cli/chat

AI-powered chat for troubleshooting and assistance

## ankra chat

AI-powered chat for troubleshooting and assistance.

If a message is provided, sends a one-shot question and prints the
conversation id so a follow-up can continue it with `--conversation`.
If no message is provided, enters interactive chat mode.

Use `--cluster` to provide cluster context for better answers; without it the
persisted 'ankra cluster select' applies, and with neither the chat reads
across the whole organisation.

A one-shot question takes -o json (or -o yaml) for scripts and CI jobs: the
answer is printed once, when the turn ends, as one document carrying the
answer text, the conversation id, the safety mode the turn ran in, the
cluster it was scoped to, the tools the model ran and any write left
awaiting confirmation. A turn that starts and then fails still prints the
document, with its "error" member set, and exits non-zero; a question the
platform refuses to start (a rejected token, an unknown cluster) prints
nothing on stdout and exits with that error's code. The one exception is
AI paused by the organisation's billing standing: that refusal prints the
document with "error\_code" BILLING\_RESTRICTED and the platform's sentence in
"detail", whether it came before the turn or on it, so a job can tell it
from a failed answer. Interactive mode has no structured output.

```bash theme={null}
ankra chat [message] [flags]
```

**Examples**

```bash theme={null}
# Ask once, scoped to a cluster
ankra chat --cluster prod "why is the payments pod restarting?"

# The same, parsed in a CI job
ankra chat --cluster prod --mode ask -o json "summarise failing pods" | jq -r .answer

# Continue the conversation a previous answer named
ankra chat --conversation <id> "and the one before that?"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name for context |
| `--conversation` | | Continue an existing conversation (id from 'ankra chat history' or a previous answer) |
| `--mode` | | Safety mode: 'ask' (read-only + safe creations) or 'agent' (can act). Defaults to the server default. |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra chat actions

Agent-mode chat halts before every write and proposes it as a pending
action. Confirm the action to run it, or reject it to discard it.

Pending actions expire, so confirm promptly. If the cluster changed since the
action was proposed, confirming answers a drift conflict; re-run with `--force`
to apply it against the changed state anyway.

## ankra chat actions confirm

Confirm a pending action proposed by agent-mode chat.

The platform re-checks the action against live cluster state before running
it. If the state drifted since the proposal, the command reports the drift and
exits without running anything; pass `--force` to run it anyway.

```bash theme={null}
ankra chat actions confirm <action_id> [flags]
```

**Examples**

```bash theme={null}
# Confirm the action id printed by the chat stream
ankra chat actions confirm 6f1c2f9e-6d5a-4a1e-9f0b-6d4c2b8a1e77

# Apply it even though the cluster drifted since it was proposed
ankra chat actions confirm 6f1c2f9e-6d5a-4a1e-9f0b-6d4c2b8a1e77 --force \
  --force-reason "drift is an unrelated label change"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Confirm even though cluster state drifted since the action was proposed |
| `--force-reason` | | Why the drift is acceptable (recorded in the audit trail, max 280 characters) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra chat actions list

List the actions awaiting confirmation in a conversation

```bash theme={null}
ankra chat actions list <conversation_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra chat actions reject

Reject a pending AI action so it never runs

```bash theme={null}
ankra chat actions reject <action_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the action was rejected |

## ankra chat delete

Delete a chat conversation

```bash theme={null}
ankra chat delete <conversation_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra chat health

Get AI-analyzed cluster health

```bash theme={null}
ankra chat health [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--ai` | `true` | Include AI analysis |
| `--cluster` | | Target cluster name or ID (defaults to the selected cluster) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra chat history

List chat conversation history

```bash theme={null}
ankra chat history [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Filter by cluster |
| `--limit` | `20` | Maximum number of conversations to show |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra chat show

Show a specific chat conversation

```bash theme={null}
ankra chat show <conversation_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra cluster
Source: https://docs.ankra.ai/reference/cli/cluster

Cluster operations

## ankra cluster

Commands for managing and operating on clusters.

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster name or ID for this command, overriding `ankra cluster select` |

## ankra cluster access

List, grant, and revoke per-user access to a cluster's Kubernetes API
through the Ankra gateway (the access used by 'ankra cluster kubeconfig' and
'ankra cluster kube-token').

Managing access requires organisation admin rights. Grants apply to one
cluster and one organisation member, identified by email. A grant can be
time-boxed with `--expires` and carry a `--reason`; the organisation access
policy ('ankra org access-policy') may require both.

A service account has no email: 'list' names it "service account \<name>",
and it gets access with 'elevate', run with its own token.

Break-glass: 'elevate' gives the caller itself time-boxed access, within the
policy. It needs only the kube\_access.elevate permission, so automation
running as a service account can use it without being able to grant anyone
else.

'list' shows where each grant came from (Source: manual, creator, role,
elevated) and whether the current policy would refuse it today (Over policy).
A grant whose source is "role" comes from the member's organisation role and
cannot be revoked here: the platform refuses it, because the role sync would
re-create it. Change the member's role, or the role's Kubernetes access, to
remove it.

Exit codes:

```text theme={null}
2  a flag is missing or invalid, or the organisation access policy refused
   the request (a role above the ceiling, a missing or too long --expires,
   a missing --reason): change the flags and run it again. Also revoke of a
   grant that comes from an organisation role: change the member's role
3  the grant or member was not found on the cluster (revoke)
6  the credentials are missing, expired or rejected: run 'ankra login'
7  your role does not allow this (for example elevate without
   kube_access.elevate, or grant without managing kubectl access): ask an
   organisation admin
```

Examples:

```bash theme={null}
ankra cluster access list --cluster my-cluster
ankra cluster access grant user@example.com --cluster my-cluster --role view
ankra cluster access grant user@example.com --cluster my-cluster --role edit --namespace staging
ankra cluster access grant user@example.com --cluster my-cluster --role admin --expires 4h --reason "maintenance window"
ankra cluster access elevate --cluster my-cluster --role edit --expires 4h --reason "incident 4711"
ankra cluster access revoke user@example.com --cluster my-cluster
ankra cluster access revoke 6f1f9aca-2c3d-4e5f-8a9b-0c1d2e3f4a5b --cluster my-cluster
```

## ankra cluster access elevate

Give the identity this CLI runs as - you, or a service account's token -
time-boxed access to a cluster through the kube gateway.

This is break-glass within the organisation access policy: the access must
end (`--expires`, at most the policy's limit or 4 hours) and needs a `--reason`,
and it can never go above the policy's ceiling. It needs the
kube\_access.elevate permission, which grants nothing else: no access for
anyone else, no standing access, and no way to change the policy. Running it
again with a new `--expires` extends your own elevation; end it early with
'ankra cluster access revoke \<grant-id>'.

The binding reaches the cluster within about 30 to 60 seconds; until then
kubectl may still answer 403 Forbidden, so retry it.

Every elevation is recorded in the audit log and notifies the organisation's
notification routes.

Exits 2 when `--expires` or `--reason` is missing or a flag is invalid, and when
the organisation access policy refuses the request; 7 when your role lacks
kube\_access.elevate. See 'ankra cluster access `--help`' for every code.

```bash theme={null}
ankra cluster access elevate [flags]
```

**Examples**

```bash theme={null}
ankra cluster access elevate --cluster prod --role edit --expires 4h --reason "incident 4711: restart the stuck rollout"
ankra cluster access elevate --cluster prod --role edit --namespace payments --expires 30m --reason "hotfix"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or ID (defaults to the selected cluster) |
| `--expires` | | When the access ends: a duration (30m, 4h) or an RFC 3339 time (required) |
| `--namespace` | | Limit the elevation to one namespace (default: cluster-wide) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the access is needed (required) |
| `--role` | `edit` | Kubernetes role to elevate to: view, edit, admin, or cluster-admin |

## ankra cluster access grant

Grant an organisation member access to a cluster's Kubernetes API through
the Ankra gateway.

The grant is cluster-wide by default; pass `--namespace` to limit it to one
namespace. Roles map to the standard Kubernetes ClusterRoles: view, edit,
admin, cluster-admin.

Exits 2 when a flag is invalid or the organisation access policy refuses the
grant (change `--role`, `--expires` or `--reason`), and 7 when your role does not
allow managing kubectl access. See 'ankra cluster access `--help`' for every
code.

```bash theme={null}
ankra cluster access grant <email> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or ID (defaults to the selected cluster) |
| `--expires` | | End the grant after a duration (30m, 4h, 7d) or at an RFC 3339 time (default: standing) |
| `--namespace` | | Limit the grant to one namespace (default: cluster-wide) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the access is granted; recorded with the grant and in the audit log |
| `--role` | `view` | Kubernetes role for the grant: view, edit, admin, or cluster-admin |

## ankra cluster access list

List access grants for a cluster

```bash theme={null}
ankra cluster access list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or ID (defaults to the selected cluster) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster access revoke

Revoke gateway access from a cluster.

Pass a grant ID (from 'ankra cluster access list') to revoke a single grant,
or an email address to revoke every grant that member has on the cluster.

A grant whose Source is "role" in 'ankra cluster access list' comes from the
member's organisation role and cannot be revoked here: the platform refuses
it, because the role sync would re-create it. Change the member's role, or
the role's Kubernetes access, to remove it. Revoking by email still revokes
the member's other grants, then names the ones it kept and exits 2, so a
script never reads the member's access as gone while a role grant remains.

Exits 2 when a grant comes from an organisation role, 3 when no grant
matches, and 7 when your role does not allow managing kubectl access.

```bash theme={null}
ankra cluster access revoke <grant-id|email> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or ID (defaults to the selected cluster) |

## ankra cluster addons

Commands to list, manage settings, and uninstall addons.

## ankra cluster addons available

List addons available for installation

```bash theme={null}
ankra cluster addons available [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster addons list

List addons for the active cluster; or show details for a single addon

```bash theme={null}
ankra cluster addons list [addon name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `asc` | Sort direction with `--sort`: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--sort` | | Sort by column: name, chart, version, namespace, health, state, created, updated (default: server order) |

## ankra cluster addons settings

Read and write an addon's settings

```bash theme={null}
ankra cluster addons settings <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster addons settings get

Get settings for an addon

```bash theme={null}
ankra cluster addons settings get <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster addons settings set

Change one or more settings on an addon without resending the rest.

Each flag is applied to the addon's stored settings; anything you do not pass
is left as it is. To replace the whole document instead, use
'ankra cluster addons update \<addon> -f settings.json'.

Backup settings override the add-on's stack backup policy for
this add-on only - use them for the one add-on in a protected stack that
should be captured differently:

```bash theme={null}
ankra cluster addons settings set cnpg-cluster --backup-enabled=true --backup-consistency=transactional
ankra cluster addons settings set redis-cache --backup-enabled=false
ankra cluster addons settings set cnpg-cluster --backup-schedule=hourly --backup-retention-daily=14
```

```bash theme={null}
ankra cluster addons settings set <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--auto-prune` | `true` | Delete resources the addon no longer declares |
| `--automated` | `true` | Sync the addon automatically when its definition changes |
| `--backup-consistency` | | How the capture is taken: transactional, application, crash or logical |
| `--backup-enabled` | `false` | Capture this addon's data assets under the stack's backup policy |
| `--backup-retention-daily` | `0` | Daily restore points to keep for this addon |
| `--backup-retention-hourly` | `0` | Hourly restore points to keep for this addon |
| `--backup-retention-minimum-age` | | Never expire a restore point younger than this (e.g. 24h) |
| `--backup-retention-minimum-count` | `0` | Keep at least this many restore points for this addon |
| `--backup-retention-monthly` | `0` | Monthly restore points to keep for this addon |
| `--backup-retention-weekly` | `0` | Weekly restore points to keep for this addon |
| `--backup-retention-yearly` | `0` | Yearly restore points to keep for this addon |
| `--backup-schedule` | | Override the stack's schedule for this addon: hourly, daily, weekly, or a cron expression |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--revision-history-limit` | `10` | How many previous releases to keep |
| `--self-heal` | `true` | Re-apply the addon when the live state drifts |

## ankra cluster addons uninstall

Uninstall an addon from the cluster

```bash theme={null}
ankra cluster addons uninstall <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--delete` | `false` | Also delete the addon permanently |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster addons update

Update addon settings by providing a JSON file that conforms to the settings schema.

Example JSON file:

```json theme={null}
{
  "retry_policy": { "limit": 3, "backoff": { "duration": "5s", "factor": 2, "max_duration": "3m" } },
  "sync_policy": { "automated": true, "self_heal": true, "auto_prune": false },
  "revision_history_limit": 10
}
```

Usage:

```bash theme={null}
ankra cluster addons update my-addon -f settings.json
```

```bash theme={null}
ankra cluster addons update <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-f`, `--file` | | Path to JSON settings file (required) |

## ankra cluster addons upgrade

Upgrade an addon by patching just the fields you supply.

At least one mutating flag is required. Examples:

```bash theme={null}
# Bump chart version
ankra cluster addons upgrade ankra-website --chart-version 1.0.146 \
  --cluster website-demo

# Tweak a single Helm values field with --set (mutates the existing values)
ankra cluster addons upgrade website --set image.tag=1.0.146 \
  --cluster website-demo

# Address a list item by a field instead of an index
ankra cluster addons upgrade website --set 'env[name=LOG_LEVEL].value=debug' \
  --cluster website-demo

# Replace the whole values document
ankra cluster addons upgrade website \
  --values-from-file ./values.yaml --cluster website-demo
```

`--set*` and `--values-from-file` are mutually exclusive: `--set*` mutates the
existing values document while `--values-from-file` replaces it.

Changing `--namespace` is destructive (Helm reinstall in the new namespace,
leaves the old release orphaned). Use `--yes` to skip the confirmation prompt
or interactively confirm.

```bash theme={null}
ankra cluster addons upgrade <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--add-parent` | `[]` | Add a dependency parent, e.g. `--add-parent` name=infisical-ns,kind=manifest (kind defaults to manifest; repeatable) |
| `--chart-version` | | New chart version to install |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--dry-run` | `false` | Print the proposed before/after spec without applying changes |
| `--namespace` | | Change the addon's namespace (destructive: Helm reinstall) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--registry-credential-name` | | New helm registry credential name |
| `--registry-name` | | New helm registry name |
| `--registry-url` | | New helm registry URL |
| `--remove-parent` | `[]` | Remove a dependency parent, e.g. `--remove-parent` name=infisical-ns,kind=manifest (repeatable) |
| `--set` | `[]` | Helm-style values mutation, e.g. `--set` image.tag=1.0.0 (MUTATES existing values; repeatable, comma-separated) |
| `--set-file` | `[]` | Like `--set` but reads the value from a file: key=path or key=@path |
| `--set-parent` | `[]` | Replace ALL dependency parents with the given set (repeatable); pass none with the others to clear |
| `--set-string` | `[]` | Like `--set` but always treats the value as a string |
| `--stack` | | Stack name (required when the addon exists in multiple stacks) |
| `--values` | | Use `-` to read values YAML from stdin (REPLACES the entire values document) |
| `--values-from-file` | | Path to YAML values file (REPLACES the entire values document) |
| `--yes` | `false` | Skip the confirmation prompt for destructive changes (`--namespace`) |

## ankra cluster addons values

Print the current Helm values document for an addon.

By default the decoded YAML is written to stdout, making it easy to pipe into
a file or edit and re-apply with `--values-from-file`:

```bash theme={null}
ankra cluster addons values my-addon > values.yaml
ankra cluster addons values my-addon -o raw   # base64-encoded form
```

```bash theme={null}
ankra cluster addons values <addon_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `-o`, `--output` | | Output format: yaml (decoded, default) or raw (base64) |

## ankra cluster agent

Commands to view agent status, get tokens, and upgrade agents.

## ankra cluster agent auto-upgrade

The platform rolls new agent releases out to every online agent automatically,
as soon as the cluster has no write execution running. Disabling that here
fences this cluster's agent off from the rollout - for a freeze window or a
migration night - and enabling it puts the agent back in. Either way
'ankra cluster agent upgrade' still applies the latest release on demand,
and 'ankra cluster agent status' shows the current setting.

Every change is recorded in the organisation audit log with who made it and
the setting it replaced; `--reason` adds your own words for why, so the next
person to look can tell a deliberate fence from an accident.

**Examples**

```bash theme={null}
ankra cluster agent auto-upgrade disable --cluster prod --reason "storage cutover tonight"
ankra cluster agent auto-upgrade enable --cluster prod --reason "cutover finished"
```

## ankra cluster agent auto-upgrade disable

Fence the cluster agent off from the automatic fleet rollout

```bash theme={null}
ankra cluster agent auto-upgrade disable [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the switch is changing, recorded on the change's audit row (optional; the platform keeps the first 500 characters) |

## ankra cluster agent auto-upgrade enable

Put the cluster agent back into the automatic fleet rollout

```bash theme={null}
ankra cluster agent auto-upgrade enable [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the switch is changing, recorded on the change's audit row (optional; the platform keeps the first 500 characters) |

## ankra cluster agent ci

The cluster agent runs Ankra Pipelines steps itself, and these settings
size that: how many steps it runs at once, and the storage class its step
workspaces are carved from.

The worker count is the agent's CI slots: each slot is one pipeline step the
agent watches at a time, not a node. The nodes those steps run on come from
the cluster's node group autoscaler ('ankra cluster node-group autoscaling
get'), so a cluster whose steps wait for a slot needs more workers, and one
whose step pods sit Pending needs more nodes.

Both are stored on the platform, so every install or upgrade command Ankra
generates for this cluster carries them - unlike a hand-run
'helm upgrade `--set` ci\_worker\_count=...', which the next agent upgrade
renders away again.

The placement says which nodes every pipeline pod runs on - step pods, their
cache and artifact helpers, and image builds - so CI can live on a dedicated,
tainted node group without editing any pipeline's runs\_on.

The run reservation decides whether a run first reserves the room its later
steps need on its node, so another run's pods cannot take it between two
steps: off (the default), shadow (sized and recorded, nothing held) or on.

The image pre-pull decides whether the agent keeps the images the platform's
own steps run in - the checkout's git client, the scanners, the rootless
builder - pulled on every node pipeline steps can land on, so a node that
just joined pulls them as it joins rather than while a step waits: off (the
default) or on.

The step workspaces setting decides whether a pipeline that declares
workspace.mode: per\_step gets a workspace for each step, so its steps can run
on different nodes, rather than one volume that keeps the whole run on one
node: off (the default), shadow (recorded, nothing changes) or on.

The Ankra Workspace class is the storage class the cluster's Ankra Workspaces
cut their volume from, when they cannot share the one pipeline steps use. Left
empty, they inherit it.

## ankra cluster agent ci get

Show the stored worker count, storage class and placement, the agent version
that has to honour them, whether that agent currently advertises it can run
pipeline steps, and how the last write was applied. The placement block names
the node group, node selector, tolerations and mode, and how many Ready nodes
it admits right now. The run reservation, image pre-pull and step workspaces
modes are shown with whether the agent advertises each; a platform that
predates a setting shows neither of its lines. The Ankra Workspace class is
the storage class the cluster's Ankra Workspaces use, and says when they
inherit it; a platform that predates it shows no such line.

An agent that has not yet re-rendered its release reports pipeline steps as
not advertised even with a non-zero worker count stored: the capability is
what the agent reported on its last check-in, not what the settings ask for.

```bash theme={null}
ankra cluster agent ci get [flags]
```

**Examples**

```bash theme={null}
ankra cluster agent ci get
ankra cluster agent ci get --cluster edge-01 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster agent ci set

Store how many pipeline steps this cluster's agent runs at once, the storage
class its step workspaces are carved from, and where its pipeline pods run.

`--workers` 0 disables the agent's pipeline-step scheduler; the cluster keeps
its agent and everything else it does. `--storage-class` is only sent when you
pass it, so setting the worker count alone keeps the storage class already
stored; pass an empty value to fall back to the cluster's default class.

`--storage-class` reaches two things at different times. Pipeline steps take it
at the agent's next re-render. Ankra Workspaces on the cluster that have no
workspace class of their own read it at their next use, so changing it replaces
each of them then, and whatever runs in one stops. An Ankra Workspace stays off
the nodes pipeline steps run on, so a class only those nodes can use would leave
it Pending for good.

`--ankra-workspace-storage-class` gives the cluster's Ankra Workspaces a class of
their own, so that cannot happen. To move pipeline steps to such a class with
no workspace replaced, first pass the class the workspaces use now, which
changes nothing for them, and then change `--storage-class`. Naming a different
class replaces each workspace at its next use. It reaches no pipeline step and
restarts no agent. Pass an empty value to inherit `--storage-class` again; a
workspace is replaced then if that is a different class.

`--workers` is the agent's CI slots: how many pipeline steps it watches at
once. A slot is not a node; the nodes steps run on come from the cluster's
node group autoscaler. Agents that support live resize accept up to 128
workers, older agents up to 32.

The write always stores the values. Whether they reach the agent now depends
on the agent: an agent that supports live resize takes a new worker count on
its next job pull without restarting, an online agent new enough to accept
chart values re-renders its release immediately, an older one picks them up
at its next upgrade, and an offline one when it reconnects. The command says
which happened.

Placement puts every pipeline pod of the cluster - step pods, their cache and
artifact helpers, and image builds - on chosen nodes. `--node-group` names one
of the cluster's Ankra node groups: the platform selects its nodes by the
ankra.cloud/node-group label (or the labels the group declares) and tolerates
every taint the group carries, so a dedicated, tainted pool needs nothing
else. `--node-selector` and `--toleration` add to it, or stand alone on a cluster
without Ankra node groups. `--placement` required (the default) keeps pods on
those nodes; preferred favours them and lets pods run elsewhere when they have
no room, and still carries the tolerations. The placement is replaced whole by
any placement flag, applies to the next step dispatched with no agent restart,
and is never held to the organisation's runs\_on allow-lists. `--clear-placement`
removes it. `--workers` is optional when only the storage class or the placement
changes.

On a cluster with pipeline steps off (0 workers), 'set' with no flags turns
them on with 50 workers. On a cluster that already runs steps, it names
nothing to change and asks for a flag.

`--run-reservation` off|shadow|on decides whether each run first reserves, on
its node, the room its later steps will need, held by one placeholder pod per
run, so another run's pods cannot take that room between two steps. off (every
cluster's default) reserves nothing. shadow sizes each run's reservation and
records it beside what its steps requested, and holds nothing: use it to check
the estimate first. on holds it, which can add a node or keep one up while a
run is between steps; it needs an agent that advertises run reservation, and
until the agent does, on behaves as shadow. Like the placement it applies to
the next step dispatched, with no agent restart, and off is the way back.

`--image-prepull` off|on decides whether the agent keeps the platform's own
step images (the checkout's git client, the trivy, checkov and semgrep
scanners, the rootless builder) pulled on every node pipeline steps can land
on, honouring the placement, with one DaemonSet in the agent's namespace. A
node that just joined then pulls them as it joins instead of while a
checkout, scan or build waits. The images are pinned by digest and follow
the platform: a platform release that moves one moves the pre-pull with the
next step dispatched. Each node keeps about 0.9 GB of images it would
otherwise pull on demand. It needs an agent that advertises image pre-pull;
off (the default) removes it with the next step dispatched.

`--step-workspaces` off|shadow|on decides whether a pipeline that declares
workspace.mode: per\_step gets a workspace for each step, so its steps can run
on different nodes, rather than one volume that keeps the whole run on one
node. off (every cluster's default) runs every pipeline on the shared volume,
whatever it declares. shadow still does, and records the mode each per\_step
run would have taken under on: use it to check a cluster first. on gives each
step its own workspace; it needs an agent that advertises step workspaces and
a ready backup vault to hand files between steps through, and a run without
either stays on the shared volume. A pipeline that does not declare per\_step
never changes. A run takes its mode at its first step, with no agent restart,
and keeps it, so off is the way back for new runs and a run already started
finishes in the mode it has.

`--build-apparmor-profile` \<name> runs the rootless image builder under a
Localhost AppArmor profile installed on the cluster's nodes under that name.
On nodes whose container runtime confines the builder with its default
AppArmor profile (containerd on Ubuntu denies the builder its mount), builds
otherwise fail in-cluster and fall back to Ankra's builders. The build
namespace's Pod Security Baseline admits a Localhost profile, so nothing else
is relaxed. Install the profile on every node builds can run on first: a node
without it makes the build wait rather than run. The name is a DNS-1123
subdomain other than unconfined; pass an empty value to go back to the
runtime's default. It needs an agent that advertises the capability, applies
to the next build dispatched with no agent restart, and the next build is
probed in-cluster again even if the cluster was known to confine the builder.

```bash theme={null}
ankra cluster agent ci set [flags]
```

**Examples**

```bash theme={null}
ankra cluster agent ci set
ankra cluster agent ci set --workers 50 --storage-class proxmox-csi
ankra cluster agent ci set --workers 0 --cluster edge-01
ankra cluster agent ci set --ankra-workspace-storage-class ankra-ci-disposable --cluster ci-01
ankra cluster agent ci set --node-group pipelines
ankra cluster agent ci set --node-selector pool=ci --toleration dedicated=ci:NoSchedule --placement preferred
ankra cluster agent ci set --clear-placement
ankra cluster agent ci set --run-reservation shadow --cluster ci-01
ankra cluster agent ci set --image-prepull on --cluster ci-01
ankra cluster agent ci set --step-workspaces shadow --cluster ci-01
ankra cluster agent ci set --build-apparmor-profile ankra-rootless-buildkit --cluster ci-01
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--ankra-workspace-storage-class` | | Storage class for the cluster's Ankra Workspaces, apart from pipeline steps; a different class replaces each workspace on next use; pass empty to inherit `--storage-class` (omit the flag to keep the stored value) |
| `--build-apparmor-profile` | | Node-installed AppArmor profile the rootless image builder runs under (Localhost); pass empty to use the runtime's default (omit the flag to keep the stored value) |
| `--clear-placement` | `false` | Remove the cluster's CI placement |
| `--image-prepull` | | Image pre-pull: off (default) pulls the platform's step images on demand, on keeps them pulled on every node pipeline steps can land on |
| `--node-group` | | Run every pipeline pod on this Ankra node group: selects its nodes and tolerates its taints |
| `--node-selector` | `[]` | Node label every pipeline pod selects, as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--placement` | | Placement mode: required (default) keeps pipeline pods on the selected nodes, preferred favours them |
| `--run-reservation` | | Run reservation: off (default) reserves nothing, shadow sizes and records each run's reservation without holding it, on holds a run's room on its node between its steps |
| `--step-workspaces` | | Step workspaces: off (default) runs every pipeline on one shared volume, shadow records the mode each per\_step run would take without changing it, on gives each step of a per\_step pipeline its own workspace |
| `--storage-class` | | Storage class for pipeline step workspaces: pipeline steps take it at the next agent re-render, and Ankra Workspaces on the cluster that have no workspace class of their own are replaced on next use; pass empty to use the cluster default (omit the flag to keep the stored value) |
| `--toleration` | `[]` | Taint every pipeline pod tolerates, as key\[=value]:Effect with Effect NoSchedule, PreferNoSchedule or NoExecute (repeatable) |
| `--workers` | `0` | CI slots: pipeline steps the agent watches at once, not nodes (nodes come from the node group autoscaler); up to 128 on agents that support live resize, 32 otherwise; 0 disables the scheduler; omitted with no other flag on a cluster with pipeline steps off, 50 |

## ankra cluster agent resources

The cluster agent runs as one pod in the cluster, and these settings size it:
its memory limit and request and its CPU limit and request, as Kubernetes
quantities ("2Gi", "500m").

They are stored on the platform, so every install or upgrade command Ankra
generates for this cluster carries them - unlike a hand-run
'helm upgrade `--set` resources.limits.memory=...', which the next agent
upgrade renders away again. A member the cluster does not set uses the agent
chart's default.

## ankra cluster agent resources get

Show the stored memory and CPU limits and requests of the cluster's agent, when
they last changed, and how the platform applied them. A member the cluster
does not set reads "chart default": the agent chart's own value applies.

```bash theme={null}
ankra cluster agent resources get [flags]
```

**Examples**

```bash theme={null}
ankra cluster agent resources get
ankra cluster agent resources get --cluster edge-01 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster agent resources set

Store the memory and CPU limits and requests of this cluster's agent, as
Kubernetes quantities ("2Gi", "512Mi", "1", "500m").

Only the flags you pass are sent, so setting the memory limit alone keeps
every other member as stored. Pass an empty value ("") to clear a member: the
agent goes back to the chart's default for it. At least one flag is required.

The write always stores the values. Whether they reach the agent now depends
on the agent: an online agent new enough to accept them re-renders its
release immediately, an older one picks them up at its next upgrade, and an
offline one when it reconnects. The command prints the platform's sentence
saying which happened.

The platform validates the values - a malformed quantity, or a request above
its limit - and its refusal is printed as it came.

```bash theme={null}
ankra cluster agent resources set [flags]
```

**Examples**

```bash theme={null}
ankra cluster agent resources set --memory-limit 2Gi
ankra cluster agent resources set --memory-limit 2Gi --memory-request 1Gi --cluster edge-01
ankra cluster agent resources set --cpu-limit 1 --cpu-request 250m
ankra cluster agent resources set --memory-limit ""
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cpu-limit` | | Agent CPU limit, such as 1 or 1500m; pass "" to clear it back to the chart default |
| `--cpu-request` | | Agent CPU request, such as 250m; pass "" to clear it back to the chart default |
| `--memory-limit` | | Agent memory limit, a Kubernetes quantity such as 2Gi; pass "" to clear it back to the chart default |
| `--memory-request` | | Agent memory request, such as 1Gi; pass "" to clear it back to the chart default |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster agent status

Get agent status for the selected cluster

```bash theme={null}
ankra cluster agent status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster agent token

Get or generate agent token for the selected cluster

```bash theme={null}
ankra cluster agent token [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new agent token |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster agent upgrade

Upgrade the Ankra agent on the selected cluster now, instead of waiting for
the fleet rollout.

Without `--version` the platform installs the newer of the release the agent
runs and the latest stable release, so this never moves an agent backwards:
an agent already on a newer release (a release candidate) is re-rendered where
it is.

`--version` installs that exact published release. A version older than the one
the agent runs is refused unless `--allow-downgrade` is also given, so a
downgrade only ever happens when both flags say so. A version that is neither
published nor the running one is refused.

```bash theme={null}
ankra cluster agent upgrade [flags]
```

**Examples**

```bash theme={null}
ankra cluster agent upgrade
ankra cluster agent upgrade --version 2.1.1250
ankra cluster agent upgrade --version 2.1.1247 --allow-downgrade
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allow-downgrade` | `false` | Allow `--version` to be older than the release the agent runs (needs `--version`) |
| `--version` | | Exact agent release to install (default: the newer of the running release and the latest stable one) |

## ankra cluster ankracloud

Manage kubeadm or k3s clusters Ankra builds on Ankra Cloud servers.

For Ankra Cloud Kubernetes, where the Ankra team runs the control plane, use
'ankra cluster managed ... `--provider` ankracloud\_k8s' instead. Both take the
same Ankra Cloud credential ('ankra credentials ankracloud create').

## ankra cluster ankracloud bastion

Inspect, diagnose, and resize the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster ankracloud bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster ankracloud bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster ankracloud bastion resize

Resize the bastion/gateway node. The provider's bastion/gateway update job
powers it off, resizes it, and powers it back on, causing brief SSH/NAT
downtime for the cluster.

`--wait` covers the platform write only; the cloud resize runs as the operation
reported on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

```bash theme={null}
ankra cluster ankracloud bastion resize <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster ankracloud bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster ankracloud bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster ankracloud control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster ankracloud control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster ankracloud control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud control-plane set-instance-type

Change the instance type of every controller in a Ankra Cloud cluster.

The instance type is stored as given; it is not checked against Ankra Cloud's catalog.
A name that does not exist is rejected by Ankra Cloud itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster ankracloud plans
```

```bash theme={null}
ankra cluster ankracloud control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud cpu-pools

List the CPU pools of an Ankra Cloud zone: compute nodes grouped by exact CPU.

A server is placed in one pool and only moves within it, and its guest sees the
host's CPU, so the pool decides which instructions a workload may use. The
x86-64 level column is the microarchitecture level every CPU of the pool meets:
3 or more has AVX2, which images built for x86-64-v3 (duckdb, pyarrow, numba
wheels and many ML runtimes) need or they crash with SIGILL.

Pin a node group to a pool with 'ankra cluster node-group add `--cpu-pool` \<name>'.

Pass `--cluster` to list the pools of an existing cluster's zone under its own
credential, or `--credential-id` with `--zone` to browse before creating one.

```bash theme={null}
ankra cluster ankracloud cpu-pools [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | List the CPU pools of an existing cluster's zone under its own credential instead |
| `--credential-id` | | Ankra Cloud credential ID (required unless `--cluster` is given) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--zone` | | Zone whose CPU pools to list (required with `--credential-id`) |

## ankra cluster ankracloud create

Create an Ankra-managed kubeadm (default) or k3s cluster on Ankra Cloud
servers. Ankra builds the private network (unless `--private-network-id` adopts
one), a NAT router for the nodes' IPv4 egress, the per-server firewalls, a
bastion with a public IPv4 address, and the control plane and worker servers.
The kube-apiserver stays private and is reached through the bastion.

That is the ipv4\_nat network mode, the server default. A zone with no public
IPv4 left takes `--network-mode` ipv6\_only instead: no NAT router, the bastion
is reached over IPv6 through the Cloud's port forward, and the nodes reach
IPv4 through the zone's NAT64. The preflight names the mode a zone needs.

Servers are sized by plan: list them with 'ankra cluster ankracloud plans'.
Each server's root disk is its plan's included disk unless a --*-disk-gib
flag sizes it, on the zone's default storage tier unless a --*-disk-tier flag
chooses one (local-nvme, standard, maxiops or hdd). CI workers belong on
small local-nvme disks when their data lives on persistent volumes. Run 'preflight' first to check the zone, plans, network
and quota, which counts the chosen disk sizes against the account's storage.

Examples:

```bash theme={null}
ankra cluster ankracloud create --name prod --credential-id <id> \
  --ssh-key-credential-id <id> --zone <zone> \
  --bastion-plan <plan> --control-plane-plan <plan> --worker-plan <plan>
ankra cluster ankracloud create --name edge --distribution k3s ...
ankra cluster ankracloud create --name ci --worker-plan starter-16c-32g --worker-disk-gib 40 --worker-disk-tier local-nvme ...
ankra cluster ankracloud create --name fsn --zone de-fsn3 --network-mode ipv6_only ...
```

```bash theme={null}
ankra cluster ankracloud create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-allowed-ips` | `[]` | CIDRs allowed to reach the bastion over SSH (default: anywhere) |
| `--bastion-disk-gib` | `0` | Bastion root disk size in GiB (default: the plan's included disk) |
| `--bastion-disk-tier` | | Bastion root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--bastion-plan` | | Bastion server plan (required) |
| `--cni` | | CNI plugin (server default: cilium; immutable after create) |
| `--control-plane-count` | `0` | Control plane node count (server default: 1) |
| `--control-plane-disk-gib` | `0` | Control plane root disk size in GiB (default: the plan's included disk) |
| `--control-plane-disk-tier` | | Control plane root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--control-plane-plan` | | Control plane server plan (required) |
| `--credential-id` | | Ankra Cloud credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-disk-gib` | `0` | External etcd node root disk size in GiB (default: the plan's included disk) |
| `--etcd-disk-tier` | | External etcd node root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--etcd-node-count` | `0` | External etcd node count, 3 or 5 (server default: 3) |
| `--etcd-plan` | | External etcd server plan (required with `--etcd-topology` external) |
| `--etcd-topology` | | etcd topology: stacked or external (server default: stacked) |
| `--gitops-branch` | | GitOps branch (server default: master) |
| `--gitops-credential-name` | | GitOps credential name (optional) |
| `--gitops-repository` | | GitOps repository URL (optional) |
| `--include-dns` | `true` | Provision the DNS zone |
| `--include-networking` | `true` | Provision the networking stack |
| `--kubernetes-version` | | Pin a Kubernetes version (default: latest supported) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | | RFC 1918 CIDR (/16 to /29) for the created private network (server default: a /24 derived from the cluster) |
| `--network-mode` | | Network mode: ipv4\_nat (NAT router and a public-IPv4 bastion) or ipv6\_only (for a zone without public IPv4: no router, bastion reached over IPv6 and the Cloud's port forward, IPv4 egress through NAT64). Server default: ipv4\_nat |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--private-network-id` | | Adopt an existing private network instead of creating one |
| `--retention-policy` | | Teardown policy for volumes: retain or delete (server default: retain) |
| `--runtime-credential-id` | | Ankra Cloud credential for the in-cluster CCM/CSI (defaults to the provisioning credential) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--template` | | Server template (server default: debian-13; see 'ankracloud templates') |
| `--worker-count` | `0` | Default-pool worker count (server default: 1) |
| `--worker-disk-gib` | `0` | Worker root disk size in GiB (default: the plan's included disk). Ankra Cloud refuses a size below the plan's and the template's minimum |
| `--worker-disk-tier` | | Worker root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--worker-plan` | | Worker server plan (required while workers are above zero) |
| `--zone` | | Ankra Cloud zone (required; see 'ankracloud zones') |

## ankra cluster ankracloud deprovision

Permanently delete an Ankra Cloud cluster and the servers, network, router
and firewall rules Ankra created for it. An adopted private network is left in
place. Volumes follow the cluster's retention\_policy: 'retain' keeps them,
'delete' sweeps them. A 'delete' cluster's persistent volumes are named first
and deleted only when you accept that: answer the prompt on a terminal, or
pass `--accept-volume-data-loss` (`--yes` does not imply it).

```bash theme={null}
ankra cluster ankracloud deprovision <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-volume-data-loss` | `false` | Accept that deprovisioning deletes the cluster's persistent volumes (the cloud volumes its CSI driver provisioned) and the data on them, forced or not. Required when the cluster has such volumes, or Ankra cannot list them, and you are not answering the prompt on a terminal; `--yes` does not imply it. A cluster whose retention\_policy is retain (AWS, Scaleway, Ankra Cloud) keeps its volumes and needs no acknowledgement |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster ankracloud k8s-version

Get current Kubernetes version for an Ankra Cloud cluster

```bash theme={null}
ankra cluster ankracloud k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud networks

List the Ankra Cloud private networks a cluster can adopt

```bash theme={null}
ankra cluster ankracloud networks [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Ankra Cloud credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--zone` | | Only list the networks in this zone |

## ankra cluster ankracloud nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster ankracloud nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster ankracloud nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster ankracloud nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster ankracloud nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster ankracloud nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster ankracloud nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster ankracloud nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud plans

List the server plans (sizes) the create and node-group flags take.

Pass `--credential-id` to browse before creating a cluster, or `--cluster` to list
the plans under an existing cluster's own credential (for node groups and
control-plane or bastion resizes).

```bash theme={null}
ankra cluster ankracloud plans [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | List the plans under an existing cluster's own credential instead |
| `--credential-id` | | Ankra Cloud credential ID (required unless `--cluster` is given) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud preflight

Run the Ankra Cloud create preflight: credential, zone, plan and template
availability and the network, without building anything.

Takes the same flags as 'create'.

```bash theme={null}
ankra cluster ankracloud preflight [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-allowed-ips` | `[]` | CIDRs allowed to reach the bastion over SSH (default: anywhere) |
| `--bastion-disk-gib` | `0` | Bastion root disk size in GiB (default: the plan's included disk) |
| `--bastion-disk-tier` | | Bastion root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--bastion-plan` | | Bastion server plan (required) |
| `--cni` | | CNI plugin (server default: cilium; immutable after create) |
| `--control-plane-count` | `0` | Control plane node count (server default: 1) |
| `--control-plane-disk-gib` | `0` | Control plane root disk size in GiB (default: the plan's included disk) |
| `--control-plane-disk-tier` | | Control plane root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--control-plane-plan` | | Control plane server plan (required) |
| `--credential-id` | | Ankra Cloud credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-disk-gib` | `0` | External etcd node root disk size in GiB (default: the plan's included disk) |
| `--etcd-disk-tier` | | External etcd node root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--etcd-node-count` | `0` | External etcd node count, 3 or 5 (server default: 3) |
| `--etcd-plan` | | External etcd server plan (required with `--etcd-topology` external) |
| `--etcd-topology` | | etcd topology: stacked or external (server default: stacked) |
| `--gitops-branch` | | GitOps branch (server default: master) |
| `--gitops-credential-name` | | GitOps credential name (optional) |
| `--gitops-repository` | | GitOps repository URL (optional) |
| `--include-dns` | `true` | Provision the DNS zone |
| `--include-networking` | `true` | Provision the networking stack |
| `--kubernetes-version` | | Pin a Kubernetes version (default: latest supported) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | | RFC 1918 CIDR (/16 to /29) for the created private network (server default: a /24 derived from the cluster) |
| `--network-mode` | | Network mode: ipv4\_nat (NAT router and a public-IPv4 bastion) or ipv6\_only (for a zone without public IPv4: no router, bastion reached over IPv6 and the Cloud's port forward, IPv4 egress through NAT64). Server default: ipv4\_nat |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--private-network-id` | | Adopt an existing private network instead of creating one |
| `--retention-policy` | | Teardown policy for volumes: retain or delete (server default: retain) |
| `--runtime-credential-id` | | Ankra Cloud credential for the in-cluster CCM/CSI (defaults to the provisioning credential) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--template` | | Server template (server default: debian-13; see 'ankracloud templates') |
| `--worker-count` | `0` | Default-pool worker count (server default: 1) |
| `--worker-disk-gib` | `0` | Worker root disk size in GiB (default: the plan's included disk). Ankra Cloud refuses a size below the plan's and the template's minimum |
| `--worker-disk-tier` | | Worker root disk storage tier: local-nvme (the node's own disks), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--worker-plan` | | Worker server plan (required while workers are above zero) |
| `--zone` | | Ankra Cloud zone (required; see 'ankracloud zones') |

## ankra cluster ankracloud pricing

Show Ankra Cloud storage and public IPv4 prices

```bash theme={null}
ankra cluster ankracloud pricing [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Ankra Cloud credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud quota

Show the limits of the Ankra Cloud account behind an Ankra Cloud cluster, what the account already holds, and what is left: servers, cores, memory, storage, floating IPs, private networks and routers.

Storage is shared by server disks and every PersistentVolumeClaim the Ankra Cloud CSI provisions, so a claim larger than what is left stays Pending. Applies and stack deploys that need more storage than is left say so in their warnings.

Quota applies to Ankra Cloud clusters only: a cluster built on another provider, or imported, is refused with exit code 2.

```bash theme={null}
ankra cluster ankracloud quota <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud start

Start a stopped Ankra Cloud cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster ankracloud start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster ankracloud stop

Stop an Ankra Cloud cluster. A plain stop powers the servers off and keeps them with their disks; only a forced stop or a deprovision deletes servers.

```bash theme={null}
ankra cluster ankracloud stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and delete the servers instead of powering them off. The cluster's volumes are kept: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster ankracloud templates

List the operating-system templates Ankra Cloud servers boot

```bash theme={null}
ankra cluster ankracloud templates [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Ankra Cloud credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud workers

Get current worker count for an Ankra Cloud cluster

```bash theme={null}
ankra cluster ankracloud workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ankracloud zones

List the Ankra Cloud zones a credential can use

```bash theme={null}
ankra cluster ankracloud zones [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Ankra Cloud credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster apply

Apply an ImportCluster YAML to the Ankra API

```bash theme={null}
ankra cluster apply [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allow-repoint` | `false` | Allow this apply to change the cluster's GitOps repository or branch. Ankra writes the cluster's current state to the new source first, then syncs from it; anything that later leaves that source is pruned. A target that cannot be written leaves the cluster unchanged |
| `--allow-repoint-destroying-data` | `false` | Additionally allow a repoint on a cluster holding PersistentVolumeClaims, whose data is destroyed if the new source stops defining their workloads. Requires `--allow-repoint` |
| `--confirm-removal` | `[]` | Allow the apply to remove this member, which the file no longer lists, as kind/name (kind addon, manifest or application; repeatable) |
| `--dry-run` | `false` | Validate the ImportCluster YAML locally without calling the API |
| `-f`, `--file` | | Path to the ImportCluster YAML file to apply |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--prune` | `false` | Remove the members (add-ons, manifests, applications) of the file's stacks that the file no longer lists. Use it when the file is the complete, current definition of those stacks; without it, or `--confirm-removal`, such an apply is refused and changes nothing |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the configuration write to be applied and report its result. Add-on deploys are dispatched afterwards and are NOT covered by this flag - watch them with 'ankra cluster operations list' |

## ankra cluster aws

Manage the lifecycle of self-managed Kubernetes clusters Ankra builds on EC2.

These are k3s (or kubeadm) clusters on plain EC2 instances, not EKS. By
default Ankra creates the whole network for the cluster (VPC, subnets,
internet gateway, route tables, NAT) and removes it with the cluster; pass
`--vpc-id` to build inside a VPC you already own instead. For an EKS control
plane use 'ankra cluster managed'.

## ankra cluster aws access-info

Show the bastion and control plane IPs plus ready-to-use SSH jump and Kubernetes API port-forward commands.

```bash theme={null}
ankra cluster aws access-info <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws availability-zones

List the availability zones of a region

```bash theme={null}
ankra cluster aws availability-zones [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |

## ankra cluster aws bastion

Inspect and diagnose the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster aws bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster aws bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster aws bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster aws bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster aws control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster aws control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster aws control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws control-plane set-instance-type

Change the instance type of every controller in a AWS cluster.

The instance type is stored as given; it is not checked against AWS's catalog.
A name that does not exist is rejected by AWS itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster aws instance-types
```

```bash theme={null}
ankra cluster aws control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws create

Create an Ankra-managed k3s or kubeadm cluster on EC2 instances.

By default Ankra creates the whole network: a VPC from `--network-ip-range`
(default 10.0.0.0/16) with a public bastion subnet and private node subnets
in each of `--availability-zones` (default: one zone, or three when the
control plane has 3 or more nodes), an internet gateway, route tables and
the nodes' egress - 'nat\_gateway' (the default; one NAT gateway per zone, or
one in total with `--nat-gateway-single-zone`) or 'bastion\_nat' (the bastion is
the nodes' NAT, the cheapest option). The created network is Ankra's and is
deleted with the cluster.

Pass `--vpc-id` to build inside a VPC you already own instead: Ankra adopts
the VPC, `--node-subnet-ids` and `--bastion-subnet-id` and never creates or
deletes networking there. Egress is then detected from the node subnets'
route tables unless `--egress-mode` pins it: 'existing' uses the NAT gateway
or internet gateway the subnets already route through, 'bastion\_nat' makes
the bastion the NAT. `--network-ip-range`, `--availability-zones` and
`--nat-gateway-single-zone` do not apply to an adopted VPC.

In both modes Ankra owns the instances, security groups, the generated SSH
key and the bastion. Run 'preflight' first to check the region, the network
(ownership, zones, CIDR or the adopted subnets), instance-type availability
and the resolved egress mode.

Examples:

```bash theme={null}
# Ankra creates the network (default)
ankra cluster aws create --name prod --credential-id <id> \
  --ssh-key-credential-id <id> --region eu-north-1 \
  --bastion-allowed-ips 203.0.113.0/24

# ... spanning three zones with a single NAT gateway
ankra cluster aws create --name prod --credential-id <id> \
  --ssh-key-credential-id <id> --region eu-north-1 \
  --bastion-allowed-ips 203.0.113.0/24 --control-plane-count 3 \
  --availability-zones eu-north-1a,eu-north-1b,eu-north-1c \
  --nat-gateway-single-zone

# Build inside a VPC you already own
ankra cluster aws create --name prod --credential-id <id> \
  --ssh-key-credential-id <id> --region eu-north-1 --vpc-id vpc-0abc \
  --node-subnet-ids subnet-0aaa,subnet-0bbb --bastion-subnet-id subnet-0ccc \
  --bastion-allowed-ips 203.0.113.0/24
```

```bash theme={null}
ankra cluster aws create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--architecture` | | Node CPU architecture (server default: amd64; arm64 is refused until its image catalogue is audited) |
| `--availability-zones` | `[]` | Created network only: zones the subnets are created in, comma-separated (server default: 1 zone, or 3 when `--control-plane-count` is 3 or more) |
| `--bastion-allowed-ips` | `[]` | CIDRs allowed to reach the bastion over SSH, comma-separated (server default: 0.0.0.0/0 - open to everyone, key-only and rate-limited on the host; name your own CIDRs to restrict it) |
| `--bastion-instance-type` | | Bastion instance type (server default: t3.small) |
| `--bastion-subnet-id` | | Adopted VPC only: public subnet the bastion is placed in (required with `--vpc-id`) |
| `--cni` | | CNI plugin: cilium, calico or flannel (server default: cilium; kubeadm requires cilium; immutable after create) |
| `--cni-features` | `[]` | CNI features to switch on, comma-separated: kube\_proxy\_replacement, hubble, wireguard\_encryption, ebpf\_dataplane (default: all off) |
| `--control-plane-count` | `0` | Control plane node count, 1-9; at least 3 when the network spans more than one zone, and 3 or more makes a created network default to three zones (server default: 1) |
| `--control-plane-type` | | Control plane instance type (server default: t3.medium) |
| `--credential-id` | | AWS credential ID - an access key pair or an assumable role (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | | Kubernetes distribution: k3s or kubeadm (server default: kubeadm) |
| `--egress-mode` | | How the nodes reach the internet: 'nat\_gateway' (created network only; default for one), 'bastion\_nat' (either; the bastion is the NAT) or 'existing' (adopted VPC only; the subnets' own NAT or internet gateway, and the default there, detected from their route tables) |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `0` | External etcd node count, 3 or 5 (server default: 3) |
| `--etcd-topology` | | etcd topology: stacked or external (server default: stacked) |
| `--etcd-type` | | External etcd instance type (server default: t3.medium) |
| `--gitops-branch` | | GitOps branch (server default: master) |
| `--gitops-credential-name` | | GitOps GitHub credential name; when set with `--gitops-repository`, the generated stack is committed to Git |
| `--gitops-repository` | | GitOps repository (owner/repo) the generated stack is committed to |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Provision the networking stack (default on; pass `--include-networking=false` to skip) |
| `--k3s-disabled-components` | `[]` | k3s packaged components to disable, comma-separated (e.g. traefik,servicelb) |
| `--kubernetes-version` | | Pin a Kubernetes version (default: latest supported) |
| `--name` | | Cluster name (required) |
| `--nat-gateway-single-zone` | `false` | Created network only: with `--egress-mode` nat\_gateway, place one NAT gateway in the first zone instead of one per zone (cheaper, not zone-redundant) |
| `--network-ip-range` | | Created network only: CIDR of the VPC Ankra creates (server default: 10.0.0.0/16) |
| `--node-subnet-ids` | `[]` | Adopted VPC only: subnets the control plane and workers are spread across, comma-separated (required with `--vpc-id`) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |
| `--retention-policy` | | Teardown policy for EBS volumes and load balancers: retain or delete (server default: retain) |
| `--root-volume-gib` | `0` | Encrypted gp3 root volume size in GiB per instance, 20-2000 (server default: 40) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--ubuntu-series` | | Ubuntu series for the node AMI, e.g. 24.04 (server default: 24.04; see 'images') |
| `--vpc-id` | | Adopt an existing VPC instead of letting Ankra create the network; needs `--node-subnet-ids` and `--bastion-subnet-id` |
| `--worker-count` | `0` | Default-pool worker count (server default: 1) |
| `--worker-type` | | Worker instance type (server default: t3.medium) |

## ankra cluster aws deprovision

Permanently delete an AWS cluster and the provider resources Ankra created
for it: the instances, security groups, bastion and generated SSH key, and -
when Ankra created the network - the VPC, subnets, internet gateway, NAT
gateways, route tables and elastic IPs. An adopted VPC and its subnets are
never touched. EBS volumes and load balancers follow the cluster's
retention\_policy: 'retain' keeps them (forced or not, for the volumes),
'delete' sweeps them. A 'delete' cluster's persistent volumes are named
first and deleted only when you accept that: answer the prompt on a
terminal, or pass `--accept-volume-data-loss` (`--yes` does not imply it).

```bash theme={null}
ankra cluster aws deprovision <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-volume-data-loss` | `false` | Accept that deprovisioning deletes the cluster's persistent volumes (the cloud volumes its CSI driver provisioned) and the data on them, forced or not. Required when the cluster has such volumes, or Ankra cannot list them, and you are not answering the prompt on a terminal; `--yes` does not imply it. A cluster whose retention\_policy is retain (AWS, Scaleway, Ankra Cloud) keeps its volumes and needs no acknowledgement |
| `--force` | `false` | Force teardown: also delete the cluster's load balancers even when retention\_policy is retain, and tolerate unreachable infrastructure - the agent's dependency chain is skipped so the EC2 teardown runs even when the cluster can no longer be reached. It never deletes the persistent volumes of a retain cluster; a delete cluster's volumes need `--accept-volume-data-loss`, forced or not |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster aws images

List the Ubuntu series and CPU architectures a create may ask for with
`--ubuntu-series` and `--architecture`. The platform resolves the actual AMI at
build time, so there is no AMI id to pick.

```bash theme={null}
ankra cluster aws images [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |

## ankra cluster aws instance-types

List EC2 instance types available in a region

```bash theme={null}
ankra cluster aws instance-types [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |

## ankra cluster aws k8s-version

Get current Kubernetes version for an AWS cluster

```bash theme={null}
ankra cluster aws k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster aws nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster aws nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster aws nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster aws nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster aws nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster aws nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster aws nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws preflight

Run the AWS create preflight: credential and region reachability, the
network (a free CIDR and the zones for a created network; VPC and subnet
membership and bastion subnet routing for an adopted one), instance-type
and AMI availability, and what the server resolved - the network ownership
(created or adopted), the availability zones the network will span, and
the egress mode when `--egress-mode` is left unset.

Takes the same flags as 'create'.

```bash theme={null}
ankra cluster aws preflight [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--architecture` | | Node CPU architecture (server default: amd64; arm64 is refused until its image catalogue is audited) |
| `--availability-zones` | `[]` | Created network only: zones the subnets are created in, comma-separated (server default: 1 zone, or 3 when `--control-plane-count` is 3 or more) |
| `--bastion-allowed-ips` | `[]` | CIDRs allowed to reach the bastion over SSH, comma-separated (server default: 0.0.0.0/0 - open to everyone, key-only and rate-limited on the host; name your own CIDRs to restrict it) |
| `--bastion-instance-type` | | Bastion instance type (server default: t3.small) |
| `--bastion-subnet-id` | | Adopted VPC only: public subnet the bastion is placed in (required with `--vpc-id`) |
| `--cni` | | CNI plugin: cilium, calico or flannel (server default: cilium; kubeadm requires cilium; immutable after create) |
| `--cni-features` | `[]` | CNI features to switch on, comma-separated: kube\_proxy\_replacement, hubble, wireguard\_encryption, ebpf\_dataplane (default: all off) |
| `--control-plane-count` | `0` | Control plane node count, 1-9; at least 3 when the network spans more than one zone, and 3 or more makes a created network default to three zones (server default: 1) |
| `--control-plane-type` | | Control plane instance type (server default: t3.medium) |
| `--credential-id` | | AWS credential ID - an access key pair or an assumable role (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | | Kubernetes distribution: k3s or kubeadm (server default: kubeadm) |
| `--egress-mode` | | How the nodes reach the internet: 'nat\_gateway' (created network only; default for one), 'bastion\_nat' (either; the bastion is the NAT) or 'existing' (adopted VPC only; the subnets' own NAT or internet gateway, and the default there, detected from their route tables) |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `0` | External etcd node count, 3 or 5 (server default: 3) |
| `--etcd-topology` | | etcd topology: stacked or external (server default: stacked) |
| `--etcd-type` | | External etcd instance type (server default: t3.medium) |
| `--gitops-branch` | | GitOps branch (server default: master) |
| `--gitops-credential-name` | | GitOps GitHub credential name; when set with `--gitops-repository`, the generated stack is committed to Git |
| `--gitops-repository` | | GitOps repository (owner/repo) the generated stack is committed to |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Provision the networking stack (default on; pass `--include-networking=false` to skip) |
| `--k3s-disabled-components` | `[]` | k3s packaged components to disable, comma-separated (e.g. traefik,servicelb) |
| `--kubernetes-version` | | Pin a Kubernetes version (default: latest supported) |
| `--name` | | Cluster name (required) |
| `--nat-gateway-single-zone` | `false` | Created network only: with `--egress-mode` nat\_gateway, place one NAT gateway in the first zone instead of one per zone (cheaper, not zone-redundant) |
| `--network-ip-range` | | Created network only: CIDR of the VPC Ankra creates (server default: 10.0.0.0/16) |
| `--node-subnet-ids` | `[]` | Adopted VPC only: subnets the control plane and workers are spread across, comma-separated (required with `--vpc-id`) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |
| `--retention-policy` | | Teardown policy for EBS volumes and load balancers: retain or delete (server default: retain) |
| `--root-volume-gib` | `0` | Encrypted gp3 root volume size in GiB per instance, 20-2000 (server default: 40) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--ubuntu-series` | | Ubuntu series for the node AMI, e.g. 24.04 (server default: 24.04; see 'images') |
| `--vpc-id` | | Adopt an existing VPC instead of letting Ankra create the network; needs `--node-subnet-ids` and `--bastion-subnet-id` |
| `--worker-count` | `0` | Default-pool worker count (server default: 1) |
| `--worker-type` | | Worker instance type (server default: t3.medium) |

## ankra cluster aws pricing

Show the on-demand prices a cluster in a region is estimated from

```bash theme={null}
ankra cluster aws pricing [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |

## ankra cluster aws regions

List AWS regions available to a credential

```bash theme={null}
ankra cluster aws regions [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster aws start

Re-provision a stopped AWS cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster aws start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster aws stop

Stop an AWS cluster by terminating its EC2 instances while preserving its configuration so it can be re-provisioned later.

```bash theme={null}
ankra cluster aws stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and also delete the cluster's tagged load balancers even when retention\_policy is retain. The cluster's EBS volumes are kept: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster aws subnets

List the subnets of a VPC with their availability zone, how their route
table reaches the internet (egress: internet\_gateway, nat\_gateway,
nat\_instance, transit, none or unknown) and how many instances Ankra did
not create already live in them. Nodes go in private subnets (egress via a
NAT gateway, or via the bastion with `--egress-mode` bastion\_nat, which is
refused when a node subnet carries foreign instances); the bastion needs a
public one (internet\_gateway).

```bash theme={null}
ankra cluster aws subnets [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |
| `--vpc-id` | | VPC to list the subnets of (required) |

## ankra cluster aws vpcs

List the VPCs of a region with their CIDR and DHCP domain name. The DHCP
domain column is the domain the VPC's DHCP option set hands to instances;
"(none)" means the option set names no domain and "?" means it could not be
read, which is not the same thing.

```bash theme={null}
ankra cluster aws vpcs [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | AWS credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | AWS region, e.g. eu-north-1 (required) |

## ankra cluster aws workers

Get current worker count for an AWS cluster

```bash theme={null}
ankra cluster aws workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster backups

Read the cluster's backup posture: which stacks are protected, which hold data and are not, what each one can be restored from, and whether the backup components are installed on the cluster.

## ankra cluster backups status

Show what this cluster is backing up, one row per stack.

The verdict has three values, not two: "unknown" is a stack Ankra could not
assess - its inventory has not landed, or its backup settings could not be
read - and it is deliberately not reported as unprotected.

Examples:

```bash theme={null}
ankra cluster backups status
ankra cluster backups status --cluster production
ankra cluster backups status --protection unprotected
ankra cluster backups status --limit 10 --output json
```

```bash theme={null}
ankra cluster backups status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cursor` | | Continue from a previous page's cursor |
| `--limit` | `0` | Stacks per page (default 25, maximum 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--protection` | `[]` | Only stacks with this verdict: protected, unprotected, unknown (repeatable) |

## ankra cluster clear

Clear the active cluster selection

```bash theme={null}
ankra cluster clear
```

## ankra cluster clone

Clone stacks from an existing cluster ImportCluster YAML to a new cluster.

The source can be either a local file path or a URL (http/https).

Examples:

```bash theme={null}
ankra cluster clone cluster.yaml new-cluster.yaml
ankra cluster clone https://github.com/user/repo/raw/main/cluster.yaml new-cluster.yaml
ankra cluster clone cluster.yaml new-cluster.yaml --stack "monitoring" --stack "networking"
```

Flags:

```text theme={null}
--clean: Replace all stacks in the new cluster with those from the existing cluster
--force: Force merge even when stack/addon/manifest names conflict
--copy-missing: Copy missing files even for skipped stacks
--stack: Clone only specific stacks by name (can be used multiple times)
```

Without flags: Merge stacks, skipping any with conflicting names

```bash theme={null}
ankra cluster clone <existing_cluster_file_or_url> <new_cluster_path> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clean` | `false` | Replace all stacks in the new cluster |
| `--copy-missing` | `false` | Copy missing files even for skipped stacks |
| `--force` | `false` | Force merge even when names conflict |
| `--stack` | `[]` | Clone only specific stacks by name (can be used multiple times) |

## ankra cluster control-plane-heal

When a control plane node has been NotReady for several minutes while every other
control plane node is Ready and etcd keeps quorum without it, Ankra can restart
that one node through your cloud provider. It never stops, scales or deletes
anything, and it shows each step on the cluster in the product.

The switch is per cluster and on by default. Turning it off stops the restart
only: the NotReady card is still shown. Changing it needs permission to change
cluster settings (clusters.write).

**Examples**

```bash theme={null}
ankra cluster control-plane-heal get
ankra cluster control-plane-heal set --enabled=false --cluster prod
```

## ankra cluster control-plane-heal get

Show whether Ankra may restart a NotReady control plane of the cluster, and the
latest episode: which node, how it ended or why Ankra is not restarting it yet,
and whether the platform acted or only recorded what it would have done
(shadow).

-o json prints the platform's answer as it is.

```bash theme={null}
ankra cluster control-plane-heal get [flags]
```

**Examples**

```bash theme={null}
ankra cluster control-plane-heal get
ankra cluster control-plane-heal get --cluster prod -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster control-plane-heal set

Turn Ankra's automatic restart of a NotReady control plane on or off for the
cluster. `--enabled` is required, so a change is always explicit. Turning it off
sends nothing anywhere, so this does not ask for confirmation.

```bash theme={null}
ankra cluster control-plane-heal set --enabled=true|false [flags]
```

**Examples**

```bash theme={null}
ankra cluster control-plane-heal set --enabled=false
ankra cluster control-plane-heal set --enabled=true --cluster prod
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--enabled` | `false` | Whether Ankra may restart a NotReady control plane (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster cordon

Mark a node unschedulable so no new pods land on it. Pods already running
stay where they are; 'cluster drain' moves them off. 'cluster uncordon' puts
the node back into service.

Example:

```bash theme={null}
ankra cluster cordon worker-3
```

```bash theme={null}
ankra cluster cordon <node>
```

## ankra cluster custom-dns-zones

Declare, list, and withdraw the DNS zones a cluster serves with one of the
organisation's own DNS credentials - an external-dns webhook credential or a
Cloudflare credential - alongside the generated domain Ankra serves itself.

The external-dns Ankra manages publishes only under the cluster's generated
subdomain: its credential is scoped to that zone by the DNS provider, so
ingress hostnames on your own zones are dropped silently. Declaring a zone
here has Ankra render and reconcile a separate external-dns for it, using a
credential you supply ('ankra org dns credentials', or 'ankra org cloudflare
connect' for a Cloudflare zone). Each controller is
pinned to exactly its zone with its own record ownership, so it can never
fight Ankra's controller or another cluster's.

To serve a zone from every cluster in the organisation - including clusters
created later - declare it once with 'ankra org custom-dns-zones add'
instead. 'list' shows those inherited zones with source 'organisation'; a
zone declared here on the cluster itself takes precedence over the
organisation's on this cluster, which is how one cluster serves a zone with
a different credential.

Withdrawing a zone removes the controller Ankra rendered; the zone's records
are yours and are left untouched.

## ankra cluster custom-dns-zones add

Declare a zone the cluster also serves, with the DNS credential that can
publish into it. Ankra renders an external-dns for the zone on the next
reconciler pass, scoped to exactly that zone.

Use `--cloudflare-credential` for a zone hosted at Cloudflare: it names an
organisation Cloudflare credential ('ankra org cloudflare connect') and the
zone is published by external-dns's native Cloudflare provider. Before storing
anything Ankra checks with Cloudflare that the credential's token can reach the
zone with DNS edit. That controller runs upsert-only: it creates and updates
only the records it owns and never changes or deletes a record someone else
made, so hand-made records in the zone are safe. Opt an Ingress host into
Cloudflare's proxy with the external-dns.alpha.kubernetes.io/cloudflare-proxied
annotation.

```bash theme={null}
ankra cluster custom-dns-zones add prod --zone ankra.cloud --cloudflare-credential ankra-cloudflare
ankra cluster custom-dns-zones add prod --zone launch.example.com --credential example-dns
```

Refused when the zone is not a domain name, when the organisation has no
credential of that name (or, with `--cloudflare-credential`, no Cloudflare
credential of that name), when a Cloudflare token cannot reach the zone or may
not edit its DNS, or when the zone overlaps the generated domain Ankra already
serves for this cluster - that would put a second controller on names Ankra's
own external-dns publishes.

```bash theme={null}
ankra cluster custom-dns-zones add <cluster> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cloudflare-credential` | | Name of the organisation Cloudflare credential that publishes into the zone with the native Cloudflare provider |
| `--credential` | | Name of the organisation credential that publishes into the zone, of whichever kind (this or `--cloudflare-credential` is required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--zone` | | Zone to declare, e.g. launch.example.com (required) |

## ankra cluster custom-dns-zones list

List the zones declared on a cluster

```bash theme={null}
ankra cluster custom-dns-zones list <cluster> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster custom-dns-zones remove

Withdraw a declared zone. Ankra removes the controller it rendered on the
next reconciler pass. The zone's records are yours and are left untouched.

```bash theme={null}
ankra cluster custom-dns-zones remove <cluster> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--zone` | | Zone to withdraw (required) |

## ankra cluster debug

Debug pods are pods Ankra creates on your behalf, in any namespace of the
active cluster, from an image chosen for its tools rather than for the
workload. Point one at an existing pod with `--from-pod` and it impersonates
that pod: the same service account, node, volumes and volume mounts,
environment variables and envFrom sources, tolerations and security
context - under an image that actually has curl, dig, psql or strace in it.
The workload itself is never touched.

Labels are never copied, so a debug pod never sits behind the workload's
Service. Every debug pod carries a lifetime the kubelet enforces on its own,
and every terminal session into one is recorded to the audit log.

## ankra cluster debug create

Create a debug pod in a namespace of the active cluster and wait for it to
start. With `--from-pod` the pod impersonates the named pod - its service
account, node, volumes and mounts, environment - so what the workload's
container sees, the debug pod sees. Without `--from-pod` it is a plain pod of
the chosen image with no service-account token.

The command prints the portal link to the new pod's terminal; every session
opened there is recorded to the audit log. Creating a debug pod needs the
kubernetes.write and kubernetes.exec permissions.

Examples:

```bash theme={null}
ankra cluster debug create -n payments --from-pod api-6d8f9c7b5-x2kq9
ankra cluster debug create -n payments --from-pod api-6d8f9c7b5-x2kq9 --container sidecar --no-env
ankra cluster debug create -n payments --image docker.io/library/alpine:3.21 --ttl 2h
ankra cluster debug create -n payments --from-pod api-6d8f9c7b5-x2kq9 -o json
```

```bash theme={null}
ankra cluster debug create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-a`, `--attach` | `false` | Open a shell in the debug pod as soon as it runs (see "cluster terminal") |
| `-c`, `--container` | | Container of `--from-pod` whose mounts and environment to mirror (default: the first) |
| `--from-pod` | | Pod to impersonate: its service account, node, volumes, mounts and environment are mirrored |
| `--image` | | Debug image (default: the catalogue's default; see "debug images") |
| `-n`, `--namespace` | | Namespace to create the debug pod in (required) |
| `--no-env` | `false` | Do not mirror the target's environment variables |
| `--no-mounts` | `false` | Do not mirror the target's volumes and volume mounts |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--shell` | `/bin/sh` | Path of the shell to start with `--attach` (one executable, not a command line) |
| `--ttl` | `1h0m0s` | How long the pod lives before the kubelet ends it (1m-8h) |

## ankra cluster debug delete

Delete a debug pod before its lifetime ends. Only a pod carrying the
ankra.io/debug-pod label can be deleted this way; a workload pod answers
not found.

```bash theme={null}
ankra cluster debug delete <pod_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-n`, `--namespace` | | Namespace of the debug pod (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster debug images

List the tag-pinned images the platform offers for debug pods. Any image
reference is accepted by "debug create `--image`"; the catalogue is the set
that ships with tools and is known to pull.

```bash theme={null}
ankra cluster debug images [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster debug list

List the debug pods on the active cluster

```bash theme={null}
ankra cluster debug list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-n`, `--namespace` | | Only list debug pods in this namespace |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster decrypt

Decrypt SOPS-encrypted values stored on a cluster or in a local cluster.yaml.

## ankra cluster decrypt addon

Decrypt a SOPS-encrypted addon's Helm values and print the result to stdout.

Two modes:

Cluster mode (default): fetch the addon values from a live cluster, decrypt,
and print to stdout.

File mode (-f cluster.yaml): read the addon values file referenced from a
local cluster.yaml, decrypt, and print to stdout.

Examples:

```bash theme={null}
ankra cluster decrypt addon --name grafana
ankra cluster decrypt addon --name grafana --cluster prod --stack monitoring
ankra cluster decrypt addon --name grafana -f cluster.yaml
```

```bash theme={null}
ankra cluster decrypt addon [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection (cluster mode) |
| `-f`, `--file` | | Path to a local cluster YAML (enables file mode) |
| `--name` | | Name of the addon (required) |
| `--stack` | | Stack name (cluster mode; required when the addon exists in multiple stacks) |

## ankra cluster decrypt manifest

Decrypt a SOPS-encrypted manifest and print the result to stdout.

Two modes:

Cluster mode (default): fetch the manifest from a live cluster, decrypt it,
and print to stdout.

File mode (-f cluster.yaml): read the manifest file referenced from a local
cluster.yaml, decrypt it, and print to stdout.

Examples:

```bash theme={null}
# Cluster mode against the selected cluster
ankra cluster decrypt manifest db-secret

# Cluster mode against a specific cluster
ankra cluster decrypt manifest db-secret --cluster prod

# File mode
ankra cluster decrypt manifest db-secret -f cluster.yaml
```

```bash theme={null}
ankra cluster decrypt manifest <manifest_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection (cluster mode) |
| `-f`, `--file` | | Path to a local cluster YAML (enables file mode) |

## ankra cluster delete

Delete one or more Kubernetes resources from the active cluster.

The kind takes the kubectl spellings - pod, pods, po, deployment, deploy,
statefulset, sts, configmap, cm, namespace, node, pvc, ... - and a custom
resource is reachable with `--group` and `--api-version`, exactly like
'cluster get resources' and 'cluster describe'. Cluster-scoped built-in
kinds (namespace, node, storageclass, crd, priorityclass, the webhook
configurations, ...) need no namespace; a cluster-scoped custom kind such as
a ClusterIssuer or a ClusterPolicy takes `--cluster-scoped` instead.

A pod owned by a controller (Deployment, StatefulSet, DaemonSet, Job) is
recreated by that controller, so deleting it is how you restart a single
replica; 'cluster restart' rolls a whole workload. The delete goes through
the cluster's Ankra agent: no kubeconfig is needed and the same organisation
permissions as the portal apply.

Each object reports its own outcome. The command exits 0 when everything was
deleted, 3 when one of the objects did not exist, and 1 when the cluster
refused a delete.

Examples:

```bash theme={null}
ankra cluster delete pod my-pod -n default
ankra cluster delete pods web-0 web-1 -n prod --yes
ankra cluster delete pod stuck-pod -n default --grace-period 0
ankra cluster delete deployment web -n prod --dry-run
ankra cluster delete namespace scratch
ankra cluster delete Certificate web-tls -n prod --group cert-manager.io --api-version v1
ankra cluster delete crd kafkas.kafka.strimzi.io kafkatopics.kafka.strimzi.io
ankra cluster delete ClusterIssuer letsencrypt-staging --group cert-manager.io --api-version v1 --cluster-scoped
```

```bash theme={null}
ankra cluster delete <kind> <name> [name...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-version` | | API version for a kind outside the built-in set (e.g. v1, v1beta1) |
| `--cluster-scoped` | `false` | Treat a kind outside the built-in set as cluster-scoped (e.g. ClusterIssuer, ClusterPolicy); no `--namespace` is needed |
| `--dry-run` | `false` | Report what would be deleted without deleting anything |
| `--grace-period` | `-1` | Seconds the object gets to shut down cleanly; 0 deletes it immediately, -1 keeps the object's own grace period |
| `--group` | | API group for a kind outside the built-in set (e.g. cert-manager.io) |
| `-n`, `--namespace` | | Kubernetes namespace (required for namespaced kinds) |
| `--resource` | | Exact API resource plural when a custom kind has an irregular plural (e.g. backuprepositories) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster deprovision

Tear down a managed cluster: everything it runs on is released.

Whether the cluster survives as a record depends on its kind, and the two
outcomes are very different:

* cloud clusters (hetzner, ovh, upcloud, digitalocean, scaleway, ankracloud, aws, proxmox, morpheus)
  go to the provider-specific endpoint, which DELETES the cluster. The
  record does not survive, "ankra cluster provision" cannot bring it back,
  and the cluster id, its stacks and anything referencing them are gone.
  Rebuilding means creating a new cluster;
* imported clusters keep their record, so "ankra cluster provision" can
  rebuild them from the stored stack definition later.

This is a teardown, not a power-off:

* all cloud resources are released (servers, networks, SSH keys);
* every stack resource on the cluster is uninstalled;
* on hetzner, ovh, upcloud, digitalocean, scaleway, ankracloud and aws the cluster's
  persistent volumes (the cloud volumes its CSI driver provisioned) are
  deleted with it, and the data on them. The command names them first and
  deletes them only when you accept that: answer the prompt on a terminal,
  or pass `--accept-volume-data-loss` (`--yes` does not imply it). A cluster
  whose retention\_policy is retain (aws, scaleway, ankracloud) keeps its volumes, which
  keep billing in your cloud account.

To power a cluster off and back on while keeping its state, use the provider's
stop/start commands (for example "ankra hetzner cluster stop" and
"ankra hetzner cluster start") or "ankra cluster power-schedules" instead.

If no cluster name is provided, uses the currently selected cluster.

```bash theme={null}
ankra cluster deprovision [cluster_name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-volume-data-loss` | `false` | Accept that deprovisioning deletes the cluster's persistent volumes (the cloud volumes its CSI driver provisioned) and the data on them, forced or not. Required when the cluster has such volumes, or Ankra cannot list them, and you are not answering the prompt on a terminal; `--yes` does not imply it. A cluster whose retention\_policy is retain (AWS, Scaleway, Ankra Cloud) keeps its volumes and needs no acknowledgement |
| `--force` | `false` | Force deprovision even if cluster is in an unexpected state; on UpCloud, Hetzner, OVH, DigitalOcean and AWS also deletes leftover load balancers (the persistent volumes are deleted forced or not, and only with `--accept-volume-data-loss` or a yes at the prompt); on Proxmox finishes the teardown when the host or jumphost is unreachable, leaving the VMs behind |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt (not the persistent volume acknowledgement) |

## ankra cluster describe

Show a single Kubernetes resource together with the events scoped to it.

This answers the question a failing workload raises - why is it not ready? -
in one call: the object's conditions, a pod's per-container state (probe
failures, image-pull errors, OOMKills, exit codes), and the events whose
involvedObject is this resource, rather than a namespace-wide event list you
have to filter by eye.

Kinds outside the built-in set need `--group` (and sometimes `--api-version`),
exactly like 'cluster get resources'.

Examples:

```bash theme={null}
ankra cluster describe pod web-7d9f-2xkvp -n default
ankra cluster describe deployment web -n default
ankra cluster describe node worker-1
ankra cluster describe pvc data-web-0 -n default -o json
```

```bash theme={null}
ankra cluster describe <kind> <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-version` | | API version for a kind outside the built-in set (e.g. v1, v1beta1) |
| `--cluster-scoped` | `false` | Treat a kind outside the built-in set as cluster-scoped (e.g. ClusterIssuer, ClusterPolicy); no `--namespace` is needed |
| `--group` | | API group for a kind outside the built-in set (e.g. cert-manager.io) |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `--resource` | | Exact API resource plural when a custom kind has an irregular plural (e.g. backuprepositories) |

## ankra cluster digitalocean

Commands to create, deprovision, and scale DigitalOcean clusters.

## ankra cluster digitalocean bastion

Inspect, diagnose, and resize the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster digitalocean bastion allowed-ips

Replace the bastion/gateway's SSH source allowlist. Only the listed IPv4
addresses or CIDRs, the platform's own egress addresses and private network
sources can then reach port 22; every other source is dropped. The platform's
egress is always added by the platform itself, so it can never be locked out.

The list you give is the complete new list: entries may be separated by
spaces or commas. `--clear` removes the allowlist and makes the bastion
reachable from anywhere again (key-only SSH, rate-limited). IPv6 entries and
0.0.0.0/0 are refused; at most 64 entries.

The platform applies the list through the bastion update operation reported
on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

Examples:

```bash theme={null}
ankra cluster hetzner bastion allowed-ips my-cluster 203.0.113.7 198.51.100.0/24
ankra cluster ovh bastion allowed-ips my-cluster --clear
```

```bash theme={null}
ankra cluster digitalocean bastion allowed-ips <cluster_id|name> [ip-or-cidr ...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove the allowlist: SSH from anywhere again |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster digitalocean bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster digitalocean bastion resize

Resize the bastion/gateway node. The provider's bastion/gateway update job
powers it off, resizes it, and powers it back on, causing brief SSH/NAT
downtime for the cluster.

`--wait` covers the platform write only; the cloud resize runs as the operation
reported on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

```bash theme={null}
ankra cluster digitalocean bastion resize <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster digitalocean bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster digitalocean bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster digitalocean control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster digitalocean control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster digitalocean control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean control-plane set-instance-type

Change the instance type of every controller in a DigitalOcean cluster.

The instance type is stored as given; it is not checked against DigitalOcean's catalog.
A name that does not exist is rejected by DigitalOcean itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster digitalocean sizes
```

```bash theme={null}
ankra cluster digitalocean control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean create

Create a new DigitalOcean cluster

```bash theme={null}
ankra cluster digitalocean create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-allowed-ips` | `[]` | IPv4 addresses or CIDRs allowed to reach the bastion over SSH, comma-separated (the platform's own egress is always allowed too; IPv6 and 0.0.0.0/0 are refused). Omit to keep the bastion reachable from anywhere (key-only SSH, rate-limited). Change it later with 'bastion allowed-ips'. |
| `--bastion-size` | | Bastion droplet size (server default: s-1vcpu-1gb) |
| `--control-plane-count` | `1` | Number of control plane nodes |
| `--control-plane-size` | | Control plane droplet size (server default: s-2vcpu-4gb) |
| `--credential-id` | | DigitalOcean API credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm (default, vanilla upstream Kubernetes with Cilium) or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `3` | Number of dedicated etcd nodes when `--etcd-topology=external` (3 or 5) |
| `--etcd-size` | | Droplet size for dedicated etcd nodes when `--etcd-topology=external` (server default: s-2vcpu-4gb) |
| `--etcd-topology` | `stacked` | etcd topology for kubeadm clusters: stacked (on control plane) or external (dedicated VMs) |
| `--external-cloud-provider` | `true` | Install the DigitalOcean CCM and CSI (cloud-provider=external) for LoadBalancers and persistent volumes (default on; pass `--external-cloud-provider=false` to skip, which also disables `--include-networking`) |
| `--gitops-branch` | `master` | GitOps branch to commit to |
| `--gitops-credential-name` | | GitOps GitHub credential name; when set with `--gitops-repository`, the generated digitalocean-cloud-provider stack is committed to Git (optional) |
| `--gitops-repository` | | GitOps repository (e.g. org/repo) to commit the generated stack to (optional) |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Install Traefik + cert-manager for ingress (default on; pass `--include-networking=false` to skip). Requires `--external-cloud-provider` (the ingress LoadBalancer is provisioned by the cloud controller manager) |
| `--kubernetes-version` | | Kubernetes version (optional; see `ankra cluster kubeadm-versions` or `ankra cluster k3s-versions`) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | | VPC IP range (optional). Left unset, the platform derives a /24 from the cluster id, so clusters in one account do not all ask for the same range; pass one only to pin it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | DigitalOcean region (required) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--worker-count` | `1` | Number of worker nodes |
| `--worker-size` | | Worker droplet size (server default: s-2vcpu-4gb) |

## ankra cluster digitalocean k8s-version

Get current Kubernetes version for an DigitalOcean cluster

```bash theme={null}
ankra cluster digitalocean k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean node-group

List, add, scale, upgrade, and delete node groups.

## ankra cluster digitalocean nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster digitalocean nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster digitalocean nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster digitalocean nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster digitalocean nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster digitalocean nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster digitalocean nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster digitalocean nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster digitalocean regions

List the DigitalOcean regions the supplied credential can deploy in.

```bash theme={null}
ankra cluster digitalocean regions [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | DigitalOcean API credential ID (required) |

## ankra cluster digitalocean sizes

List DigitalOcean droplet sizes. Pass `--region` to filter by region availability.

```bash theme={null}
ankra cluster digitalocean sizes [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--available-only` | `false` | Show only sizes available in the selected region |
| `--credential-id` | | DigitalOcean API credential ID (required) |
| `--region` | | Filter by region slug |

## ankra cluster digitalocean start

Start (re-provision) a stopped DigitalOcean cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster digitalocean start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster digitalocean stop

Stop an DigitalOcean cluster's compute while keeping its configuration so it can be started again later.

```bash theme={null}
ankra cluster digitalocean stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and also delete the cluster's load balancers. The cluster's block storage volumes are kept and keep billing while stopped: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster digitalocean workers

Get current worker count for an DigitalOcean cluster

```bash theme={null}
ankra cluster digitalocean workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster domain

Show the cluster's generated public domain. The domain nests under the
organisation's Ankra-managed root - ankra.cc by default, or the organisation's
own domain when one is registered (portal: AI > Settings > Workspaces, field
"Custom Ankra domain"; CLI: 'ankra org domain').

The read also reports the cluster's PUBLIC domain: the domain hostnames on the
cluster are published under, and what \$\{\{ ankra.cluster\_domain }} resolves to
in stacks and stack profiles. It is the organisation's preview domain
('ankra org ai-environment set `--demo-base-domain`') whenever a custom DNS zone
declared for the organisation or the cluster ('ankra org custom-dns-zones',
'ankra cluster custom-dns-zones') covers it - the cluster's own external-dns
then publishes every hostname under it - and the generated domain otherwise.
An organisation whose domain cannot be registered as the Ankra root (it lives
in its own DNS account) gets its own domain as the cluster domain this way.

The plain command is a read: it never creates a zone. A cluster that has no
domain reports state "none", and 'ankra org dns zones' lists every cluster in
the organisation that does have one.

`--enable` queues the zone for a cluster that has none. It is idempotent: a
cluster that already has a zone reports its existing domain unchanged. A fresh
zone reads "pending" until it is published to the authoritative nameservers
and then turns "active"; external-dns is wired to it on the next
cloud-provider pass, after which any ingress hostname under the domain
resolves with TLS.

`--remove` hands the zone back for teardown: the removal step before an
organisation switches its Ankra root domain (the switch is refused while
cluster zones still live under the old root). The removal is then HELD -
nothing re-creates the zone, including the external-dns Ankra runs on the
cluster and the discovery that mints zones for clusters that lack one - until
you ask for it back. A read reports "opted out" for as long as the hold
stands.

`--enable` withdraws the hold and re-creates the zone under the organisation's
current root. The cluster's label is derived from its id, so the zone comes
back under exactly the name it had before, and the external-dns Ankra manages
for it keeps the same `--txt-owner-id`.

```bash theme={null}
ankra cluster domain [cluster] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--enable` | `false` | Create the cluster's generated public domain if it does not have one (idempotent) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--remove` | `false` | Remove the cluster's generated public domain (tear the zone down) |

## ankra cluster draft

Stage all changes in an ImportCluster YAML as drafts on the cluster
without deploying anything. The local checks run first (the same ones as
'ankra cluster apply `--dry-run`'), then each stack in the file is saved as a
resource draft you can review, edit, and deploy from the Ankra stack builder.

If the cluster does not exist yet it is imported first without its stacks,
since drafts can only be attached to an existing cluster; every stack in the
file is then staged as a draft. Stacks that already match the cluster's
desired state are reported as "no changes" rather than creating an empty
draft.

```bash theme={null}
ankra cluster draft [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-f`, `--file` | | Path to the ImportCluster YAML file to stage as drafts |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster drain

Cordon a node, then delete every pod scheduled on it so its controller
reschedules the pod elsewhere. DaemonSet pods are left alone (they would
come straight back on the same node) and so are the static pods the kubelet
runs from disk. A pod without a controller is deleted like any other and is
not recreated - the plan names every pod before anything happens, and
`--dry-run` stops after printing it.

Unlike 'kubectl drain', the pods are deleted rather than evicted: the Ankra
agent has no eviction relay yet, so PodDisruptionBudgets are not consulted
and a budget at its limit does not hold the drain back. Check the budgets in
the namespaces you care about ('cluster get resources PodDisruptionBudget
`--group` policy') before draining a node that carries a quorum member.

The node stays cordoned afterwards; run 'cluster uncordon' to put it back
into service.

Examples:

```bash theme={null}
ankra cluster drain worker-3
ankra cluster drain worker-3 --grace-period 30 --yes
ankra cluster drain worker-3 --dry-run
```

```bash theme={null}
ankra cluster drain <node> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--dry-run` | `false` | Print the plan without cordoning or deleting anything |
| `--grace-period` | `-1` | Seconds each pod gets to shut down cleanly; 0 deletes immediately, -1 keeps each pod's own grace period |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster encrypt

Encrypt sensitive values in manifest or addon configuration files using SOPS.

## ankra cluster encrypt addon

Encrypt one or more keys in an addon's Helm values using SOPS.

`--key` takes the YAML key name whose values should be encrypted. Repeat `--key` to
encrypt several keys in a single run; all keys are encrypted in one SOPS pass
and one write. SOPS matches key names anywhere in the document, not dotted
paths; a dotted `--key` is normalised to its last segment. A key whose own name
starts with a dot (such as ".dockerconfigjson") is kept literally. After
encrypting, the CLI verifies every value is actually ENC\[...] ciphertext and
fails if any is not.

`--key` glob:\<pattern> encrypts every key whose name matches the pattern, now
and on every later platform re-encrypt - including keys added afterwards.
Only "\*" is a wildcard; everything else is literal. The entry is recorded in
encrypted\_paths as written ("glob:\*Password"). A pattern that matches no key
fails, the same way a misspelled exact key does. Requires cluster#1867 on the
platform.

Two modes:

Cluster mode (default): fetch the addon's values from a live cluster,
encrypt the key together with every key the addon already declares in
encrypted\_paths (a declared value can still be stored as plaintext until
the next GitOps push seals it), and push the result back via the
partial-stack PATCH endpoint. The owning stack is resolved automatically.

File mode (-f cluster.yaml): rewrite the local addon values file referenced
by the cluster.yaml in place, adding the key to encrypted\_paths. Keys the
file already declares are sealed together with `--key`.

Examples:

```bash theme={null}
# Cluster mode against the selected cluster
ankra cluster encrypt addon --name grafana --key adminPassword

# Cluster mode against a specific cluster, disambiguating stack
ankra cluster encrypt addon --name grafana --key adminPassword --cluster prod --stack monitoring

# Encrypt several keys in one run
ankra cluster encrypt addon --name grafana --key adminPassword --key smtpPassword

# Encrypt every *Password key, including ones added later
ankra cluster encrypt addon --name grafana --key 'glob:*Password' --cluster prod

# File mode
ankra cluster encrypt addon --name grafana --key adminPassword -f cluster.yaml
```

```bash theme={null}
ankra cluster encrypt addon [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection (cluster mode) |
| `-f`, `--file` | | Path to a local cluster YAML (enables file mode) |
| `--key` | `[]` | YAML key name to encrypt (required; repeatable), or glob:\<pattern> to encrypt every key whose name matches (only \* is a wildcard, e.g. glob:\*Password); dotted paths are normalised to the last segment, a leading-dot key like .dockerconfigjson is kept literally |
| `--name` | | Name of the addon (required) |
| `--stack` | | Stack name (cluster mode; required when the addon exists in multiple stacks) |

## ankra cluster encrypt manifest

Encrypt one or more keys in a manifest using SOPS.

`--key` takes the YAML key name whose values should be encrypted (for a Secret's
data.password, that is "password"). Repeat `--key` to encrypt several keys in a
single run; all keys are encrypted in one SOPS pass and one write. SOPS matches
key names anywhere in the document, not dotted paths; a dotted `--key` is
normalised to its last segment. A key whose own name starts with a dot (such as
".dockerconfigjson" in a kubernetes.io/dockerconfigjson Secret) is kept
literally. After encrypting, the CLI verifies every value is actually ENC\[...]
ciphertext and fails if any is not.

`--key` glob:\<pattern> encrypts every key whose name matches the pattern, now
and on every later platform re-encrypt - including keys added afterwards.
Only "*" is a wildcard (any run of characters); everything else is literal,
and a leading "data." or "stringData." is accepted and ignored, exactly as for
an exact key. The entry is recorded in encrypted\_paths as written
("glob:stringData.DB\_*"), which is the form the platform re-expands into the
SOPS encrypted\_regex on every push. A pattern that matches no key fails, the
same way a misspelled exact key does. Requires cluster#1867 on the platform.

`--all-data` selects every key under data and stringData of a Kubernetes Secret
manifest instead of naming keys individually; keys whose values are already
encrypted are skipped. The manifest must be a Secret. `--all-data` and `--key` are
mutually exclusive.

Two modes:

Cluster mode (default): fetch the manifest from a live cluster, encrypt the
key, and push the result back via the partial-stack PATCH endpoint. The
owning stack is resolved automatically.

File mode (-f cluster.yaml): rewrite a local cluster.yaml's referenced
from\_file in place, adding the key to encrypted\_paths in the file. Used by
GitOps workflows where the source of truth is on disk. Every key the file
already declares in encrypted\_paths is sealed together with `--key`, so a
document decrypted with "ankra cluster decrypt" (which leaves the
declaration in place) is sealed whole again.

In cluster mode, `--set` applies value edits in-memory BEFORE encrypting, so the
new secret value and its encryption land in a single commit - the plaintext
value never reaches git history. This is the recommended way to set a new
secret value:

```bash theme={null}
ankra cluster encrypt manifest db-secret --key password \
  --set 'data.password=aHVudGVyMg==' --cluster prod
```

(compared to "manifests upgrade `--set`" followed by "encrypt manifest", which
commits the plaintext value first).

`--set` also replaces a value that is already encrypted, which is how a sealed
credential is rotated in place. A manifest that carries SOPS metadata is
decrypted in memory, the edits are applied, and every key that was encrypted
is encrypted again together with `--key`, still in a single write. A key whose
name starts with a dot is escaped in the `--set` path:

```bash theme={null}
ankra cluster encrypt manifest registry --key .dockerconfigjson \
  --set 'data.\.dockerconfigjson=<new base64>' --cluster prod
```

In cluster mode every key the manifest already declares in encrypted\_paths is
sealed together with `--key`. A value declared in the portal or through the API
is stored as plaintext until the next GitOps push seals it, and a document
that carries SOPS metadata with plaintext under a declared path is refused by
the platform, so sealing only the new key would be rejected.

Examples:

```bash theme={null}
# Cluster mode against the selected cluster
ankra cluster encrypt manifest db-secret --key password

# Cluster mode against a specific cluster
ankra cluster encrypt manifest db-secret --key password --cluster prod

# Set a new value and encrypt it atomically (single commit, no plaintext)
ankra cluster encrypt manifest db-secret --key password \
  --set 'data.password=bmV3LXNlY3JldA==' --cluster prod

# Encrypt several keys in one run
ankra cluster encrypt manifest db-secret --key password --key api-token

# Encrypt every data/stringData key of a Secret manifest
ankra cluster encrypt manifest db-secret --all-data --cluster prod

# Encrypt every DB_* key, including ones added later
ankra cluster encrypt manifest db-secret --key 'glob:stringData.DB_*' --cluster prod

# File mode
ankra cluster encrypt manifest db-secret --key password -f cluster.yaml
```

```bash theme={null}
ankra cluster encrypt manifest <manifest_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-data` | `false` | Encrypt every key under data and stringData of a Secret manifest, skipping values that are already encrypted |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection (cluster mode) |
| `-f`, `--file` | | Path to a local cluster YAML (enables file mode) |
| `--key` | `[]` | YAML key name to encrypt (repeatable), or glob:\<pattern> to encrypt every key whose name matches (only \* is a wildcard, e.g. glob:stringData.DB\_\*); dotted paths are normalised to the last segment, a leading-dot key like .dockerconfigjson is kept literally |
| `--set` | `[]` | Apply value edits in-memory before encrypting (same syntax as manifests upgrade `--set`, e.g. `--set 'data.password=bmV3'`); the plaintext value never reaches git (cluster mode only; repeatable) |

## ankra cluster events

List Kubernetes events from the active cluster.

`--for` scopes the listing to a single object's involvedObject, which is what
turns "the pod is Pending" into "no node matches the nodeSelector". This is
a server-side field selector, not a substring match on the event text, so
an object whose name is a prefix of another object's name is not conflated
with it.

Examples:

```bash theme={null}
ankra cluster events -n default
ankra cluster events --for pod/web-7d9f-2xkvp -n default
ankra cluster events --for deployment/web -n default --type Warning
ankra cluster events --all-namespaces --type Warning -o json
```

```bash theme={null}
ankra cluster events [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--for` | | Scope to one object's events, as kind/name (e.g. pod/web-7d9f-2xkvp) |
| `--name` | | Filter by the Event resource's own name; to scope by the object an event is about, use `--for` |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |
| `--type` | | Filter by event type: Normal or Warning |

## ankra cluster exec

Run a single command in a container of the named pod, through the platform

* no kubeconfig and no port-forward - and exit with the command's own exit
  code, so a script or CI job can branch on it.

Everything after -- is the command and its arguments, passed to the
container exactly as given: no shell re-parses it, so quote once for your
local shell and not again. To use shell features (pipes, globs, variables)
run a shell explicitly: -- sh -c 'echo "\$HOSTNAME" | tr a-z A-Z'.

stdout and stderr stream to your stdout and stderr as the command runs. The
command gets no TTY and, unless `--stdin` is given, no input; with `--stdin` your
input is forwarded and the command sees end-of-file when it ends.

Like "ankra cluster terminal", every run is recorded by the platform and
linked from the cluster's audit log as an open\_pod\_terminal event carrying
the command; "ankra org terminal-session" replays it. Needs kubernetes.exec
on the cluster, and a cluster agent recent enough to run one-off commands.

Exit codes: the command's own exit code when it ran; otherwise the CLI's
usual codes (6 for a refused credential, 7 for a missing kubernetes.exec,
1 when the command could not be started).

With -o json nothing is streamed; one document is printed when the command
ends: \{"exit\_code", "stdout", "stderr", "stdout\_truncated",
"stderr\_truncated"}, each stream capped at 8 MiB.

```bash theme={null}
ankra cluster exec <pod> -- <command> [args...] [flags]
```

**Examples**

```bash theme={null}
ankra cluster exec cnpg-cluster-1 -n cnpg-database -c postgres -- psql -U postgres -d appdb -Atc 'select count(*) from users'
ankra cluster exec api-6d8f9c7b5-x2kq9 -n payments -- cat /etc/app/config.yaml
ankra cluster exec api-6d8f9c7b5-x2kq9 -n payments -o json -- curl -sf localhost:8080/healthz
ankra cluster exec cnpg-cluster-1 -n cnpg-database -c postgres --stdin -- psql -U postgres -d appdb < query.sql
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-c`, `--container` | | Container to run the command in (default: the pod's only container) |
| `-n`, `--namespace` | | Namespace of the pod (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stdin` | `false` | Forward your stdin to the command; it sees end-of-file when your input ends |

## ankra cluster get

Get Kubernetes resources from the active cluster.

Examples:

```bash theme={null}
ankra cluster get pods
ankra cluster get deployments -n kube-system
ankra cluster get nodes
ankra cluster get services --all-namespaces
```

## ankra cluster get configmaps

List configmaps in the cluster

```bash theme={null}
ankra cluster get configmaps [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get cronjobs

List cronjobs in the cluster

```bash theme={null}
ankra cluster get cronjobs [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get daemonsets

List daemonsets in the cluster

```bash theme={null}
ankra cluster get daemonsets [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get deployments

List deployments in the cluster

```bash theme={null}
ankra cluster get deployments [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get events

List events in the cluster

```bash theme={null}
ankra cluster get events [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--for` | | Scope to one object's events, as kind/name (e.g. pod/web-7d9f-2xkvp) |
| `--name` | | Filter by the Event resource's own name; to scope by the object an event is about, use `--for` |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |
| `--type` | | Filter by event type: Normal or Warning |

## ankra cluster get ingresses

List ingresses in the cluster

```bash theme={null}
ankra cluster get ingresses [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get k8s-jobs

List Kubernetes jobs in the cluster

```bash theme={null}
ankra cluster get k8s-jobs [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get namespaces

List namespaces in the cluster

```bash theme={null}
ankra cluster get namespaces [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Filter by resource name |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get nodes

List nodes in the cluster

```bash theme={null}
ankra cluster get nodes [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Filter by resource name |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get pods

List pods or get a specific pod's manifest

```bash theme={null}
ankra cluster get pods [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by pod name (contains) |
| `-n`, `--namespace` | | Kubernetes namespace |
| `--node` | | Filter by node name |
| `-o`, `--output` | `table` | Output format: table, json, yaml |

## ankra cluster get resources

Fetch any Kubernetes resource type. Use for kinds not covered by dedicated commands.

Kinds outside the core API group need `--group` (and sometimes `--api-version`).

Example:

```bash theme={null}
ankra cluster resources PersistentVolumeClaim -n default
ankra cluster resources NetworkPolicy --group networking.k8s.io --all-namespaces
ankra cluster resources StorageClass --group storage.k8s.io
```

```bash theme={null}
ankra cluster get resources <kind> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--api-version` | `v1` | API version (e.g. v1, v1beta1) |
| `--group` | | API group (e.g. apps, networking.k8s.io) |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get secrets

List Secrets, or read one Secret by name.

The platform returns every Secret value as a sha256 digest (sha256: followed
by 12 hex characters) unless you ask for the values. Keys, type and metadata
are readable; the values are not. A digest still changes when its value does.

`--reveal` prints the plaintext values of ONE named Secret. It needs the
Secret's namespace (-n), it is refused on a listing (no name, -A or -l), and
it needs the kubernetes.secrets\_reveal permission on the cluster, which the
operator, admin and owner roles carry. The platform records every reveal in
the organisation's audit log. Values under data stay base64-encoded, as with
kubectl.

Exit codes with `--reveal`: 7 when your role lacks kubernetes.secrets\_reveal,
3 when the Secret does not exist, 1 when the platform could not hand out live
values (for example the cluster is unreachable), 2 for a reveal on a listing.

Examples:

```bash theme={null}
ankra cluster get secrets -n default
ankra cluster get secrets db-credentials -n default
ankra cluster get secrets db-credentials -n default --reveal
```

```bash theme={null}
ankra cluster get secrets [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `--reveal` | `false` | Print the plaintext values of the one named Secret instead of sha256 digests (needs -n and the kubernetes.secrets\_reveal permission; every reveal is audited) |
| `-l`, `--selector` | | Label selector |

## ankra cluster get services

List services in the cluster

```bash theme={null}
ankra cluster get services [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get statefulsets

List statefulsets in the cluster

```bash theme={null}
ankra cluster get statefulsets [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces |
| `--name` | | Filter by resource name |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster get storageclasses

List storage classes in the cluster

```bash theme={null}
ankra cluster get storageclasses [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Filter by resource name |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-l`, `--selector` | | Label selector |

## ankra cluster gitops

Commands for inspecting which GitOps repository a cluster syncs from, and for
listing and resolving the merge conflicts that pause its sync.

## ankra cluster gitops conflicts

A GitOps merge conflict is a resource that changed both in the cluster's GitOps
repository and on the platform (in the portal, the CLI or the API) since the two
last agreed. Ankra does not pick a side on its own: while any conflict is
undecided, GitOps sync applies nothing from Git, including commits pushed since.

'list' shows the open conflicts. 'resolve' records which side to keep, for one
conflict or for all of them, and the next sync applies it:

```text theme={null}
--keep git      keep the repository's version; the platform's version is
                overwritten and the cluster is updated to match Git.
--keep cluster  keep the platform's version; it is pushed back to the
                repository, over the change made there.
```

## ankra cluster gitops conflicts list

List the cluster's open GitOps merge conflicts: the resource key of each, how
Git and the cluster each changed it (added, modified or removed), when it was
detected, and whether a resolution is already recorded and waiting for the next
sync to apply it.

If no cluster name is provided, uses the `--cluster` flag or the currently
selected cluster. -o json|yaml prints the platform's answer as it is.

```bash theme={null}
ankra cluster gitops conflicts list [cluster_name] [flags]
```

**Examples**

```bash theme={null}
ankra cluster gitops conflicts list
ankra cluster gitops conflicts list prod
ankra cluster gitops conflicts list prod -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster gitops conflicts resolve

Record which side of a GitOps merge conflict to keep, for one conflict (by its
resource key, as 'ankra cluster gitops conflicts list' prints it) or for every
open conflict with `--all`. The next sync applies the choice and clears the
conflict; resolve triggers that sync.

`--keep` is required, because either side discards the other:

```text theme={null}
--keep git      keep the repository's version. The platform's version of the
                resource is overwritten and the cluster is updated to match Git.
--keep cluster  keep the platform's version. It is pushed back to the
                repository, over the change made there.
```

resolve lists what it is about to resolve and what each choice discards, then
asks for confirmation. `--yes` skips the question; without a terminal to ask on
(a script, CI) it is required. With `--all`, every conflict open when the platform
receives the request is resolved the same way, including one detected after the
list was shown.

Resolving needs permission to change the cluster's configuration
(clusters.write). The cluster is the `--cluster` flag or the currently selected
cluster.

```bash theme={null}
ankra cluster gitops conflicts resolve [resource_key] [flags]
```

**Examples**

```bash theme={null}
ankra cluster gitops conflicts resolve stack:web/addon:nginx --keep git
ankra cluster gitops conflicts resolve --all --keep cluster --cluster prod
ankra cluster gitops conflicts resolve --all --keep git --yes -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Resolve every open conflict on the cluster |
| `--keep` | | Which side to keep: 'git' (the repository's version) or 'cluster' (the platform's version, pushed to the repository) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt (required when stdin is not a terminal) |

## ankra cluster gitops status

Show the GitOps sync status of a cluster: the repository, branch, and
credential it syncs from, the last synced commit, the commit the cluster is
in step with and Git's head as last checked, any pending commit or sync
error, any open merge conflicts pausing the sync, and the files Git and the
platform are divided on (preserved paths), with when each was detected and
whether it is decided.

If no cluster name is provided, uses the currently selected cluster.

```bash theme={null}
ankra cluster gitops status [cluster_name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster helm

Commands to list, inspect, roll back, upgrade and uninstall Helm releases running in the cluster.

## ankra cluster helm get

Show one Helm release - the chart and revision it is on, when it was
deployed, the values it was installed with and the chart's notes.

'-o values' prints only the values the release was installed with, as YAML:
edit that file and hand it back to 'cluster helm upgrade `--values`'.

Passwords, tokens and keys in a release's values, the Secrets it renders and
its notes are shown as \[REDACTED:...] placeholders. '`--reveal`' asks for them in
plaintext: that needs the kubernetes.secrets\_reveal permission on the cluster,
and each reveal is written to the audit log. An upgrade whose values file still
holds a placeholder is refused, so reveal before you edit a release that has
credentials.

Examples:

```bash theme={null}
ankra cluster helm get traefik -n traefik
ankra cluster helm get traefik -n traefik -o values > traefik-values.yaml
ankra cluster helm get postgres -n data -o values --reveal > postgres-values.yaml
```

```bash theme={null}
ankra cluster helm get <release_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `-o`, `--output` | `table` | Output format: table, json, yaml, values |
| `--reveal` | `false` | Show credential values in plaintext (needs kubernetes.secrets\_reveal; audited) |

## ankra cluster helm history

List a Helm release's revisions, newest first, with the chart and status of
each - the revision numbers 'cluster helm rollback `--revision`' takes.

Example:

```bash theme={null}
ankra cluster helm history traefik -n traefik
```

```bash theme={null}
ankra cluster helm history <release_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `25` | Number of revisions to show (1-200) |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `-o`, `--output` | `table` | Output format: table, json |

## ankra cluster helm releases

List Helm releases in the cluster

```bash theme={null}
ankra cluster helm releases [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | List across all namespaces (default) |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json |

## ankra cluster helm rollback

Roll a Helm release back to one of its earlier revisions, as listed by
'cluster helm history'. The rollback runs on the cluster's Ankra agent and,
by default, waits for the rolled-back resources to become ready before
returning. A release that an Ankra addon manages is refused: change the
addon's values in the stack instead, so Git stays the source of truth.

Examples:

```bash theme={null}
ankra cluster helm rollback traefik -n traefik --revision 3
ankra cluster helm rollback traefik -n traefik --revision 3 --wait=false --yes
```

```bash theme={null}
ankra cluster helm rollback <release_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `--revision` | `0` | Revision to roll back to (required, see 'cluster helm history') |
| `--timeout` | `600` | Seconds to wait for the rollback (1-3600) |
| `--wait` | `true` | Wait for the rolled-back resources to become ready |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster helm uninstall

Uninstall a Helm release from the cluster

```bash theme={null}
ankra cluster helm uninstall <release_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster helm upgrade

Upgrade a Helm release in place: the agent runs 'helm upgrade' with the
chart reference and the values file you pass. The values file REPLACES the
release's values wholesale - start from 'cluster helm get \<release> -o values'
so nothing you did not mean to change resets to a chart default. Without
`--version` the release stays on the chart version it already runs.

A release that an Ankra addon manages is refused: change the addon in the
stack instead, so Git stays the source of truth.

Examples:

```bash theme={null}
ankra cluster helm get traefik -n traefik -o values > traefik-values.yaml
ankra cluster helm upgrade traefik -n traefik --chart traefik/traefik --values traefik-values.yaml
ankra cluster helm upgrade traefik -n traefik --chart traefik --repo https://traefik.github.io/charts --version 30.0.0 --values traefik-values.yaml
```

```bash theme={null}
ankra cluster helm upgrade <release_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--chart` | | Chart reference (required): repo/name, an OCI reference, or a name with `--repo` |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `--repo` | | Chart repository URL when `--chart` is a bare chart name |
| `--timeout` | `600` | Seconds to wait for the upgrade (1-3600) |
| `-f`, `--values` | | Values file that replaces the release's values (required) |
| `--version` | | Chart version to upgrade to (default: the version the release already runs) |
| `--wait` | `true` | Wait for the upgraded resources to become ready |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster hetzner

Commands to create, deprovision, and scale Hetzner clusters.

## ankra cluster hetzner bastion

Inspect, diagnose, and resize the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster hetzner bastion allowed-ips

Replace the bastion/gateway's SSH source allowlist. Only the listed IPv4
addresses or CIDRs, the platform's own egress addresses and private network
sources can then reach port 22; every other source is dropped. The platform's
egress is always added by the platform itself, so it can never be locked out.

The list you give is the complete new list: entries may be separated by
spaces or commas. `--clear` removes the allowlist and makes the bastion
reachable from anywhere again (key-only SSH, rate-limited). IPv6 entries and
0.0.0.0/0 are refused; at most 64 entries.

The platform applies the list through the bastion update operation reported
on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

Examples:

```bash theme={null}
ankra cluster hetzner bastion allowed-ips my-cluster 203.0.113.7 198.51.100.0/24
ankra cluster ovh bastion allowed-ips my-cluster --clear
```

```bash theme={null}
ankra cluster hetzner bastion allowed-ips <cluster_id|name> [ip-or-cidr ...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove the allowlist: SSH from anywhere again |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster hetzner bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster hetzner bastion resize

Resize the bastion/gateway node. The provider's bastion/gateway update job
powers it off, resizes it, and powers it back on, causing brief SSH/NAT
downtime for the cluster.

`--wait` covers the platform write only; the cloud resize runs as the operation
reported on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

```bash theme={null}
ankra cluster hetzner bastion resize <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster hetzner bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster hetzner bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster hetzner control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster hetzner control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster hetzner control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner control-plane set-instance-type

Change the instance type of every controller in a Hetzner cluster.

The instance type is stored as given; it is not checked against Hetzner's catalog.
A name that does not exist is rejected by Hetzner itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster hetzner server-types
```

```bash theme={null}
ankra cluster hetzner control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner create

Create a new Hetzner cluster

```bash theme={null}
ankra cluster hetzner create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-allowed-ips` | `[]` | IPv4 addresses or CIDRs allowed to reach the bastion over SSH, comma-separated (the platform's own egress is always allowed too; IPv6 and 0.0.0.0/0 are refused). Omit to keep the bastion reachable from anywhere (key-only SSH, rate-limited). Change it later with 'bastion allowed-ips'. |
| `--bastion-server-type` | | Bastion server type (server default: the cheapest x86 type the location can provision with at least 2 vCPU and 4 GB; see 'ankra cluster hetzner server-types') |
| `--control-plane-count` | `1` | Number of control plane nodes |
| `--control-plane-server-type` | | Control plane server type (server default: the cheapest x86 type the location can provision with at least 4 vCPU and 8 GB) |
| `--credential-id` | | Hetzner API credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm (default, vanilla upstream Kubernetes with Cilium) or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `3` | Number of dedicated etcd nodes when `--etcd-topology=external` (3 or 5) |
| `--etcd-server-type` | | Server type for dedicated etcd nodes when `--etcd-topology=external` (server default: the cheapest x86 type the location can provision with at least 4 vCPU and 8 GB) |
| `--etcd-topology` | `stacked` | etcd topology for kubeadm clusters: stacked (on control planes) or external (dedicated VMs) |
| `--external-cloud-provider` | `true` | Install the Hetzner CCM and CSI (cloud-provider=external) for LoadBalancers and persistent volumes (default on; pass `--external-cloud-provider=false` to skip, which also disables `--include-networking`) |
| `--gitops-branch` | `master` | GitOps branch to commit to |
| `--gitops-credential-name` | | GitOps GitHub credential name; when set with `--gitops-repository`, the generated hcloud stack is committed to Git (optional) |
| `--gitops-repository` | | GitOps repository (e.g. org/repo) to commit the generated stack to (optional) |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Install Traefik + cert-manager for ingress (default on; pass `--include-networking=false` to skip). Requires `--external-cloud-provider` (the ingress LoadBalancer is provisioned by the cloud controller manager) |
| `--kubernetes-version` | | Kubernetes version for the chosen `--distribution` (optional): a plain tag such as v1.36.4 for kubeadm (see `ankra cluster kubeadm-versions`), a k3s build such as v1.35.7+k3s1 for k3s (see `ankra cluster k3s-versions`) |
| `--location` | | Hetzner location (required) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | `10.0.0.0/16` | Network IP range |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ssh-key-credential-id` | | SSH key credential ID (single key, use `--ssh-key-credential-ids` for multiple) |
| `--ssh-key-credential-ids` | `[]` | SSH key credential IDs (comma-separated or repeated) |
| `--subnet-range` | `10.0.1.0/24` | Subnet range |
| `--worker-count` | `1` | Number of worker nodes |
| `--worker-server-type` | | Worker server type (server default: the cheapest x86 type the location can provision with at least 2 vCPU and 4 GB) |

## ankra cluster hetzner k8s-version

Get current Kubernetes version for a Hetzner cluster

```bash theme={null}
ankra cluster hetzner k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner locations

List the Hetzner Cloud locations the supplied credential can deploy in. Only these locations are valid for cluster creation.

```bash theme={null}
ankra cluster hetzner locations [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Hetzner API credential ID (required) |

## ankra cluster hetzner node-group

List, add, scale, upgrade, and delete node groups.

## ankra cluster hetzner nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster hetzner nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster hetzner nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster hetzner nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster hetzner nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster hetzner nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster hetzner nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster hetzner nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster hetzner server-types

List Hetzner Cloud server types. Pass `--location` to see which types are currently available for provisioning there, and `--available-only` to hide the rest.

```bash theme={null}
ankra cluster hetzner server-types [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--available-only` | `false` | Only show server types available for provisioning (use with `--location`) |
| `--credential-id` | | Hetzner API credential ID (required) |
| `--location` | | Filter availability by location |

## ankra cluster hetzner start

Start (re-provision) a stopped Hetzner cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster hetzner start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster hetzner stop

Stop a Hetzner cluster's compute while keeping its configuration so it can be started again later.

```bash theme={null}
ankra cluster hetzner stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and also delete the cluster's load balancers. The cluster's CSI volumes are kept and keep billing while stopped: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster hetzner workers

Get current worker count for a Hetzner cluster

```bash theme={null}
ankra cluster hetzner workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster info

Show details of a specific cluster, named by its name or its id.

If no cluster is given, shows details for the currently selected cluster.

```bash theme={null}
ankra cluster info [name|id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster k3s-versions

List the k3s versions the platform can provision or upgrade to. Use one of these values with `ankra cluster upgrade <cluster_id> <target_version>` (the provider is detected automatically).

```bash theme={null}
ankra cluster k3s-versions
```

## ankra cluster kube-token

Print a short-lived Kubernetes ExecCredential so kubectl can authenticate to the
Ankra cluster gateway.

This command is intended to be invoked by kubectl as a client-go credential plugin,
for example in a kubeconfig:

```yaml theme={null}
users:
- name: ankra
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: ankra
      args: ["cluster", "kube-token", "--cluster", "<cluster-name-or-id>", "--org", "<organisation-id>"]
```

Pinning `--org` to the cluster's organisation ID keeps the entry working when
your selected organisation differs from the cluster's ('ankra cluster
kubeconfig add' writes it automatically). An entry written without `--org` still
works: a cluster ID the selected organisation does not have is looked up
across the organisations you belong to, and the token is minted against the
one that owns it. Your selected organisation is not changed.

It authenticates like every ankra command: a `--token` flag, else the saved
'ankra login' in \~/.ankra.yaml (or `--config`), else ANKRA\_API\_TOKEN from the
environment kubectl runs it in. See 'ankra cluster kubeconfig add `--help`' for
what that means for automation.

kubectl runs this on every command, so the token is cached on disk (readable
only by you) and reused while it has more than two minutes left and was minted
less than five minutes ago; logging in again starts over.
ANKRA\_KUBE\_TOKEN\_CACHE=off mints a fresh token every time.

It prints JSON to stdout and never prompts; run 'ankra login' first.

```bash theme={null}
ankra cluster kube-token [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or ID (defaults to the selected cluster) |

## ankra cluster kubeadm-versions

List the upstream Kubernetes versions the platform can provision or upgrade kubeadm-distribution clusters to. Use one of these values with `--kubernetes-version` on `ankra cluster <provider> create --distribution kubeadm`, or with `ankra cluster upgrade <cluster_id> <target_version>`.

```bash theme={null}
ankra cluster kubeadm-versions
```

## ankra cluster kubeconfig

Add, remove, and list the Ankra cluster contexts in your kubeconfig.

By default 'add' writes an exec-based context that fetches a short-lived token
on demand via 'ankra cluster kube-token', so credentials stay ephemeral and
SSO-backed (run 'ankra login' once). Other clusters/users/contexts already in
your kubeconfig are left untouched.

These commands read and write a single file: `--kubeconfig` if given, otherwise
the first entry of \$KUBECONFIG, otherwise \~/.kube/config.

Examples:

```bash theme={null}
ankra cluster kubeconfig add my-cluster --use
ankra cluster kubeconfig add --all
ankra cluster kubeconfig add my-cluster --print > my-cluster.yaml
ankra cluster kubeconfig list
ankra cluster kubeconfig remove my-cluster
ankra cluster kubeconfig remove --all
```

## ankra cluster kubeconfig add

Add or update an Ankra context in your kubeconfig.

The context's user is an exec credential plugin: on every kubectl command,
kubectl runs 'ankra cluster kube-token `--cluster` \<id> `--org` \<organisation>'
(the executable is `--exec-command`) and uses the short-lived gateway token it
prints. Pass `--embed-token` to write that token into the file instead; it
stops working when it expires.

Whose access kubectl gets is decided when kubectl runs the plugin, not when
the context is added: kube-token authenticates like every ankra command,
with the saved 'ankra login' in \~/.ankra.yaml first, and ANKRA\_API\_TOKEN from
kubectl's environment only when there is no saved login. On a machine where
a person ran 'ankra login', kubectl therefore acts as that person even when
ANKRA\_API\_TOKEN holds a service account's token (kube-token prints a note
on stderr when it ignores ANKRA\_API\_TOKEN this way).

Automation that should act as a service account must run kubectl where
nothing is logged in (no \~/.ankra.yaml for that user, or HOME pointing at a
clean directory) and export the service token as ANKRA\_API\_TOKEN in the
environment kubectl runs in. Without a grant, a service account gives
itself time-boxed access with 'ankra cluster access elevate'.

```bash theme={null}
ankra cluster kubeconfig add [cluster] [flags]
```

**Examples**

```bash theme={null}
ankra cluster kubeconfig add my-cluster --use
ankra cluster kubeconfig add --all
ankra cluster kubeconfig add my-cluster --print > my-cluster.yaml

# CI, acting as a service account:
export ANKRA_API_TOKEN="$SERVICE_TOKEN"
ankra cluster kubeconfig add my-cluster --use
kubectl get pods
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Add every cluster you can access |
| `--cluster` | | Cluster name or ID (same as the positional argument; defaults to the selected cluster) |
| `--embed-token` | `false` | Embed a short-lived token instead of the exec credential plugin |
| `--exec-command` | `ankra` | Executable kubectl invokes for credentials in exec mode (use an absolute path if 'ankra' is not on PATH) |
| `--insecure-skip-tls-verify` | `false` | Skip TLS verification for the cluster server (dev only) |
| `--kubeconfig` | | Path to the kubeconfig file (default: \$KUBECONFIG or \~/.kube/config) |
| `--namespace` | | Default namespace for the context |
| `--print` | `false` | Print a standalone kubeconfig to stdout instead of writing the file |
| `--use` | `false` | Set the added context as the active current-context |

## ankra cluster kubeconfig list

List Ankra-managed contexts in your kubeconfig

```bash theme={null}
ankra cluster kubeconfig list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--kubeconfig` | | Path to the kubeconfig file (default: \$KUBECONFIG or \~/.kube/config) |

## ankra cluster kubeconfig remove

Remove Ankra contexts from your kubeconfig

```bash theme={null}
ankra cluster kubeconfig remove [cluster] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Remove all Ankra-managed contexts |
| `--cluster` | | Cluster name or ID (same as the positional argument) |
| `--kubeconfig` | | Path to the kubeconfig file (default: \$KUBECONFIG or \~/.kube/config) |

## ankra cluster list

List all clusters

```bash theme={null}
ankra cluster list [flags]
```

**Examples**

```bash theme={null}
# newest clusters first
ankra cluster list --sort created --order desc

# alphabetical by name
ankra cluster list --sort name
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `asc` | Sort direction with `--sort`: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--sort` | | Sort by column: name, environment, kube-version, nodes, control-planes, state, kind, created (default: server order) |

## ankra cluster logs

Stream log output from the active cluster.

By default the stream stays open and prints new lines as they arrive, like
kubectl logs -f. Pass `--follow=false` to print the current backlog and exit,
which is what a pipeline into grep or a script wants.

`--previous` reads the log of the container instance that terminated. For a
pod in CrashLoopBackOff that is the only log with the failure in it, and it
is the case where reaching for kubectl through a broad access grant used to
be the only option. A previous log is closed, so `--previous` always makes a
bounded read.

-l/`--selector` reads every pod matching a label selector instead of one pod
name, and `--all-containers` expands each pod to all of its containers (init
and ephemeral containers included). With more than one target each line is
prefixed with \[pod] or \[pod/container] so the interleaved output stays
attributable.

Examples:

```bash theme={null}
ankra cluster logs my-pod -n default -c my-container --tail 100
ankra cluster logs my-pod -n default --previous
ankra cluster logs -l app=web -n default --tail 50 --follow=false
ankra cluster logs my-pod -n default --all-containers --previous
ankra cluster logs -l app=web -n default --follow=false -o json
```

```bash theme={null}
ankra cluster logs [pod_name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-containers` | `false` | Read every container of each selected pod, including init and ephemeral containers |
| `-c`, `--container` | | Container name (defaults to pod name) |
| `-f`, `--follow` | `true` | Keep the stream open for new lines; `--follow=false` prints the current backlog and exits |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `-p`, `--previous` | `false` | Read the terminated container's log (the one a CrashLoopBackOff wrote); always a bounded read |
| `-l`, `--selector` | | Read every pod matching this label selector instead of one pod name |
| `--since` | `0` | Seconds of logs to retrieve |
| `--tail` | `0` | Number of lines from the end of the logs |

## ankra cluster logs-ship

Ankra can keep a cluster's container logs in its hosted log store, so they can
be read from Ankra with no logging stack of your own to run or connect.

Shipping is opt-in per cluster and off by default: no log content leaves the
cluster until a member with permission to change cluster settings
(clusters.write) turns it on, here or in the cluster's settings in the portal.
While it is on, the cluster's agent sends the log lines of every running
container to Ankra's hosted log store, where they are kept for 7 days and can
be read by the members of your organisation. 'disable' stops it at any time.

The agent picks the switch up at its next check-in. An agent too old to follow
it does not, and 'status' says so.

**Examples**

```bash theme={null}
ankra cluster logs-ship status
ankra cluster logs-ship enable --cluster prod
ankra cluster logs-ship enable --cluster prod --yes
ankra cluster logs-ship disable --cluster prod
```

## ankra cluster logs-ship disable

Turn hosted log shipping off for the cluster. The agent stops sending log lines
at its next check-in. Nothing is sent by turning it off, so this does not ask
for confirmation.

```bash theme={null}
ankra cluster logs-ship disable [flags]
```

**Examples**

```bash theme={null}
ankra cluster logs-ship disable
ankra cluster logs-ship disable --cluster prod -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster logs-ship enable

Turn hosted log shipping on for the cluster. The log lines of every running
container in the cluster are sent to Ankra's hosted log store, where they are
kept for 7 days and can be read by the members of your organisation. Turn it
off any time with 'ankra cluster logs-ship disable'.

Because log content leaves the cluster, enable says what is sent and asks for
confirmation first. `--yes` skips the question; without a terminal to ask on
(a script, CI) it is required.

If Ankra has not turned hosted logging on for the platform yet, the switch is
stored and nothing ships until it does.

```bash theme={null}
ankra cluster logs-ship enable [flags]
```

**Examples**

```bash theme={null}
ankra cluster logs-ship enable
ankra cluster logs-ship enable --cluster prod --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt (required when stdin is not a terminal) |

## ankra cluster logs-ship status

Show whether the cluster ships its logs to Ankra's hosted log store, whether
hosted logging is available on this platform yet, whether the cluster's agent
is new enough to follow the switch, and when the switch was last changed.

-o json prints the platform's answer as it is.

```bash theme={null}
ankra cluster logs-ship status [flags]
```

**Examples**

```bash theme={null}
ankra cluster logs-ship status
ankra cluster logs-ship status --cluster prod -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster managed

Create, delete, stop and start, scale node pools, and upgrade cloud-managed Kubernetes clusters on DOKS, UpCloud UKS, GKE, OVH MKS, AKS, EKS, Scaleway Kapsule, and Ankra Cloud Kubernetes.

## ankra cluster managed create

Create a managed Kubernetes cluster

```bash theme={null}
ankra cluster managed create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--autoscaling` | `false` | Enable autoscaling for the initial node pool |
| `--autoscaling-max` | `0` | Maximum node count while autoscaling (requires `--autoscaling`) |
| `--autoscaling-min` | `0` | Minimum node count while autoscaling (requires `--autoscaling`) |
| `--control-plane` | | Control plane tier for an Ankra Cloud managed cluster: development (one replica, no control plane fee, you pay for the nodes only, not for production) or production (three replicas, the default) |
| `--credential-id` | | Cloud credential ID (optional with `--provider` ankracloud\_k8s: Ankra uses the organisation's built-in Ankra Cloud credential) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--dev-cluster` | `false` | Ankra Cloud Kubernetes: create a dev cluster, one server that is control plane, node, load balancer and gateway, sized by `--node-pool-size` (development only, no control-plane fee) |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--gitops-branch` | `master` | GitOps branch (optional) |
| `--gitops-credential-name` | | GitOps credential name (optional) |
| `--gitops-repository` | | GitOps repository URL (optional) |
| `--kubernetes-version` | | Kubernetes version (optional) |
| `--location` | | Region or zone for the cluster |
| `--maintenance-window` | | AKS: planned maintenance window as \<Weekday>:\<start-hour>:\<hours> in UTC, e.g. Saturday:22:4 |
| `--name` | | Cluster name |
| `--network-cidr` | | Ankra Cloud Kubernetes: CIDR of the network Ankra creates (server default 10.100.0.0/24) |
| `--network-plugin` | | AKS: network plugin, azure (default) or kubenet |
| `--node-pool-count` | `2` | Initial node pool node count |
| `--node-pool-name` | `workers` | Initial node pool name |
| `--node-pool-size` | | Initial node pool size/plan |
| `--os-disk-size-gb` | `0` | AKS: OS disk size in GB for the initial pool (at least 30) |
| `--os-disk-type` | | AKS: OS disk type for the initial pool, Managed or Ephemeral |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--private-cluster` | `false` | AKS: private API server endpoint |
| `--private-network-id` | | Private network ID: required with `--provider` kapsule; optional with `--provider` ankracloud\_k8s (default: Ankra creates ankra-\<name>) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |
| `--public-ipv4` | `true` | Ankra Cloud Kubernetes: give the API endpoint a public IPv4 address |
| `--resource-group` | | AKS: existing resource group to adopt (default: Ankra creates and owns ankra-\<name>) |
| `--sku-tier` | | AKS: control-plane tier, Free (default), Standard (uptime SLA) or Premium |
| `--vnet-subnet-id` | | AKS: ARM id of the subnet every node pool joins (default: AKS-managed VNet) |
| `--zone` | | AKS: availability zone(s) for the initial pool, comma-separated (e.g. 1,2,3) |

## ankra cluster managed delete

Delete a managed Kubernetes cluster

```bash theme={null}
ankra cluster managed delete <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force delete even when cluster is in a non-idle state |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |
| `-y`, `--yes` | `false` | Skip confirmation prompt |

## ankra cluster managed discover

List the managed Kubernetes clusters that already run in the provider account behind a credential, marking the ones already imported into Ankra.

```bash theme={null}
ankra cluster managed discover [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Cloud credential ID |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |

## ankra cluster managed import

Adopt a managed Kubernetes cluster that already runs at the provider: Ankra fetches the kubeconfig through the provider API and installs the agent automatically, so there is nothing to run against the cluster.

```bash theme={null}
ankra cluster managed import [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Cloud credential ID |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Description for the cluster in Ankra (optional) |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--name` | | Name for the cluster in Ankra (defaults to the provider-side name) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |
| `--provider-cluster-id` | | Provider-side cluster ID (from discover) |

## ankra cluster managed node-pool

Manage managed cluster node pools

## ankra cluster managed node-pool add

Add a node pool to a managed cluster

```bash theme={null}
ankra cluster managed node-pool add <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--autoscaling` | `false` | Enable autoscaling for the node pool |
| `--autoscaling-max` | `0` | Maximum node count while autoscaling (requires `--autoscaling`) |
| `--autoscaling-min` | `0` | Minimum node count while autoscaling (requires `--autoscaling`) |
| `--count` | `1` | Node count |
| `--name` | | Node pool name |
| `--os-disk-size-gb` | `0` | AKS: OS disk size in GB (at least 30) |
| `--os-disk-type` | | AKS: OS disk type, Managed or Ephemeral |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |
| `--size` | | Node pool size/plan |
| `--spot` | `false` | AKS: run the pool on spot capacity (never the cluster's first pool) |
| `--spot-max-price` | `0` | AKS: hourly spot price cap in USD (requires `--spot`; default: up to the on-demand price) |
| `--zone` | | AKS: availability zone(s), comma-separated (e.g. 1,2,3) |

## ankra cluster managed node-pool delete

Delete a managed cluster node pool

```bash theme={null}
ankra cluster managed node-pool delete <cluster_id|name> <node_pool_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |
| `-y`, `--yes` | `false` | Skip confirmation prompt |

## ankra cluster managed node-pool scale

Scale a managed cluster node pool

```bash theme={null}
ankra cluster managed node-pool scale <cluster_id|name> <node_pool_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--count` | `0` | Target node count |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |

## ankra cluster managed node-pool update

Update the node count or autoscaling settings of a managed cluster node
pool. Pass at least one of `--count`, `--autoscaling`, `--autoscaling-min`, or
`--autoscaling-max`; unspecified settings are left unchanged.

Pass `--externally-managed` on its own to hand the pool's node count to
something outside Ankra, such as a cluster autoscaler you run yourself. While
it is set, Ankra refuses to scale, update, replace or delete the pool;
`--externally-managed=false` hands it back.

```bash theme={null}
ankra cluster managed node-pool update <cluster_id|name> <node_pool_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--autoscaling` | `false` | Enable (true) or disable (false) autoscaling |
| `--autoscaling-max` | `0` | Maximum node count while autoscaling |
| `--autoscaling-min` | `0` | Minimum node count while autoscaling |
| `--count` | `0` | Target node count |
| `--externally-managed` | `false` | Hand the pool's node count to something outside Ankra (true) or take it back (false); pass on its own |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |

## ankra cluster managed start

Start a stopped managed Kubernetes cluster. Currently only AKS supports
stopping and starting managed clusters.

```bash theme={null}
ankra cluster managed start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |

## ankra cluster managed stop

Stop a managed Kubernetes cluster's compute while keeping its configuration
so it can be started again later. Currently only AKS supports stopping and
starting managed clusters.

```bash theme={null}
ankra cluster managed stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |

## ankra cluster managed upgrade

Upgrade a managed cluster Kubernetes version

```bash theme={null}
ankra cluster managed upgrade <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Managed Kubernetes provider (doks, uks, gke, ovh\_mks, aks, eks, kapsule, ankracloud\_k8s) |
| `--version` | | Target Kubernetes version |
| `-y`, `--yes` | `false` | Skip confirmation prompt |

## ankra cluster manifests

Commands to list, view, upgrade, and delete manifests.

## ankra cluster manifests create

Add a NEW manifest to an existing stack, without touching any other member.

Unlike 'ankra cluster apply', which is declarative over the WHOLE cluster and
prunes anything the file does not mention, this sends only the new manifest.
Every other stack, addon and manifest is left exactly as it is.

Examples:

```bash theme={null}
# Add a Secret to the langfuse stack, ordered after its namespace
ankra cluster manifests create langfuse-secrets --stack langfuse \
  --from-file ./secret.yaml --parent name=langfuse-namespace,kind=manifest \
  --cluster luminarylane

# Read the manifest from stdin
cat secret.yaml | ankra cluster manifests create langfuse-secrets \
  --stack langfuse --manifest - --cluster luminarylane

# See what would be sent without applying it
ankra cluster manifests create web --stack app --from-file ./web.yaml --dry-run
```

`--from-file` / `--manifest` - accept SOPS-encrypted content: when the file carries
a top-level sops: metadata mapping, the keys holding ENC\[...] ciphertext are
detected and recorded as encrypted\_paths automatically. Use `--encrypted-path` to
declare keys explicitly when auto-detection cannot see them.

To change a manifest that already exists, use 'ankra cluster manifests upgrade'.

```bash theme={null}
ankra cluster manifests create <manifest_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--dry-run` | `false` | Print the proposed before/after spec without applying changes |
| `--encrypted-path` | `[]` | Declare a YAML key name that is (or must stay) SOPS-encrypted; merged with auto-detected ENC\[...] keys (repeatable) |
| `--from-file` | | Path to the manifest YAML file |
| `--manifest` | | Use `-` to read the manifest YAML from stdin |
| `--namespace` | | Namespace for the manifest |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--parent` | `[]` | Dependency parent, e.g. `--parent` name=langfuse-namespace,kind=manifest (kind defaults to manifest; repeatable) |
| `--stack` | | Existing stack the manifest joins (required) |

## ankra cluster manifests delete

Disconnect a manifest from its stack. The manifest's resources are
removed from the cluster and dependent resources are reconnected to the
manifest's own parents.

The owning stack is discovered automatically (manifest names are unique per
cluster). Use `--dry-run` to preview the target without making changes.

```bash theme={null}
ankra cluster manifests delete <manifest_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--dry-run` | `false` | Print the manifest that would be disconnected without making changes |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster manifests get

Print the current YAML content of a manifest.

By default the decoded YAML is written to stdout, making it easy to pipe into
a file or edit and re-apply with `--from-file`:

```bash theme={null}
ankra cluster manifests get web > web.yaml
ankra cluster manifests get web -o raw   # base64-encoded form
```

```bash theme={null}
ankra cluster manifests get <manifest_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `-o`, `--output` | | Output format: yaml (decoded, default) or raw (base64) |

## ankra cluster manifests list

List manifests for the active cluster; or show details for a single manifest

```bash theme={null}
ankra cluster manifests list [manifest name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster manifests upgrade

Upgrade a manifest by patching just the fields you supply.

At least one mutating flag is required. Examples:

```bash theme={null}
# Patch a single path in-place, e.g. bump a Deployment image tag
ankra cluster manifests upgrade web \
  --set 'spec.template.spec.containers[name=app].image=nginx:1.27' \
  --cluster website-demo

# When the manifest holds multiple documents, select which one to edit
ankra cluster manifests upgrade web --target-kind Deployment --target-name web \
  --set 'spec.replicas=3' --cluster website-demo

# Replace the manifest content from a file
ankra cluster manifests upgrade demo-namespace \
  --from-file manifests/demo-namespace.yaml --cluster website-demo

# Read the manifest from stdin
cat manifest.yaml | ankra cluster manifests upgrade demo-namespace \
  --manifest - --cluster website-demo
```

`--set`/`--set-string`/`--set-file` MUTATE the existing manifest YAML and address
list items by a stable field (e.g. containers\[name=app]) as well as by numeric
index (containers\[0]). `--from-file` / `--manifest` - REPLACE the whole manifest
and are mutually exclusive with `--set*`.

`--from-file` / `--manifest` - accept SOPS-encrypted content: when the file
carries a top-level sops: metadata mapping, the keys holding ENC\[...]
ciphertext are detected and recorded as encrypted\_paths automatically (merged
with the manifest's existing encrypted\_paths). Use `--encrypted-path` to declare
keys explicitly when auto-detection cannot see them.

When no content or `--set` flag is supplied, the existing content is re-sent
unchanged (only namespace is updated). This is required because the backend's
manifest validation rejects empty manifest\_base64.

```bash theme={null}
ankra cluster manifests upgrade <manifest_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--add-parent` | `[]` | Add a dependency parent, e.g. `--add-parent` name=infisical-ns,kind=manifest (kind defaults to manifest; repeatable) |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--dry-run` | `false` | Print the proposed before/after spec without applying changes |
| `--encrypted-path` | `[]` | With `--from-file` / `--manifest` -: declare a YAML key name that is (or must stay) SOPS-encrypted; merged with auto-detected ENC\[...] keys and the manifest's existing encrypted\_paths (repeatable) |
| `--from-file` | | Path to manifest YAML file (REPLACES the entire manifest) |
| `--manifest` | | Use `-` to read manifest YAML from stdin (REPLACES the entire manifest) |
| `--namespace` | | Change the manifest's namespace |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--remove-parent` | `[]` | Remove a dependency parent, e.g. `--remove-parent` name=infisical-ns,kind=manifest (repeatable) |
| `--set` | `[]` | In-place edit of the manifest YAML, e.g. `--set 'spec.template.spec.containers[name=app].image=nginx:1.27'` (MUTATES existing content; repeatable, comma-separated) |
| `--set-file` | `[]` | Like `--set` but reads the value from a file: key=path or key=@path |
| `--set-parent` | `[]` | Replace ALL dependency parents with the given set (repeatable) |
| `--set-string` | `[]` | Like `--set` but always treats the value as a string |
| `--target-kind` | | With `--set`: select the document to edit by Kubernetes kind (e.g. Deployment) when the manifest holds multiple documents |
| `--target-name` | | With `--set`: select the document to edit by metadata.name when the manifest holds multiple documents |
| `--yes` | `false` | Skip confirmation prompts |

## ankra cluster mesh

Manage Cilium ClusterMeshes: sets of Ankra clusters whose pods and services resolve each other.

A cluster can join a mesh only if it was created on the platform's WireGuard overlay with a unique network identity, so `ankra cluster mesh readiness` is the place to start - it says which of your clusters can mesh, and why the others cannot.

## ankra cluster mesh create

Create an empty cluster mesh

```bash theme={null}
ankra cluster mesh create <name>
```

## ankra cluster mesh delete

Delete a cluster mesh. The mesh must be empty; remove its members first so their Cilium configuration is torn down rather than left pointing at a mesh that no longer exists.

```bash theme={null}
ankra cluster mesh delete <mesh_id>
```

## ankra cluster mesh join

Add a cluster to a mesh. The platform mints the mesh's shared certificate authority on the first join, hands it to the joining cluster, and re-renders every member's peer list.

A cluster that cannot mesh is refused with the reason; `ankra cluster mesh readiness` reports the same checks up front.

```bash theme={null}
ankra cluster mesh join <mesh_id> <cluster_id|name>
```

## ankra cluster mesh leave

Remove a cluster from a mesh

```bash theme={null}
ankra cluster mesh leave <mesh_id> <cluster_id|name>
```

## ankra cluster mesh list

List the organisation's cluster meshes

```bash theme={null}
ankra cluster mesh list
```

## ankra cluster mesh make-ready

Turn an existing cluster mesh-capable, day-2: allocate its Cilium identity and overlay range, stamp the overlay onto its stored definitions, and set its resources converging so every node joins the platform WireGuard overlay. The node-IP switch restarts kubelets once; nothing is deleted or recreated.

Two clusters prepared from the kubeadm default share one pod range and cannot mesh with each other. Moving a running cluster onto another pod range is disabled while it is redesigned - the platform refuses it, because a kube-controller-manager whose `--cluster-cidr` excludes a node's range exits at start - so such a pair cannot mesh for now. `--pod-cidr` still accepts the kubeadm default 10.244.0.0/16, which puts a cluster an earlier move split back onto the range its nodes run. UpCloud clusters only.

Proxmox clusters need `--site-public-ip`: the address other sites dial this cluster's site gateway on.

```bash theme={null}
ankra cluster mesh make-ready <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--pod-cidr` | | Record a pod range: the platform accepts only the kubeadm default 10.244.0.0/16 for now, to put back a cluster an earlier pod-range move split (upcloud only; moving a running cluster onto another range is disabled while it is redesigned) |
| `--site-public-ip` | | Public address other sites dial this cluster's site gateway on (proxmox clusters only) |

## ankra cluster mesh readiness

Check whether the given clusters could form one mesh. Each cluster is reported ready or not, with the failing checks spelled out.

A missing Cilium identity and a node network no other cluster can reach are fixed in place by `ankra cluster mesh make-ready`; a pod range that overlaps another member's is not, while moving a running cluster onto a fresh range is disabled. The cloud, the distribution and the container network are settled when the cluster is created, so a cluster failing those has to be rebuilt to mesh. `ankra cluster mesh up` runs the whole path for a set of clusters.

```bash theme={null}
ankra cluster mesh readiness <cluster_id|name> [cluster_id|name...]
```

## ankra cluster mesh show

Show one cluster mesh and its members

```bash theme={null}
ankra cluster mesh show <mesh_id>
```

## ankra cluster mesh up

Bring a set of clusters into one mesh from wherever they are: read their readiness, run make-ready on every cluster that only lacks its network identity or the overlay, join every cluster that is ready, and keep going until each member reports ready or `--wait` runs out. The mesh is created when no mesh of that name exists.

Two clusters prepared from the kubeadm default share one pod range and cannot mesh with each other, and moving one onto a fresh range is disabled while it is redesigned, so `up` reports such a cluster blocked with the platform's reason. `--renumber-pods` has no effect until that move returns.

`--plan` prints what a pass would do and changes nothing. Re-running is safe: members are skipped and a make-ready re-arms a cluster whose nodes did not converge.

```bash theme={null}
ankra cluster mesh up <mesh_name|mesh_id> <cluster_id|name> [cluster_id|name...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--interval` | `30s` | Pause between passes |
| `--plan` | `false` | Print what one pass would do and change nothing |
| `--renumber-pods` | `false` | Ask `up` to move every colliding cluster after the first onto a fresh pod range (the platform refuses that move while it is redesigned, so the flag has no effect for now) |
| `--wait` | `45m0s` | How long to keep passing over the clusters and waiting for members to report ready (0 runs one pass) |

## ankra cluster metrics

Query the Prometheus metrics source configured for a cluster.

The query is proxied through the Ankra agent to the in-cluster Prometheus
endpoint configured in Cluster Settings > Metrics.

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name (defaults to the selected cluster) |

## ankra cluster metrics query

Run an instant PromQL query against the cluster's Prometheus source.

Examples:

```bash theme={null}
ankra cluster metrics query 'up'
ankra cluster metrics query 'sum(rate(container_cpu_usage_seconds_total[5m])) by (pod)'
```

```bash theme={null}
ankra cluster metrics query [promql] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `--timeout` | `0` | Query timeout in seconds (default server-side) |

## ankra cluster metrics query-range

Run a range PromQL query against the cluster's Prometheus source.

Provide either `--range` (a duration relative to now) or both `--start` and `--end`
(Unix seconds). When `--step` is omitted a sensible step is chosen automatically.

Examples:

```bash theme={null}
ankra cluster metrics query-range 'up' --range 1h
ankra cluster metrics query-range 'rate(node_cpu_seconds_total[5m])' --range 6h --step 5m
ankra cluster metrics query-range 'up' --start 1717000000 --end 1717003600 --step 1m
```

```bash theme={null}
ankra cluster metrics query-range [promql] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--end` | | Range end as Unix seconds (use with `--start`) |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `--range` | | Duration relative to now (e.g. 15m, 1h, 6h, 24h, 7d) |
| `--start` | | Range start as Unix seconds (use with `--end`) |
| `--step` | | Resolution step (e.g. 30s, 1m, 5m) |
| `--timeout` | `0` | Query timeout in seconds (default server-side) |

## ankra cluster morpheus

Commands to create, stop, start, and inspect HPE Morpheus clusters.

## ankra cluster morpheus bastion

Inspect and diagnose the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster morpheus bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster morpheus bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster morpheus bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster morpheus bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus clouds

List HPE Morpheus clouds available to a credential

```bash theme={null}
ankra cluster morpheus clouds [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | HPE Morpheus API credential ID (required) |

## ankra cluster morpheus control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster morpheus control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster morpheus control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster morpheus control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus control-plane set-instance-type

Change the instance type of every controller in a HPE Morpheus cluster.

The instance type is stored as given; it is not checked against HPE Morpheus's catalog.
A name that does not exist is rejected by HPE Morpheus itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster morpheus plans
```

```bash theme={null}
ankra cluster morpheus control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus create

Create a new HPE Morpheus cluster

```bash theme={null}
ankra cluster morpheus create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-plan-id` | `0` | Service plan ID for the bastion (required; see `ankra cluster morpheus plans`) |
| `--cloud-id` | `0` | Morpheus cloud ID (required; see `ankra cluster morpheus clouds`) |
| `--cni` | | CNI plugin (optional; the platform default is used when omitted) |
| `--control-plane-count` | `1` | Number of control plane nodes |
| `--control-plane-plan-id` | `0` | Service plan ID for control plane nodes (required) |
| `--credential-id` | | HPE Morpheus API credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm (default, vanilla upstream Kubernetes with Cilium) or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `3` | Number of dedicated etcd nodes when `--etcd-topology=external` (3 or 5) |
| `--etcd-plan-id` | `0` | Service plan ID for dedicated etcd nodes when `--etcd-topology=external` (optional) |
| `--etcd-topology` | `stacked` | etcd topology for kubeadm clusters: stacked (on control plane) or external (dedicated instances) |
| `--group-id` | `0` | Morpheus group ID (required; see `ankra cluster morpheus groups`) |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Install Traefik + cert-manager as Ankra-managed stacks for ingress (exposed via the built-in k3s service load balancer; default on) |
| `--kubernetes-version` | | Kubernetes version (optional; see `ankra cluster kubeadm-versions` or `ankra cluster k3s-versions`) |
| `--layout-id` | `0` | Morpheus instance-type layout ID (required; see `ankra cluster morpheus layouts`) |
| `--name` | | Cluster name (required) |
| `--network-id` | `0` | Morpheus network ID (required; see `ankra cluster morpheus networks`) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--virtual-image-id` | `0` | Morpheus virtual image ID (optional) |
| `--worker-count` | `1` | Number of worker nodes |
| `--worker-plan-id` | `0` | Service plan ID for worker nodes (required) |

## ankra cluster morpheus groups

List HPE Morpheus groups available to a credential

```bash theme={null}
ankra cluster morpheus groups [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | HPE Morpheus API credential ID (required) |

## ankra cluster morpheus k8s-version

Get current Kubernetes version for an HPE Morpheus cluster

```bash theme={null}
ankra cluster morpheus k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus layouts

List HPE Morpheus instance-type layouts available to a credential

```bash theme={null}
ankra cluster morpheus layouts [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | HPE Morpheus API credential ID (required) |

## ankra cluster morpheus networks

List HPE Morpheus networks available to a credential

```bash theme={null}
ankra cluster morpheus networks [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | HPE Morpheus API credential ID (required) |

## ankra cluster morpheus nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster morpheus nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster morpheus nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster morpheus nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster morpheus plans

List HPE Morpheus service plans available to a credential

```bash theme={null}
ankra cluster morpheus plans [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | HPE Morpheus API credential ID (required) |

## ankra cluster morpheus start

Start (re-provision) a stopped HPE Morpheus cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster morpheus start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster morpheus stop

Stop an HPE Morpheus cluster's instances while keeping its configuration so it can be started again later.

```bash theme={null}
ankra cluster morpheus stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands (also stops a cluster that is still being created) |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster morpheus workers

Get current worker count for an HPE Morpheus cluster

```bash theme={null}
ankra cluster morpheus workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster move

Move a cluster into another existing organisation.

Only an administrator of BOTH the current organisation and the destination can
move a cluster. The cluster keeps its id, agent, executions, resources, security
findings, insights, DNS records and variables. Bindings that belong to the
current organisation are detached and reported: access grants, kube tokens,
notification routes and mutes, security report schedules, trusted AI actions
and cluster-group memberships. Billing, audit and chat history stay with the
current organisation.

Only imported clusters can be moved for now: Ankra-provisioned and managed
Kubernetes clusters use a provider credential that belongs to the current
organisation, so the platform refuses to move them. The platform also refuses
the move while operations are running on the cluster, while the cluster is a
member of a cluster mesh, while it has DNS zones bound to the current
organisation (a published cluster domain or custom DNS zones), for playground
and sandbox clusters, and when the destination already has a cluster with the
same name.

The destination is resolved among your organisations by id, slug or name.
If no cluster name is provided, the currently selected cluster is moved.

```bash theme={null}
ankra cluster move [cluster_name] [flags]
```

**Examples**

```bash theme={null}
ankra cluster move edge-01 --organisation acme-prod
ankra cluster move --organisation 6f1c... --yes
ankra cluster move edge-01 --organisation "Acme Prod" -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--organisation` | | Destination organisation (id, slug or name); you must be an admin there (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster node-group

List, add, scale, upgrade, and delete node groups on a cloud cluster.

The cloud provider (Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, Ankra Cloud, AWS, Proxmox VE, or
HPE Morpheus) is detected automatically from the cluster.

## ankra cluster node-group add

Add a node group

```bash theme={null}
ankra cluster node-group add <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--availability-zone` | | Pin every node of the group to one availability zone, on OVH 3-AZ regions (e.g. eu-west-par-b). See 'ankra cluster ovh regions `--with-zones`'. Pin the group when it runs zonal storage: an OVH volume cannot attach from another zone. Omitted on a zone-spread cluster, each node takes the zone with the fewest instances cluster-wide, so a one-node group lands wherever the cluster is thinnest, not where its name suggests; on a cluster with no zone pool OVH chooses |
| `--count` | `1` | Number of nodes |
| `--cpu-pool` | | CPU pool of the cluster's zone every server the group creates is pinned to, scale-ups included (Ankra Cloud clusters only). Pick one with 'ankra cluster ankracloud cpu-pools `--cluster` \<cluster>': a pool of x86-64 level 3 has AVX2, which images built with current Python, Rust or Go wheels may need (they crash with an illegal instruction, exit 132, on a lower level). Default: the Cloud places each server |
| `--disk-gib` | `0` | Root disk size in GiB of every server the group creates, scale-ups included (Ankra Cloud clusters only; default: the plan's included disk). Ankra Cloud refuses a size below the plan's and the template's minimum |
| `--disk-tier` | | Storage tier of the root disk of every server the group creates, scale-ups included (Ankra Cloud clusters only): local-nvme (the node's own disks, the choice for CI nodes), standard, maxiops or hdd (the zone's Ankra Storage). Default: the zone's default tier |
| `--instance-type` | | Server type / flavor / plan for nodes (required) |
| `--labels` | | Comma-separated key=value labels every node of the group carries, from its first boot |
| `--name` | | Node group name (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--taints` | | Comma-separated key=value:Effect taints every node of the group registers with (value optional, effect defaults to NoSchedule); a tainted group runs only pods that tolerate them, such as pipeline pods placed with 'ankra cluster agent ci set `--node-group`' |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--user-data-file` | | Path to a cloud-init user-data file for the group (OVH clusters only). Applied verbatim at first boot by every instance the group ever creates, replacements included; Ankra sends no cloud-init of its own, so the document is not merged with anything. Max 65535 bytes. Use for provision-time disk layouts, e.g. carving a partition for LUKS before growpart runs |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |
| `--zone` | | Pin every node of the group to one zone of an UpCloud multi-zone cluster's pool (e.g. se-sto1). Pin the group when it runs zonal storage: an UpCloud volume cannot attach from another zone. Omitted spreads the group across the pool; refused on a single-zone cluster |

## ankra cluster node-group autoscaling

Read or write the Cluster Autoscaler settings of a node group.

When autoscaling is enabled, the Ankra-managed Cluster Autoscaler keeps the
group's node count within \[min, max] based on pod demand. Manual scaling
stays allowed but is clamped into the same bounds.

## ankra cluster node-group autoscaling get

Show autoscaling settings for a node group

```bash theme={null}
ankra cluster node-group autoscaling get <cluster_id|name> <group_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster node-group autoscaling set

Enable autoscaling with `--enabled` `--min` \<n> `--max` \<n>, or disable it with
`--enabled=false`. min must be at least 1 (scale-to-zero is not supported);
enabling requires the cluster's ankra-agent to be recent enough to serve
the autoscaler, and installs the Cluster Autoscaler on first enable.

```bash theme={null}
ankra cluster node-group autoscaling set <cluster_id|name> <group_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--enabled` | `true` | Enable (true) or disable (false) autoscaling |
| `--max` | `5` | Maximum node count while autoscaling |
| `--min` | `1` | Minimum node count while autoscaling (>= 1) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster node-group delete

Delete a node group and every node in it.

Each node removed is drained first, honouring its pods' PodDisruptionBudgets. A
node whose drain is refused (a budget allows no eviction, or the node cannot be
drained at all) is kept in service instead of removed, and a notice on the
cluster says why. Give the blocking workloads eviction headroom (more replicas
or a looser budget) and run the command again, or pass `--force-drain` to remove
the node anyway without honouring its PodDisruptionBudget. `--force-drain`
applies to this request only; use it only for a node you have decided to lose.

Examples:

```bash theme={null}
ankra cluster node-group delete <cluster_id> gpu-workers
ankra cluster node-group delete <cluster_id> gpu-workers --force-drain --yes
```

```bash theme={null}
ankra cluster node-group delete <cluster_id|name> <group_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets: each node of the group is removed even if its pods' disruption budget refuses the drain, instead of being kept. Use it only for nodes you have decided to lose |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster node-group labels

Replace the labels on every node in the group. Pass `--labels` as a comma-separated list of key=value pairs, or `--clear` to remove all labels. The cloud provider is detected automatically from the cluster.

```bash theme={null}
ankra cluster node-group labels <cluster_id|name> <group_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove all labels from the node group |
| `--labels` | | Comma-separated key=value pairs to set on the group |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster node-group list

List node groups

```bash theme={null}
ankra cluster node-group list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster node-group scale

Scale a node group up or down to \<count> nodes.

A scale-down picks the nodes to remove. Each node removed is drained first, honouring its pods' PodDisruptionBudgets. A
node whose drain is refused (a budget allows no eviction, or the node cannot be
drained at all) is kept in service instead of removed, and a notice on the
cluster says why. Give the blocking workloads eviction headroom (more replicas
or a looser budget) and run the command again, or pass `--force-drain` to remove
the node anyway without honouring its PodDisruptionBudget. `--force-drain`
applies to this request only; use it only for a node you have decided to lose.

Examples:

```bash theme={null}
ankra cluster node-group scale <cluster_id> workers 2
ankra cluster node-group scale <cluster_id> workers 2 --force-drain
```

```bash theme={null}
ankra cluster node-group scale <cluster_id|name> <group_name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the nodes a scale-down removes: a node is removed even if its pods' disruption budget refuses the drain, instead of being kept. Use it only for a node you have decided to lose. Has no effect on a scale-up |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster node-group taints

Replace the taints on every node in the group. Pass `--taints` as a comma-separated list of key=value:Effect (value optional, effect defaults to NoSchedule), or `--clear` to remove all taints. The cloud provider is detected automatically from the cluster.

```bash theme={null}
ankra cluster node-group taints <cluster_id|name> <group_name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove all taints from the node group |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--taints` | | Comma-separated key=value:Effect taints to set on the group |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster node-group upgrade

Change the instance type of every node in a node group. This cannot be reversed.

The resize power-cycles each node, and each is drained first, honouring its
pods' PodDisruptionBudgets. `--force-drain` bypasses those budgets for that
drain, so a node is resized even if its pods' disruption budget refuses the
eviction. It applies to this request only.

On UpCloud a plan is changed in place only within its plan family (STARTER,
DEV, PREMIUM, GPU, or the unprefixed general-purpose plans such as 4xCPU-8GB).
A new plan from another family replaces each node instead - drained, deleted
and re-provisioned with the new plan - and the command says so. A control
plane cannot be replaced that way, so a cross-family change there is refused.

Examples:

```bash theme={null}
ankra cluster node-group upgrade <cluster_id> workers <instance_type>
ankra cluster node-group upgrade <cluster_id> workers <instance_type> --force-drain
```

```bash theme={null}
ankra cluster node-group upgrade <cluster_id|name> <group_name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets when draining each node before its resize: a node is power-cycled even if its pods' disruption budget refuses the drain, so those pods lose the availability their budget protects. Use it only when you accept that disruption |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster operations

Commands to list, inspect, retry, and cancel executions and their steps.

## ankra cluster operations cancel

Cancel one or more running executions

```bash theme={null}
ankra cluster operations cancel <execution_id> [<execution_id>...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster operations cancel-step

Cancel a specific step within an execution

```bash theme={null}
ankra cluster operations cancel-step <execution_id> <step_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster operations hold

Set, read or lift a cluster's operations hold.

While a hold is in force the platform admits no new write operation on the
cluster: reconciliation, retries, node remediation and Kubernetes upgrades all
stop, while reads keep running. It is the lever that keeps the platform from
undoing a manual recovery, for example after a failed Kubernetes version hop.

These are Ankra staff operations. The platform refuses API tokens for them, so
they do not use your saved login: set ANKRA\_STAFF\_SESSION to the session of
your admin-portal sign-in, and pass the cluster by id. Every change is audited
with your name and the reason.

## ankra cluster operations hold get

Show the cluster's operations hold and any pending version record check

```bash theme={null}
ankra cluster operations hold get <cluster_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster operations hold lift

Lift the cluster's operations hold, whatever set it.

When a Kubernetes version record repair was made under the hold, the platform
refuses the lift until its reads have confirmed every node at the version the
record pins ('hold get' shows the check). `--force` overrides that refusal and
is recorded on the audit row; it asks for confirmation unless `--yes` is given.

```bash theme={null}
ankra cluster operations hold lift <cluster_id> --reason <text> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | lift even though a version record repair is not confirmed yet |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | why the platform may act on the cluster again (audited) |
| `-y`, `--yes` | `false` | skip the confirmation prompt of `--force` |

## ankra cluster operations hold set

Hold the cluster for `--for` from now (1m to 24h). Running it again extends
or shortens the hold to the new duration; both are audited.

Examples:

```bash theme={null}
ankra cluster operations hold set 62f4559a-a44d-46d7-aab3-a57c9dd6b4c6 --for 4h --reason "k3s hop failed, manual rollback"
```

```bash theme={null}
ankra cluster operations hold set <cluster_id> --for <duration> --reason <text> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--for` | `0s` | how long to hold the cluster from now (1m to 24h, e.g. 4h) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | why the platform must stop acting on the cluster (audited) |

## ankra cluster operations list

List executions for the active cluster, or show one by ID (no cluster needed)

```bash theme={null}
ankra cluster operations list [execution ID] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--attention` | | Keep only executions in this attention state: 'open' (a failure that still needs you) or 'resolved' (a later run or the resource's own recovery cleared it) |
| `--failed` | `false` | Shortcut for `--status` failed `--status` critical |
| `--include-internal` | `false` | Also list the platform's internal maintenance executions, such as the GitOps reconcile snapshot push, which the default listing hides |
| `--interval` | `5s` | Polling interval used when `--watch` is set |
| `--limit` | `50` | Maximum number of executions to return. Above 100, or with `--name`, the listing walks the API's pages instead of asking for one oversized page |
| `--name` | | Keep only executions whose name contains this text, case-insensitive: an add-on, manifest or stack name, for example 'kyverno' |
| `--no-collapse` | `false` | List every execution, instead of folding a run of identical successful ones into one row with a count |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | `[]` | Filter by execution status (repeatable). Examples: failed, critical, running |
| `-w`, `--watch` | `false` | Continuously poll and refresh until all executions reach a terminal state |

## ankra cluster operations retry

Retry a failed, cancelled or critical execution

```bash theme={null}
ankra cluster operations retry <execution_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster operations steps

List the steps of an execution with their status and error excerpt.

`--results` additionally fetches each step's job result - the structured
payload the scheduler recorded when the step finished (for example the
resources a teardown deleted, skipped, or failed to reclaim). Results are
printed under each step, and merged into the steps in -o json|yaml output.

```bash theme={null}
ankra cluster operations steps <execution_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--results` | `false` | Also fetch and show each step's recorded job result (what the step created, deleted, skipped, or failed to reclaim) |

## ankra cluster ovh

Commands to create, deprovision, and scale OVH Cloud clusters.

## ankra cluster ovh access-info

Show the gateway (bastion) and control plane IPs plus ready-to-use SSH jump and Kubernetes API port-forward commands.

```bash theme={null}
ankra cluster ovh access-info <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh bastion

Inspect, diagnose, and resize the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster ovh bastion allowed-ips

Replace the bastion/gateway's SSH source allowlist. Only the listed IPv4
addresses or CIDRs, the platform's own egress addresses and private network
sources can then reach port 22; every other source is dropped. The platform's
egress is always added by the platform itself, so it can never be locked out.

The list you give is the complete new list: entries may be separated by
spaces or commas. `--clear` removes the allowlist and makes the bastion
reachable from anywhere again (key-only SSH, rate-limited). IPv6 entries and
0.0.0.0/0 are refused; at most 64 entries.

The platform applies the list through the bastion update operation reported
on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

Examples:

```bash theme={null}
ankra cluster hetzner bastion allowed-ips my-cluster 203.0.113.7 198.51.100.0/24
ankra cluster ovh bastion allowed-ips my-cluster --clear
```

```bash theme={null}
ankra cluster ovh bastion allowed-ips <cluster_id|name> [ip-or-cidr ...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove the allowlist: SSH from anywhere again |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster ovh bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster ovh bastion resize

Resize the bastion/gateway node. The provider's bastion/gateway update job
powers it off, resizes it, and powers it back on, causing brief SSH/NAT
downtime for the cluster.

`--wait` covers the platform write only; the cloud resize runs as the operation
reported on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

```bash theme={null}
ankra cluster ovh bastion resize <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster ovh bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster ovh bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster ovh control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster ovh control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster ovh control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh control-plane set-instance-type

Change the instance type of every controller in a OVH cluster.

The instance type is stored as given; it is not checked against OVH's catalog.
A name that does not exist is rejected by OVH itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

```bash theme={null}
ankra cluster ovh control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh create

Create a new OVH cluster

```bash theme={null}
ankra cluster ovh create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--availability-zones` | `[]` | Availability zones to spread the cluster across, in a 3-AZ region (e.g. eu-west-par-a,eu-west-par-b,eu-west-par-c). See 'ankra cluster ovh regions `--with-zones`'. Omitted leaves placement to OVH, which puts every node in one zone. More than one zone needs `--control-plane-count=3` for etcd quorum |
| `--bastion-allowed-ips` | `[]` | IPv4 addresses or CIDRs allowed to reach the bastion over SSH, comma-separated (the platform's own egress is always allowed too; IPv6 and 0.0.0.0/0 are refused). Omit to keep the bastion reachable from anywhere (key-only SSH, rate-limited). Change it later with 'bastion allowed-ips'. |
| `--control-plane-count` | `1` | Number of control plane nodes |
| `--control-plane-flavor-id` | | Control plane instance flavor (server default: b3-16) |
| `--credential-id` | | OVH API credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--dhcp-end` | `10.0.1.200` | DHCP range end |
| `--dhcp-start` | `10.0.1.100` | DHCP range start |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm (default, vanilla upstream Kubernetes with Cilium) or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-flavor-id` | | Instance flavor for dedicated etcd nodes when `--etcd-topology=external` (server default: b3-16) |
| `--etcd-node-count` | `3` | Number of dedicated etcd nodes when `--etcd-topology=external` (3 or 5) |
| `--etcd-topology` | `stacked` | etcd topology for kubeadm clusters: stacked (on control planes) or external (dedicated VMs) |
| `--external-cloud-provider` | `true` | Install the OpenStack CCM and Cinder CSI (cloud-provider=external) for LoadBalancers and persistent volumes (default on; pass `--external-cloud-provider=false` to skip, which also disables `--include-networking`) |
| `--gateway-flavor-id` | | Gateway instance flavor (server default: c3-4) |
| `--gitops-branch` | `master` | GitOps branch to commit to |
| `--gitops-credential-name` | | GitOps GitHub credential name; when set with `--gitops-repository`, the generated ovh-cloud stack is committed to Git (optional) |
| `--gitops-repository` | | GitOps repository (e.g. org/repo) to commit the generated stack to (optional) |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Install Traefik + cert-manager for ingress (default on; pass `--include-networking=false` to skip). Requires `--external-cloud-provider` (the ingress LoadBalancer is provisioned by the cloud controller manager) |
| `--kubernetes-version` | | Kubernetes version (optional; see `ankra cluster kubeadm-versions` or `ankra cluster k3s-versions`) |
| `--name` | | Cluster name (required) |
| `--network-vlan-id` | `0` | Network VLAN ID |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | OVH Cloud region (required) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--subnet-cidr` | `10.0.1.0/24` | Subnet CIDR |
| `--worker-count` | `1` | Number of worker nodes |
| `--worker-flavor-id` | | Worker instance flavor (server default: b3-16) |

## ankra cluster ovh k8s-version

Get current Kubernetes version for an OVH cluster

```bash theme={null}
ankra cluster ovh k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh node-group

List, add, scale, upgrade, label, taint, and delete node groups.

## ankra cluster ovh nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster ovh nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster ovh nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster ovh nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster ovh nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster ovh nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster ovh nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster ovh nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ovh regions

List the OVH Cloud regions the supplied credential's project can deploy in. Only these regions are valid for cluster creation.

```bash theme={null}
ankra cluster ovh regions [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | OVH API credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--with-zones` | `false` | Also show each region's type and availability zones. Only region-3-az regions can place instances by zone; the zone names listed here are what `--availability-zones` and `--availability-zone` accept |

## ankra cluster ovh ssh-keys

Get and set the SSH key credentials authorised to access an OVH cluster's nodes.

## ankra cluster ovh start

Start (re-provision) a stopped OVH cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster ovh start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster ovh stop

Stop an OVH cluster's compute while keeping its configuration so it can be started again later.

```bash theme={null}
ankra cluster ovh stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and also delete the cluster's load balancers. The cluster's Cinder volumes are kept and keep billing while stopped: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster ovh workers

Get current worker count for an OVH cluster

```bash theme={null}
ankra cluster ovh workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster patch

Patch one or more live Kubernetes resources in the active cluster.

This is 'kubectl patch': the document given with `--patch` (inline, JSON or
YAML) or `--patch-file` is sent to the API server as a patch of the chosen
`--type` - 'strategic' (the default, the kubectl default too), 'merge' (RFC
7386 JSON merge patch) or 'json' (RFC 6902 JSON patch, a list of operations).
A patch changes only the fields it names and does not go through
server-side apply, so it is the way to correct a field on an object another
manager owns - a value the API server defaulted on an older chart, a label a
release left behind - without taking that object over or deleting it.

The kind takes the kubectl spellings - pod, deployment, deploy, service, svc,
configmap, cm, node, ... - and a custom resource is reachable with `--group`
and `--api-version`, exactly like 'cluster get resources' and 'cluster delete'.
Cluster-scoped built-in kinds (node, namespace, crd, storageclass, ...) need
no namespace; a cluster-scoped custom kind takes `--cluster-scoped` instead.
The patch goes through the cluster's Ankra agent: no kubeconfig is needed and
the same organisation permissions as the portal apply.

Each object reports its own outcome. The command exits 0 when everything was
patched, 3 when one of the objects did not exist, and 1 when the cluster
refused a patch.

Examples:

```bash theme={null}
ankra cluster patch deployment web -n prod --patch '{"spec":{"replicas":3}}'
ankra cluster patch service redis-headless -n data --type merge \
  --patch '{"spec":{"ipFamilyPolicy":"SingleStack","ipFamilies":["IPv4"]}}'
ankra cluster patch configmap settings -n prod --patch-file settings-patch.yaml --yes
ankra cluster patch deployment web -n prod --type json \
  --patch '[{"op":"remove","path":"/metadata/annotations/deprecated"}]'
ankra cluster patch node worker-1 --patch '{"metadata":{"labels":{"tier":"gpu"}}}' --dry-run
ankra cluster patch Certificate web-tls -n prod --group cert-manager.io --api-version v1 \
  --patch '{"spec":{"renewBefore":"720h"}}'
ankra cluster patch ClusterPolicy require-labels --group kyverno.io --api-version v1 --cluster-scoped \
  --type merge --patch '{"spec":{"validationFailureAction":"Audit"}}'
```

```bash theme={null}
ankra cluster patch <kind> <name> [name...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-version` | | API version for a kind outside the built-in set (e.g. v1, v1beta1) |
| `--cluster-scoped` | `false` | Treat a kind outside the built-in set as cluster-scoped (e.g. ClusterIssuer, ClusterPolicy); no `--namespace` is needed |
| `--dry-run` | `false` | Report what would change without changing anything |
| `--group` | | API group for a kind outside the built-in set (e.g. cert-manager.io) |
| `-n`, `--namespace` | | Kubernetes namespace (required for namespaced kinds) |
| `-p`, `--patch` | | The patch document, inline, as JSON or YAML |
| `--patch-file` | | Read the patch document from a JSON or YAML file instead of `--patch` |
| `--resource` | | Exact API resource plural when a custom kind has an irregular plural (e.g. backuprepositories) |
| `--type` | `strategic` | Patch type: strategic (default), merge (RFC 7386) or json (RFC 6902) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster playground

The playground is a real, writable Kubernetes environment Ankra provisions for you - a virtual cluster on Ankra's own infrastructure, with the agent already installed. Every organisation may hold one; it expires after a period of inactivity.

## ankra cluster playground create

Create the organisation's playground, optionally at a paid size from `ankra cluster playground plans`. Without `--size` the free trial is created. Provisioning runs in the background: poll `ankra cluster playground status <cluster_id>` until the phase reaches ready.

```bash theme={null}
ankra cluster playground create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--size` | | size to order, from `ankra cluster playground plans` (default: the free trial) |

## ankra cluster playground destroy

Tear the organisation's playground down. Everything deployed in it, including its storage, is deleted and cannot be recovered, so the command asks first; pass `--yes` to skip the prompt in scripts. Teardown runs in the background: poll `ankra cluster playground status <cluster_id>` until the phase reaches removed.

This is also how a refused `ankra org domain set` is cleared. A playground publishes a wildcard DNS record in the organisation's zone, and that record is reconciled rather than written once - deleting it with `ankra org dns delete` only lasts until the provisioner's next pass. Destroying the environment is what removes it for good.

```bash theme={null}
ankra cluster playground destroy <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster playground plans

List every playground size with its monthly price and whether the pool can place it right now. Order one with `ankra cluster playground create --size <id>`.

```bash theme={null}
ankra cluster playground plans
```

## ankra cluster playground resize

Change a paid playground to another paid size in place: only the namespace quota and the monthly price change (the month is billed pro-rata across the change), nothing you deployed is touched. The free trial cannot be resized - order a paid size instead.

```bash theme={null}
ankra cluster playground resize <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--size` | | the new size, from `ankra cluster playground plans` |

## ankra cluster playground status

Show the provisioning phase of a playground

```bash theme={null}
ankra cluster playground status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster power-schedules

Manage the cluster's power schedules: scheduled stop or start actions that
fire once at a chosen time or repeatedly on a cron expression, so a
development cluster can park itself outside working hours.

Power schedules are available for self-managed Hetzner, OVHcloud, UpCloud,
DigitalOcean, Scaleway, AWS (EC2), Proxmox VE, and HPE Morpheus clusters - the same
clusters that support manual stop and start. A scheduled stop behaves
like stopping the cluster yourself: on Hetzner, OVHcloud, UpCloud and
DigitalOcean the cluster's state is captured first (an encrypted etcd
snapshot the next start restores) unless `--preserve-state=false`; elsewhere
the provider VMs are terminated and only the configuration is preserved.
`--stop-mode` scale\_to\_zero deletes only the worker servers instead, and creates
new ones at the next start: the control plane and etcd, cloud volumes and
addresses are kept (and keep billing), and data on the workers' own disks is
lost at every stop. On a cluster whose volumes keep data there, the schedule
needs `--accept-node-local-data-loss` (or a yes at the prompt).
`--stop-mode` pause powers the servers off and keeps them.

`--stop-mode` pause keeps the cluster's state but saves no compute cost on
Hetzner, DigitalOcean or UpCloud (Developer and General Purpose plans):
they bill a powered-off server at its full price. To save money there, use
scale\_to\_zero or delete\_resources. On AWS and Scaleway a powered-off server
stops billing compute; its disks and IPs keep billing.

Examples:

```bash theme={null}
# Park a development cluster on weekday evenings, back before morning
ankra cluster power-schedules create --action stop --cron '0 19 * * 1-5' --timezone Europe/Stockholm
ankra cluster power-schedules create --action start --cron '0 7 * * 1-5' --timezone Europe/Stockholm

# One-off stop before the weekend
ankra cluster power-schedules create --action stop --at 2026-01-02T19:00:00Z
```

## ankra cluster power-schedules create

Create a scheduled stop or start on the active cluster. The schedule fires
once at `--at`, or repeatedly per `--cron` evaluated in `--timezone` (UTC when
omitted). A cluster can hold up to 20 schedules.

```bash theme={null}
ankra cluster power-schedules create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-node-local-data-loss` | `false` | For scale\_to\_zero stop schedules: accept that volumes keeping data on a worker's own disk (local-path, hostPath, local PVs) are emptied at every stop. Required when the cluster has such volumes and you are not answering the prompt interactively |
| `--action` | | What the schedule does when it fires: stop or start (required) |
| `--at` | | Fire once at this RFC 3339 time, e.g. 2026-01-02T19:00:00Z (mutually exclusive with `--cron`) |
| `--cron` | | Fire repeatedly per this 5-field cron expression, e.g. '0 19 \* \* 1-5' (mutually exclusive with `--at`) |
| `--enabled` | `true` | Whether the schedule is armed; `--enabled=false` creates or leaves it paused |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--preserve-state` | | For delete\_resources stop schedules: omit to capture the cluster's state (an encrypted etcd snapshot the next start restores) whenever the provider and distribution support it; 'false' to tear down without it; 'true' to state the default explicitly. On update, omitting it keeps the schedule's current choice |
| `--stop-mode` | | How a stop schedule stops the cluster: delete\_resources (default on create; terminates the VMs), scale\_to\_zero (deletes the worker servers at every stop and creates new ones at start: data on their own disks is lost; the control plane and etcd, cloud volumes and addresses are kept and keep billing) or pause (powers every server off and keeps it with its disks; k3s on Hetzner, UpCloud and DigitalOcean, and what a stop always does on AWS and Scaleway). pause saves no compute cost on Hetzner, DigitalOcean or UpCloud, which bill a powered-off server in full; use scale\_to\_zero or delete\_resources to save. On update, omitting it keeps the schedule's current mode |
| `--timezone` | | IANA timezone the cron expression is evaluated in, e.g. Europe/Stockholm (default UTC) |

## ankra cluster power-schedules delete

Delete a power schedule: it stops firing immediately and disappears from
the cluster's schedule list. The cluster itself is not touched. To pause a
schedule while keeping its configuration, use
'ankra cluster power-schedules update \<schedule\_id> ... `--enabled=false`'.

```bash theme={null}
ankra cluster power-schedules delete <schedule_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster power-schedules list

List the active cluster's power schedules

```bash theme={null}
ankra cluster power-schedules list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster power-schedules update

Replace a power schedule. This is a full replace, not a patch: pass the
complete schedule as it should be afterwards - `--action` plus one of `--at` or
`--cron` (with `--timezone` for cron schedules), and `--enabled=false` to leave it
paused. A stop schedule's `--stop-mode` and `--preserve-state` are the exception:
when omitted, the schedule's current choices are carried over, so a change of
timing never silently turns a state-discarding stop into a preserving one.
Use 'ankra cluster power-schedules list' for the schedule ID and the current
values.

```bash theme={null}
ankra cluster power-schedules update <schedule_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-node-local-data-loss` | `false` | For scale\_to\_zero stop schedules: accept that volumes keeping data on a worker's own disk (local-path, hostPath, local PVs) are emptied at every stop. Required when the cluster has such volumes and you are not answering the prompt interactively |
| `--action` | | What the schedule does when it fires: stop or start (required) |
| `--at` | | Fire once at this RFC 3339 time, e.g. 2026-01-02T19:00:00Z (mutually exclusive with `--cron`) |
| `--cron` | | Fire repeatedly per this 5-field cron expression, e.g. '0 19 \* \* 1-5' (mutually exclusive with `--at`) |
| `--enabled` | `true` | Whether the schedule is armed; `--enabled=false` creates or leaves it paused |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--preserve-state` | | For delete\_resources stop schedules: omit to capture the cluster's state (an encrypted etcd snapshot the next start restores) whenever the provider and distribution support it; 'false' to tear down without it; 'true' to state the default explicitly. On update, omitting it keeps the schedule's current choice |
| `--stop-mode` | | How a stop schedule stops the cluster: delete\_resources (default on create; terminates the VMs), scale\_to\_zero (deletes the worker servers at every stop and creates new ones at start: data on their own disks is lost; the control plane and etcd, cloud volumes and addresses are kept and keep billing) or pause (powers every server off and keeps it with its disks; k3s on Hetzner, UpCloud and DigitalOcean, and what a stop always does on AWS and Scaleway). pause saves no compute cost on Hetzner, DigitalOcean or UpCloud, which bill a powered-off server in full; use scale\_to\_zero or delete\_resources to save. On update, omitting it keeps the schedule's current mode |
| `--timezone` | | IANA timezone the cron expression is evaluated in, e.g. Europe/Stockholm (default UTC) |

## ankra cluster provision

Provision a managed cluster that is not running.

This works for a cluster that was created but never built, and for an imported
cluster that was deprovisioned. It cannot rebuild a deprovisioned cloud cluster
(hetzner, ovh, upcloud, digitalocean, scaleway, ankracloud, aws, proxmox, morpheus): that deprovision
deleted the record, so there is nothing left to provision - create a new
cluster instead.

Provisioning rebuilds the cluster's infrastructure and then redeploys its stack
resources from the cluster's stored stack definition. Verify anything you patched
in place afterwards - see "ankra cluster addons list \<addon>" and
"ankra cluster manifests list".

This is not a power-on. To resume a cluster you powered off, use the provider's
start command (for example "ankra hetzner cluster start") or
"ankra cluster power-schedules".

If no cluster name is provided, uses the currently selected cluster.

```bash theme={null}
ankra cluster provision [cluster_name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox

Commands to create, stop, start, and inspect Proxmox VE clusters.

## ankra cluster proxmox bastion

Inspect and diagnose the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster proxmox bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster proxmox bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster proxmox bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster proxmox bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox bridges

List Proxmox VE network bridges on a host node

```bash theme={null}
ankra cluster proxmox bridges [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Proxmox VE API credential ID (required) |
| `--node` | | Proxmox VE host node (required; see `ankra cluster proxmox hosts`) |

## ankra cluster proxmox control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster proxmox control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster proxmox control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox control-plane set-count

Change the number of controllers (1, 3 or 5; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster proxmox control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox control-plane set-instance-type

Change the instance type of every controller in a Proxmox VE cluster.

The instance type is stored as given; it is not checked against Proxmox VE's catalog.
A name that does not exist is rejected by Proxmox VE itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster proxmox sizes
```

```bash theme={null}
ankra cluster proxmox control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox create

Create a new Proxmox VE cluster

```bash theme={null}
ankra cluster proxmox create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-instance-type` | | Bastion instance-size preset (server default: px-small) |
| `--bridge` | | Network bridge for cluster VMs (required; see `ankra cluster proxmox bridges`) |
| `--cni` | | CNI plugin (optional; the platform default is used when omitted) |
| `--control-plane-count` | `1` | Number of control plane nodes |
| `--control-plane-instance-type` | | Control plane instance-size preset (server default: px-medium) |
| `--credential-id` | | Proxmox VE API credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm (default, vanilla upstream Kubernetes with Cilium) or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-instance-type` | | Instance-size preset for dedicated etcd nodes when `--etcd-topology=external` (server default: px-medium) |
| `--etcd-node-count` | `3` | Number of dedicated etcd nodes when `--etcd-topology=external` (3 or 5) |
| `--etcd-topology` | `stacked` | etcd topology for kubeadm clusters: stacked (on control plane) or external (dedicated VMs) |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Install Traefik + cert-manager as Ankra-managed stacks for ingress (exposed via the built-in k3s service load balancer; default on) |
| `--kubernetes-version` | | Kubernetes version (optional; see `ankra cluster kubeadm-versions` or `ankra cluster k3s-versions`) |
| `--name` | | Cluster name (required) |
| `--network-mode` | | Network mode: private\_network (default) or wireguard\_mesh. wireguard\_mesh puts the nodes on the platform WireGuard overlay behind the cluster bastion's site gateway, so the cluster can mesh with clusters on other sites and providers; kubeadm only, and a mesh cannot be retrofitted |
| `--node` | | Proxmox VE host node to deploy on (required; see `ankra cluster proxmox hosts`) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--placement-nodes` | `[]` | Two or more host nodes for host-spread placement (comma-separated or repeated; optional) |
| `--site-public-ip` | | Public address other sites dial this cluster's bastion on for the overlay (required with `--network-mode` wireguard\_mesh); the site forwards the overlay UDP port range from it to the bastion |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--storage` | | Storage for VM disks (default local-lvm; see `ankra cluster proxmox storages`) |
| `--template` | | VM template name (optional; the first available template on the node is used when omitted) |
| `--worker-count` | `1` | Number of worker nodes |
| `--worker-instance-type` | | Worker instance-size preset (server default: px-medium) |

## ankra cluster proxmox hosts

List the Proxmox VE host nodes the supplied credential can deploy virtual machines on.

```bash theme={null}
ankra cluster proxmox hosts [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Proxmox VE API credential ID (required) |

## ankra cluster proxmox k8s-version

Get current Kubernetes version for a Proxmox VE cluster

```bash theme={null}
ankra cluster proxmox k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster proxmox nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster proxmox nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster proxmox nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster proxmox nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster proxmox sizes

List the instance-size presets (px-small, px-medium, ...) accepted by the Proxmox VE instance-type flags.

```bash theme={null}
ankra cluster proxmox sizes
```

## ankra cluster proxmox start

Start (re-provision) a stopped Proxmox VE cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster proxmox start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster proxmox stop

Stop a Proxmox VE cluster's virtual machines while keeping its configuration so it can be started again later.

```bash theme={null}
ankra cluster proxmox stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands (also stops a cluster that is still being created) |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster proxmox storages

List Proxmox VE storages on a host node

```bash theme={null}
ankra cluster proxmox storages [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Proxmox VE API credential ID (required) |
| `--node` | | Proxmox VE host node (required; see `ankra cluster proxmox hosts`) |

## ankra cluster proxmox templates

List Proxmox VE VM templates on a host node

```bash theme={null}
ankra cluster proxmox templates [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Proxmox VE API credential ID (required) |
| `--node` | | Proxmox VE host node (required; see `ankra cluster proxmox hosts`) |

## ankra cluster proxmox workers

Get current worker count for a Proxmox VE cluster

```bash theme={null}
ankra cluster proxmox workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster reconcile

Trigger a reconciliation for a cluster to sync desired state with actual state.

If no cluster name is provided, uses the currently selected cluster.
If a cluster name is provided, reconciles that specific cluster.

```bash theme={null}
ankra cluster reconcile [cluster_name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster restart

Rolling-restart one or more workloads in the active cluster.

This is 'kubectl rollout restart': the pod template gets a fresh
kubectl.kubernetes.io/restartedAt annotation, so the controller replaces
every pod under its own rollout strategy - no downtime for a Deployment with
more than one replica, one pod at a time for a StatefulSet. Nothing else in
the spec changes. The kind is deployment, statefulset or daemonset; the
kubectl short and plural spellings work too.

Examples:

```bash theme={null}
ankra cluster restart deployment web -n prod
ankra cluster restart sts postgres -n data --yes
ankra cluster restart daemonset node-exporter -n monitoring --dry-run
```

```bash theme={null}
ankra cluster restart <kind> <name> [name...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--dry-run` | `false` | Report what would be restarted without changing anything |
| `-n`, `--namespace` | | Kubernetes namespace (required) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster roll-to

Roll a cluster to a specific resource version.

Uses the currently selected cluster unless `--cluster` is provided.

Example:

```bash theme={null}
ankra cluster roll-to --version abc123
```

```bash theme={null}
ankra cluster roll-to [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--version` | | Resource version ID to roll to (required) |

## ankra cluster scale

Scale the number of default-pool worker nodes up or down for a cloud cluster.

The cloud provider (Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, Ankra Cloud, AWS, Proxmox VE, or
HPE Morpheus) is detected automatically from the cluster, so you do not need to
remember which provider it runs on. To scale a named node group instead, use
'ankra cluster node-group scale'.

A scale-down picks the workers to remove. Each node removed is drained first, honouring its pods' PodDisruptionBudgets. A
node whose drain is refused (a budget allows no eviction, or the node cannot be
drained at all) is kept in service instead of removed, and a notice on the
cluster says why. Give the blocking workloads eviction headroom (more replicas
or a looser budget) and run the command again, or pass `--force-drain` to remove
the node anyway without honouring its PodDisruptionBudget. `--force-drain`
applies to this request only; use it only for a node you have decided to lose.

Examples:

```bash theme={null}
ankra cluster scale 62f4559a-a44d-46d7-aab3-a57c9dd6b4c6 3
ankra cluster scale 62f4559a-a44d-46d7-aab3-a57c9dd6b4c6 2 --force-drain
```

```bash theme={null}
ankra cluster scale <cluster_id|name> <worker_count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the nodes a scale-down removes: a node is removed even if its pods' disruption budget refuses the drain, instead of being kept. Use it only for a node you have decided to lose. Has no effect on a scale-up |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway

Manage the lifecycle of Scaleway clusters.

## ankra cluster scaleway bastion

Inspect the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster scaleway bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable. This provider has no bastion
diagnose job lane, so the recorded verdict is all there is to read.

```bash theme={null}
ankra cluster scaleway bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster scaleway control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster scaleway control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster scaleway control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway control-plane set-instance-type

Change the instance type of every controller in a Scaleway cluster.

The instance type is stored as given; it is not checked against Scaleway's catalog.
A name that does not exist is rejected by Scaleway itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

List the instance types that do exist with:

```bash theme={null}
ankra cluster scaleway instance-types
```

```bash theme={null}
ankra cluster scaleway control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway create

Create an Ankra-managed K3s or kubeadm cluster on Scaleway Instances.

Ankra owns the server graph, security group, Public Gateway v2, generated SSH
key and (unless `--private-network-id` adopts an existing one) the Private
Network. Run 'preflight' first to check region, zone, CIDR and SKU
availability - it proves availability, not project hard quota.

Examples:

```bash theme={null}
ankra cluster scaleway create --name prod --credential-id <id> \
  --ssh-key-credential-id <id> --region fr-par --zone fr-par-1
```

```bash theme={null}
ankra cluster scaleway create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-port` | `0` | Public Gateway bastion SSH port (server default: 61000) |
| `--cni` | | CNI plugin (default: the platform default; immutable after create) |
| `--control-plane-count` | `0` | Control plane node count (server default: 1) |
| `--control-plane-type` | | Control plane commercial type (server default: DEV1-M) |
| `--credential-id` | | Scaleway provisioning credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | | Kubernetes distribution: k3s or kubeadm (server default: k3s). kubeadm on Scaleway is Cilium-only |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `0` | External etcd node count, 3 or 5 (server default: 3) |
| `--etcd-topology` | | etcd topology: stacked or external (server default: stacked) |
| `--etcd-type` | | External etcd commercial type (server default: DEV1-M) |
| `--gateway-allowed-ips` | `[]` | CIDRs allowed to reach the gateway bastion |
| `--gateway-type` | | Public Gateway type (server default: VPC-GW-S) |
| `--include-dns` | `true` | Provision the DNS zone |
| `--include-networking` | `true` | Provision the networking stack |
| `--kubernetes-version` | | Pin a Kubernetes version (default: latest supported) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | | CIDR for the created Private Network |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--private-network-id` | | Adopt an existing Private Network instead of creating one |
| `--region` | | Scaleway region, e.g. fr-par (required) |
| `--retention-policy` | | Teardown policy for volumes and load balancers: retain or delete (server default: retain) |
| `--runtime-credential-id` | | Scaleway credential for the in-cluster CCM/CSI (defaults to the provisioning credential) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--worker-count` | `0` | Default-pool worker count (server default: 1) |
| `--worker-type` | | Worker commercial type (server default: DEV1-M) |
| `--zone` | | Scaleway zone in that region, e.g. fr-par-1 (required) |

## ankra cluster scaleway deprovision

Permanently delete a Scaleway cluster and the provider resources Ankra
created for it. Volumes and load balancers follow the cluster's
retention\_policy: 'retain' keeps them, 'delete' sweeps them. A 'delete'
cluster's persistent volumes are named first and deleted only when you
accept that: answer the prompt on a terminal, or pass
`--accept-volume-data-loss` (`--yes` does not imply it).

```bash theme={null}
ankra cluster scaleway deprovision <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-volume-data-loss` | `false` | Accept that deprovisioning deletes the cluster's persistent volumes (the cloud volumes its CSI driver provisioned) and the data on them, forced or not. Required when the cluster has such volumes, or Ankra cannot list them, and you are not answering the prompt on a terminal; `--yes` does not imply it. A cluster whose retention\_policy is retain (AWS, Scaleway, Ankra Cloud) keeps its volumes and needs no acknowledgement |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster scaleway gateway-types

List Scaleway Public Gateway types for a zone

```bash theme={null}
ankra cluster scaleway gateway-types [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Scaleway credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | Scaleway region, e.g. fr-par |
| `--zone` | | Scaleway zone, e.g. fr-par-1 |

## ankra cluster scaleway instance-types

List Scaleway instance types (commercial types) for a zone

```bash theme={null}
ankra cluster scaleway instance-types [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Scaleway credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | Scaleway region, e.g. fr-par |
| `--zone` | | Scaleway zone, e.g. fr-par-1 |

## ankra cluster scaleway k8s-version

Get current Kubernetes version for a Scaleway cluster

```bash theme={null}
ankra cluster scaleway k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway locations

List Scaleway regions and zones available to a credential

```bash theme={null}
ankra cluster scaleway locations [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Scaleway credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway networks

List Scaleway Private Networks a credential can adopt

```bash theme={null}
ankra cluster scaleway networks [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-id` | | Scaleway credential ID (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | Scaleway region, e.g. fr-par |
| `--zone` | | Scaleway zone, e.g. fr-par-1 |

## ankra cluster scaleway nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster scaleway nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster scaleway nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster scaleway nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster scaleway nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster scaleway nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster scaleway nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster scaleway nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster scaleway preflight

Run the Scaleway create preflight: region/zone reachability, CIDR overlap,
gateway and instance-type availability. A quota warning means SKU stock was
visible, not that project hard-quota headroom was proven.

Takes the same flags as 'create'.

```bash theme={null}
ankra cluster scaleway preflight [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-port` | `0` | Public Gateway bastion SSH port (server default: 61000) |
| `--cni` | | CNI plugin (default: the platform default; immutable after create) |
| `--control-plane-count` | `0` | Control plane node count (server default: 1) |
| `--control-plane-type` | | Control plane commercial type (server default: DEV1-M) |
| `--credential-id` | | Scaleway provisioning credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--description` | | Cluster description |
| `--distribution` | | Kubernetes distribution: k3s or kubeadm (server default: k3s). kubeadm on Scaleway is Cilium-only |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `0` | External etcd node count, 3 or 5 (server default: 3) |
| `--etcd-topology` | | etcd topology: stacked or external (server default: stacked) |
| `--etcd-type` | | External etcd commercial type (server default: DEV1-M) |
| `--gateway-allowed-ips` | `[]` | CIDRs allowed to reach the gateway bastion |
| `--gateway-type` | | Public Gateway type (server default: VPC-GW-S) |
| `--include-dns` | `true` | Provision the DNS zone |
| `--include-networking` | `true` | Provision the networking stack |
| `--kubernetes-version` | | Pin a Kubernetes version (default: latest supported) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | | CIDR for the created Private Network |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--private-network-id` | | Adopt an existing Private Network instead of creating one |
| `--region` | | Scaleway region, e.g. fr-par (required) |
| `--retention-policy` | | Teardown policy for volumes and load balancers: retain or delete (server default: retain) |
| `--runtime-credential-id` | | Scaleway credential for the in-cluster CCM/CSI (defaults to the provisioning credential) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--worker-count` | `0` | Default-pool worker count (server default: 1) |
| `--worker-type` | | Worker commercial type (server default: DEV1-M) |
| `--zone` | | Scaleway zone in that region, e.g. fr-par-1 (required) |

## ankra cluster scaleway start

Re-provision a stopped Scaleway cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster scaleway start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster scaleway stop

Stop a Scaleway cluster by terminating its compute while preserving its configuration so it can be re-provisioned later.

```bash theme={null}
ankra cluster scaleway stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and also delete the cluster's tagged load balancers even when retention\_policy is retain. The cluster's volumes are kept: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster scaleway workers

Get current worker count for a Scaleway cluster

```bash theme={null}
ankra cluster scaleway workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster select

Select a cluster and save it as the active cluster for subsequent commands.

If a cluster name is provided, it will be selected directly without prompting.
If no name is provided, an interactive picker is shown.

Examples:

```bash theme={null}
ankra cluster select
ankra cluster select my-cluster
```

```bash theme={null}
ankra cluster select [cluster_name]
```

## ankra cluster sops-config

Show the SOPS encryption configuration including the public key used for encrypting secrets.

```bash theme={null}
ankra cluster sops-config
```

## ankra cluster ssh-keys

Get, set, and re-sync the SSH key credentials authorised to access a cloud
cluster's nodes.

The cloud provider (Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, Ankra Cloud, AWS, Proxmox VE, or
HPE Morpheus) is detected automatically from the cluster.

## ankra cluster ssh-keys get

Show SSH keys attached to a cluster

```bash theme={null}
ankra cluster ssh-keys get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ssh-keys resync

Re-sync the cluster's SSH key with the cloud provider. Use this to repair a
stale provider-side SSH key reference (for example when the key was deleted and
re-created in the provider console) that blocks new node creation, and to
re-apply the authorised keys to running nodes.

```bash theme={null}
ankra cluster ssh-keys resync <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster ssh-keys set

Replace the SSH key credentials attached to a cluster. Changes take effect on
the next reconciliation and are applied to running nodes.

Pass `--clear` to remove all user SSH keys (the Ankra-managed key always remains).

```bash theme={null}
ankra cluster ssh-keys set <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove all user SSH keys (the Ankra-managed key is retained) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ssh-key-credential-ids` | `[]` | SSH key credential IDs (comma-separated or repeated) |

## ankra cluster stacks

Commands to list, create, delete, rename, and view history of stacks.

## ankra cluster stacks clone

Clone a stack from the current cluster to a target cluster.

The cloned stack is created as a draft on the target so it can be reviewed
before it is deployed. Encrypted values are stripped during cloning and must
be reconfigured on the target.

With `--with-data` the clone also carries the stack's data: a restore point is
taken on the source and restored onto the target by a run the command names.
The data moves after the clone, not during it, so the copy is a draft until
the restore has landed - a with-data clone never deploys at clone time, and
`--deploy` plans the deploy step rather than running it.

Data flags need `--with-data` beside them. Databases travel by default and
volumes only where named with `--include-pvc` namespace/name; `--exclude-databases`
needs `--confirm-exclude-databases`. Naming any selection flag REPLACES the
stack's stored backup selection for this clone rather than narrowing it, so
name the volumes to keep alongside `--exclude-databases`; leave every selection
flag off and the stored selection decides.

The vault resolves in order: `--vault`, the stack's own backup policy, then the
organisation's single ready vault. With `--from` latest the restore point is
read from the vault that holds it, so `--vault` is not accepted there.

Carrying volume data keeps the stack, Helm release and namespace names, so the
platform refuses `--name` for a clone whose plan holds volumes (a database-only
clone may still be renamed), and a target that already has a stack of this
name is refused rather than suffixed around.

Examples:

```bash theme={null}
ankra cluster stacks clone shop --to staging
ankra cluster stacks clone shop --to staging --with-data --wait
ankra cluster stacks clone shop --to staging --with-data --from latest
ankra cluster stacks clone shop --to staging --with-data --include-pvc shop/data --protect-source
```

```bash theme={null}
ankra cluster stacks clone <stack_name> --to <target_cluster> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--confirm-exclude-databases` | `false` | Acknowledge that the clone carries no database contents |
| `--deploy` | `false` | Deploy the cloned stack on the target; with `--with-data` the deploy is planned and waits for the restore |
| `--exclude-databases` | `false` | Carry no database contents (needs `--confirm-exclude-databases`); name the volumes to keep with `--include-pvc`, since this replaces the stored selection |
| `--from` | `fresh` | Where the data comes from: 'fresh' takes a restore point now, 'latest' restores the newest complete one the stack already has |
| `--idempotency-key` | | Reuse this key when retrying a with-data clone that may already have been accepted, so no second restore point is taken |
| `--include-config` | `true` | Include addon configurations |
| `--include-pvc` | `[]` | Carry this volume as namespace/name (repeatable); naming any selection flag replaces the stack's stored backup selection for this clone |
| `-n`, `--name` | | New stack name (optional, defaults to original) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--protect-source` | `false` | Write a backup policy onto the source stack if it has none, so this restore point is the first of a series |
| `--timeout` | `2h0m0s` | Maximum time to wait when `--wait` is set |
| `-t`, `--to` | | Target cluster name or ID (required) |
| `--vault` | | Backup vault name or id for the restore point `--from` fresh takes (default: the stack's policy vault, then the organisation's single ready vault); not accepted with `--from` latest |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |
| `--with-data` | `false` | Carry the stack's data: take a restore point on the source and restore it onto the target |

## ankra cluster stacks data

The stack's data inventory: standalone persistent volume claims and database custom resources with their claims folded in, each with the engine that would capture it and the consistency that engine can promise.

## ankra cluster stacks data list

List what a stack holds that a backup would have to carry.

Each asset says which engine would capture it and what consistency that engine
can promise: an engine either produces a consistent artifact or it declares
itself crash-consistent, and there is no third answer.

The live read of the database operators can come back unavailable - no relay,
or an offline agent - in which case the command says so rather than presenting
a partial inventory as the whole truth.

Only data a member of the stack owns is listed as the stack's, and each asset
says why it is: the member that owns it, or a namespace only this stack uses.
Data the sweep of the stack's namespaces finds that no member owns - another
stack's database in a shared namespace, an orphan claim - is listed separately
as not owned by this stack (unattributed). Unattributed data is never captured
or restored as this stack's, and the requested total does not count it.

Example:

```bash theme={null}
ankra cluster stacks data list shop
```

```bash theme={null}
ankra cluster stacks data list <stack> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster stacks delete

Delete a stack

```bash theme={null}
ankra cluster stacks delete <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster stacks deploy-draft

Deploy the pending draft of a stack on the active cluster: a stack that exists only as a draft (what a clone or a stack-profile instantiation leaves behind), or the draft of edits 'ankra cluster draft -f' or the stack builder left on a stack that is already deployed.

The draft's contents are deployed exactly as they are stored. Review them first with 'ankra cluster stacks list \<stack name>', and edit them in the stack builder if the clone warned that something has to change before it can come up.

For a stack that is already deployed only the members the draft changes are written; members it does not mention keep running untouched.

```bash theme={null}
ankra cluster stacks deploy-draft <stack name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster stacks history

Show history of changes for a stack

```bash theme={null}
ankra cluster stacks history <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster stacks list

List stacks for the active cluster; or show details for a single stack

```bash theme={null}
ankra cluster stacks list [stack name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster stacks protect

Turn on protection for a stack.

Protection is a property of the stack, not a separate object: the command
writes a backup block onto the stack's definition, and the platform converges
on it by installing the backup data plane on the cluster. Until that plane
exists the command reports the backup stack as "installing" rather than
claiming the stack is protected.

`--vault` is required; a protected stack with nowhere to write to is not
protected. `--schedule` takes hourly, daily, weekly, or a five-field cron
expression. `--retention` takes the buckets to keep, as key=value pairs.

Examples:

```bash theme={null}
ankra cluster stacks protect shop --vault production-backups
ankra cluster stacks protect shop --vault production-backups --schedule daily --retention daily=7,weekly=4,monthly=6
ankra cluster stacks protect shop --vault production-backups --include-pvc shop/data --backup-now --wait
```

```bash theme={null}
ankra cluster stacks protect <stack> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--backup-now` | `false` | Take the first restore point immediately instead of waiting for the schedule |
| `--confirm-exclude-databases` | `false` | Acknowledge that `--exclude-databases` means no database contents are carried |
| `--exclude-databases` | `false` | Leave this stack's database contents out of the capture |
| `--include-pvc` | `[]` | Persistent volume claim to carry, as namespace/name (repeatable). Volumes are carried only where named |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--retention` | | Restore points to keep, as key=value pairs: hourly, daily, weekly, monthly, yearly, minimum-count, minimum-age (for example daily=7,weekly=4,monthly=6) |
| `--schedule` | | hourly, daily, weekly, or a five-field cron expression |
| `--timeout` | `2h0m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault the restore points are written to (name or id, required) |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster stacks rename

Rename a stack

```bash theme={null}
ankra cluster stacks rename <old_name> <new_name>
```

## ankra cluster stacks restore-points

A restore point is an immutable copy of a stack's data in a backup vault, self-describing enough to be read without the cluster it came from. Backing up creates one; restoring applies one.

## ankra cluster stacks restore-points create

Take a restore point of a stack now.

The capture is dispatched by the platform, so the command answers with the
restore point in 'creating' and the run that will seal it. With `--wait` it
follows that run to completion and prints the sealed restore point.

The vault is resolved in order: `--vault`, then the stack's own backup policy,
then the organisation's single ready vault. With more than one ready vault and
nothing naming which, the platform refuses rather than choosing for you.

Examples:

```bash theme={null}
ankra cluster stacks restore-points create shop
ankra cluster stacks restore-points create shop --vault production-backups --wait
ankra cluster stacks restore-points create shop --include-pvc shop/data --note "before the 3.2 upgrade"
```

```bash theme={null}
ankra cluster stacks restore-points create <stack> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--confirm-exclude-databases` | `false` | Acknowledge that `--exclude-databases` means no database contents are carried |
| `--exclude-databases` | `false` | Leave this stack's database contents out of the capture |
| `--include-pvc` | `[]` | Persistent volume claim to carry, as namespace/name (repeatable). Volumes are carried only where named |
| `--note` | | Why this restore point was taken |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `2h0m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault to write to (name or id; default: the stack's own, then the organisation's single ready vault) |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster stacks restore-points delete

Delete a restore point.

The row goes either way, so a restore point whose cluster was destroyed is
never undeletable; the objects in the bucket are swept by an execution on the
source cluster, and when no sweep could be dispatched the command says why the
objects were left behind rather than understating the storage bill.

A restore point a backup, restore or clone is currently using is refused, and
so is one that is still being taken.

The id may be a prefix of the one the listing printed, at least 8 characters
long (the uuid's first group), checked for ambiguity against every restore
point the stack has; a shorter prefix is refused because a delete cannot be
undone, and the full id is always accepted.

```bash theme={null}
ankra cluster stacks restore-points delete <stack> <restore-point-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster stacks restore-points get

Describe one restore point: the manifest it carries, every asset in it, everything it does not carry, and the run that produced it. The id may be an unambiguous prefix of the one the listing printed; it is checked for ambiguity against every restore point the stack has, not just the newest page, and a prefix two of them share is refused with both named.

```bash theme={null}
ankra cluster stacks restore-points get <stack> <restore-point-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster stacks restore-points list

List the restore points taken of a stack, newest first.

The listing carries what each restore point does NOT contain as well as what
it does: a backup listing that showed sizes and hid omissions would be exactly
the silence this is here to remove.

Examples:

```bash theme={null}
ankra cluster stacks restore-points list shop
ankra cluster stacks restore-points list shop --status complete
ankra cluster stacks restore-points list shop --trigger scheduled --limit 10
```

```bash theme={null}
ankra cluster stacks restore-points list <stack> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cursor` | | Continue from a previous page's cursor |
| `--limit` | `0` | Page size (server default, maximum 200) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | `[]` | Only restore points in these statuses (creating, complete, failed, expiring, expired, deleted) |
| `--trigger` | `[]` | Only restore points with these triggers (manual, scheduled, clone, migrate, pre\_restore, verification) |
| `--vault` | | Only restore points in this backup vault (name or id) |

## ankra cluster stacks restore-points restore

Restore a restore point over the stack it was taken from.

This destroys before it replaces. Typing the stack's own name is what gates
it - the sequence the platform will follow is printed from its answer, once
the restore has been accepted and before any of its steps run:

1. Scale down the workloads that own the data.
2. Remove the volumes the restore point replaces.
3. Restore the restore point's assets onto the cluster.
4. Scale the workloads back up over the restored data.

Confirmation is the typed stack name, not y/N; `--yes` skips it for
scripts. A restore point carrying a CloudNativePG or Percona database is
refused with the platform's own reason - the ordinary restore path would
report success over unchanged data, which is worse than refusing.

A stack whose data has changed since the restore point was taken is refused
unless `--force`. An inventory whose live database scan did not run counts as
drift, because "we could not read it" is not "it is unchanged".

The id may be a prefix of the one the listing printed, at least 8 characters
long (the uuid's first group), checked for ambiguity against every restore
point the stack has; a shorter prefix is refused because the stack's volumes
are removed before anything is written back, and the full id is always
accepted.

```bash theme={null}
ankra cluster stacks restore-points restore <stack> <restore-point-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Restore even though the stack's data has changed since the restore point was taken |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `2h0m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |
| `--yes` | `false` | Skip the typed stack-name confirmation |

## ankra cluster stacks unprotect

Turn off protection for a stack.

Every restore point already taken is kept and stays restorable: removing
protection is a decision about the future, not about the past. The scheduled
backups and the rendered object stores disappear on the next render.

Confirmation is typing the stack's own name, not y/N; `--yes` skips it.

```bash theme={null}
ankra cluster stacks unprotect <stack> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the typed stack-name confirmation |

## ankra cluster stacks variables

Manage variables on a specific stack. Stack variables are the most
specific scope and shadow cluster and organisation variables of the same name
when this stack's manifests/addons are rendered.

```bash theme={null}
ankra cluster stacks variables list <stack>
ankra cluster stacks variables get <stack> DB_HOST
ankra cluster stacks variables set <stack> DB_HOST db.prod.example.com
ankra cluster stacks variables delete <stack> DB_HOST
```

Stack variables are stored on the stack spec itself; edits use the same
partial-stack PATCH endpoint as manifests/addons upgrade.

## ankra cluster stacks variables delete

Delete a variable from a stack

```bash theme={null}
ankra cluster stacks variables delete <stack> <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster stacks variables get

Get a single stack variable

```bash theme={null}
ankra cluster stacks variables get <stack> <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |

## ankra cluster stacks variables list

List variables on a stack

```bash theme={null}
ankra cluster stacks variables list <stack> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster stacks variables set

Create or update a stack variable. The value can be read from stdin by
passing "-".

```bash theme={null}
ankra cluster stacks variables set <stack> <name> <value> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--dry-run` | `false` | Print the proposed change without writing |

## ankra cluster state-snapshots

Ankra backs up the etcd state of every running cluster it provisions - every
Secret, ConfigMap, custom resource and PersistentVolume binding - every six
hours, encrypted, to your organisation's backup vault (or the Ankra-managed
default vault). A start that finds the cluster's etcd lost restores the newest
backup.

**Examples**

```bash theme={null}
ankra cluster state-snapshots retention
ankra cluster state-snapshots retention --days 30 --cluster prod
```

## ankra cluster state-snapshots retention

Show or set how many days of scheduled etcd backups Ankra keeps for the cluster.

Ankra keeps the four newest backups, plus the newest backup of each UTC day for
the retention window: 7 days unless you set another between 1 and 90. The
newest backup from before the cluster's last start or recovery incident is kept
whatever the window.

Without `--days` this shows the window. With `--days` it sets it; the next
retention pass applies it. A longer window keeps backups from then on and cannot
bring back ones already deleted. A shorter window deletes the daily backups
outside it from the vault, so it asks for confirmation first (`--yes` skips it).
Setting the window needs permission to change cluster settings (clusters.write).

-o json prints the platform's answer as it is.

```bash theme={null}
ankra cluster state-snapshots retention [--days N] [flags]
```

**Examples**

```bash theme={null}
ankra cluster state-snapshots retention
ankra cluster state-snapshots retention --days 30
ankra cluster state-snapshots retention --days 3 --yes --cluster dev -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--days` | `0` | Set the retention window in days (1 to 90) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation a shorter window asks for |

## ankra cluster terminal

Open an interactive shell in a container of the named pod, through the
platform - no kubeconfig and no port-forward. The local terminal is put in
raw mode, so every keystroke (Ctrl-C included) reaches the remote shell;
leave with exit or Ctrl-D. Window resizes follow the local terminal.

Every session is recorded by the platform and linked from the cluster's
audit log as an open\_pod\_terminal event; "ankra org terminal-session"
replays it. Needs kubernetes.exec on the cluster.

With one container the shell opens there; a pod with several needs
`--container`. Input that is not a terminal (a pipe) is forwarded as typed
and should end with exit, since the remote shell cannot see the pipe close.

To run one command non-interactively and get its exit code, use
"ankra cluster exec \<pod> -n \<namespace> -- \<command> \[args...]" instead;
`--shell` names a shell binary and cannot carry arguments.

```bash theme={null}
ankra cluster terminal <pod> [flags]
```

**Examples**

```bash theme={null}
ankra cluster terminal api-6d8f9c7b5-x2kq9 -n payments
ankra cluster terminal api-6d8f9c7b5-x2kq9 -n payments -c sidecar --shell /bin/bash
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-c`, `--container` | | Container to open the shell in (default: the pod's only container) |
| `-n`, `--namespace` | | Namespace of the pod (required) |
| `--shell` | `/bin/sh` | Path of the shell to start in the container (one executable, not a command line) |

## ankra cluster top

Show live resource usage measured by metrics-server.

This is the "which container just got OOMKilled" view. It reads the
aggregated metrics API directly, so it works on clusters where Prometheus
was never installed. For trends over time use 'ankra cluster metrics',
which queries Prometheus.

## ankra cluster top nodes

Show live CPU and memory usage per node, measured by metrics-server.

Percentages are computed against each node's allocatable capacity. If the
node list cannot be read the percentage columns are omitted rather than
guessed.

Examples:

```bash theme={null}
ankra cluster top nodes
ankra cluster top nodes --sort-by cpu
ankra cluster top nodes -o json
```

```bash theme={null}
ankra cluster top nodes [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `--sort-by` | `name` | Sort by: name, cpu or memory |

## ankra cluster top pods

Show live CPU and memory usage per pod, measured by metrics-server.

Without -n or `--all-namespaces` this reads every namespace, unlike kubectl
top, which defaults to the current one.

Examples:

```bash theme={null}
ankra cluster top pods -n default
ankra cluster top pods --all-namespaces --sort-by memory
ankra cluster top pods -n default --containers
ankra cluster top pods --all-namespaces -o json
```

```bash theme={null}
ankra cluster top pods [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-A`, `--all-namespaces` | `false` | Show pods across all namespaces |
| `--containers` | `false` | Break usage down per container |
| `-n`, `--namespace` | | Kubernetes namespace |
| `-o`, `--output` | `table` | Output format: table, json, yaml |
| `--sort-by` | `name` | Sort by: name, cpu or memory |

## ankra cluster uncordon

Clear the unschedulable mark 'cluster cordon' or 'cluster drain' set, so the
scheduler can place pods on the node again.

Example:

```bash theme={null}
ankra cluster uncordon worker-3
```

```bash theme={null}
ankra cluster uncordon <node>
```

## ankra cluster upcloud

Commands to create, deprovision, and scale UpCloud clusters.

## ankra cluster upcloud bastion

Inspect, diagnose, and resize the cluster's single bastion/gateway node.
Find its node ID with 'nodes list'.

## ankra cluster upcloud bastion allowed-ips

Replace the bastion/gateway's SSH source allowlist. Only the listed IPv4
addresses or CIDRs, the platform's own egress addresses and private network
sources can then reach port 22; every other source is dropped. The platform's
egress is always added by the platform itself, so it can never be locked out.

The list you give is the complete new list: entries may be separated by
spaces or commas. `--clear` removes the allowlist and makes the bastion
reachable from anywhere again (key-only SSH, rate-limited). IPv6 entries and
0.0.0.0/0 are refused; at most 64 entries.

The platform applies the list through the bastion update operation reported
on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

Examples:

```bash theme={null}
ankra cluster hetzner bastion allowed-ips my-cluster 203.0.113.7 198.51.100.0/24
ankra cluster ovh bastion allowed-ips my-cluster --clear
```

```bash theme={null}
ankra cluster upcloud bastion allowed-ips <cluster_id|name> [ip-or-cidr ...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove the allowlist: SSH from anywhere again |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud bastion diagnose

Dispatch the provider's read-only bastion diagnose job and wait for its
report: sshd configuration, failed-login volume, disk, failed units, journal
errors, listening ports, and pending security updates. Nothing on the host is
changed. The platform waits up to two minutes for the job; a slower run hands
back the operation id to poll with 'cluster operations list'.

```bash theme={null}
ankra cluster upcloud bastion diagnose <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster upcloud bastion resize

Resize the bastion/gateway node. The provider's bastion/gateway update job
powers it off, resizes it, and powers it back on, causing brief SSH/NAT
downtime for the cluster.

`--wait` covers the platform write only; the cloud resize runs as the operation
reported on success. Follow it with 'ankra cluster operations list \<operation\_id>'.

```bash theme={null}
ankra cluster upcloud bastion resize <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra cluster upcloud bastion status

Report the verdict the platform's bastion health loop last recorded for the
cluster's bastion/gateway: whether it is reachable, which hop a failed probe
stopped at, and when it was last checked. Nothing is probed by this command,
so it answers even while the bastion is unreachable - use 'bastion diagnose'
to SSH in and collect a fresh report.

```bash theme={null}
ankra cluster upcloud bastion status <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud control-plane

Inspect and change the control plane configuration. The controller count
is 1 or 3 (1, 3 or 5 on Proxmox VE): etcd needs an odd number of voting
members for quorum.

Growing the control plane may happen live on a running cluster: the new
controllers join it one at a time, keeping the Kubernetes API up. The platform
can refuse a live change (an operation already in flight, controllers still
reconciling, a configuration that pins the API to one controller), and says
why. Reducing it is applied offline: stop the cluster (its state is
preserved), change the count, then start it. On a stopped cluster either
change applies at the next start.

The instance type can also be changed on a running cluster that has three
controllers: they are then resized one at a time, keeping the Kubernetes API
up. With a single controller, resizing the only controller takes the API down
for a few minutes while it reboots: where the platform supports that live
resize it needs `--accept-api-downtime`, otherwise it needs a stopped cluster.

Run "control-plane get" to see which of the two is available right now.

## ankra cluster upcloud control-plane get

Show the current control plane configuration

```bash theme={null}
ankra cluster upcloud control-plane get <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud control-plane set-count

Change the number of controllers (1 or 3; etcd needs an odd number of
voting members for quorum).

On a running cluster growing the count may happen live: the new controllers
join one at a time and the command prints the operation to follow, unless the
platform refuses the live change and says why. Reducing it is
refused on a running cluster; stop the cluster (its state is preserved),
change the count, then start it. On a stopped cluster the change applies at
the next start.

Run "control-plane get" to see whether a count change is possible right now.

```bash theme={null}
ankra cluster upcloud control-plane set-count <cluster_id|name> <count> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud control-plane set-instance-type

Change the instance type of every controller in a UpCloud cluster.

The instance type is stored as given; it is not checked against UpCloud's catalog.
A name that does not exist is rejected by UpCloud itself, which on a stopped
cluster is at the next start - after this command has already reported
success.

On a running cluster the rolling resize drains each controller before resizing
it, honouring its pods' PodDisruptionBudgets. `--force-drain` bypasses them for
that drain, so pods whose budget refuses eviction are evicted anyway. It
applies to this request only, and only a live rolling resize reads it: a
stopped cluster's offline resize drains nothing and ignores it, and so does a
request the rolling resize refuses (fewer than three controllers) or has
nothing to do for (the controllers already run that type).

A running cluster with a single controller can be resized in place where the
platform supports it, but the Kubernetes API is down for a few minutes while
that server reboots on the new type. Workloads on the workers keep running;
kubectl, deploys, the Ankra agent and controllers pause until it is back. That
resize needs `--accept-api-downtime`: without it the command refuses before
sending anything. Scale the control plane to three controllers first for a
resize without downtime, or stop the cluster and resize it offline.

```bash theme={null}
ankra cluster upcloud control-plane set-instance-type <cluster_id|name> <instance_type> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-api-downtime` | `false` | Accept that resizing the only controller of a running cluster takes the Kubernetes API down for a few minutes while it reboots on the new type. Required for that resize; has no effect on a stopped cluster or one with three controllers |
| `--force-drain` | `false` | Bypass PodDisruptionBudgets for the rolling resize's drain of each control plane: pods whose disruption budget refuses eviction are evicted anyway. It only matters for a live rolling resize of a running cluster and has no effect on a stopped cluster's offline resize |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud create

Create a new UpCloud cluster

```bash theme={null}
ankra cluster upcloud create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--bastion-allowed-ips` | `[]` | IPv4 addresses or CIDRs allowed to reach the bastion over SSH, comma-separated (the platform's own egress is always allowed too; IPv6 and 0.0.0.0/0 are refused). Omit to keep the bastion reachable from anywhere (key-only SSH, rate-limited). Change it later with 'bastion allowed-ips'. |
| `--bastion-plan` | | Bastion plan (server default: STARTER-1xCPU-1GB) |
| `--cni` | | CNI plugin: flannel, calico, or cilium (optional; the platform default is used when omitted) |
| `--control-plane-count` | `1` | Number of control plane nodes |
| `--control-plane-plan` | | Control plane plan (server default: PREMIUM-2xCPU-4GB) |
| `--credential-id` | | UpCloud API credential ID (required) |
| `--criticality` | | Reporting level: production, staging, development or disposable (server default: the environment's own level) |
| `--distribution` | `kubeadm` | Kubernetes distribution: kubeadm (default, vanilla upstream Kubernetes with Cilium) or k3s |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (server default: development) |
| `--etcd-node-count` | `3` | Number of dedicated etcd nodes when `--etcd-topology=external` (3 or 5) |
| `--etcd-plan` | | Plan for dedicated etcd nodes when `--etcd-topology=external` (server default: PREMIUM-2xCPU-4GB) |
| `--etcd-topology` | `stacked` | etcd topology for kubeadm clusters: stacked (on control planes) or external (dedicated VMs) |
| `--external-cloud-provider` | `true` | Install the UpCloud CCM and CSI (cloud-provider=external) for LoadBalancers and persistent volumes (default on; pass `--external-cloud-provider=false` to skip, which also disables `--include-networking`) |
| `--gitops-branch` | `master` | GitOps branch to commit to |
| `--gitops-credential-name` | | GitOps GitHub credential name; when set with `--gitops-repository`, the generated upcloud-cloud-provider stack is committed to Git (optional) |
| `--gitops-repository` | | GitOps repository (e.g. org/repo) to commit the generated stack to (optional) |
| `--include-dns` | `true` | Give the cluster its own subdomain under ankra.cc and install external-dns, so an ingress hostname under that subdomain gets its DNS record and TLS certificate with no manual setup. Scope: external-dns only manages the generated subdomain - ingress hosts on your own domains are ignored, and their DNS records stay yours to create (default on; pass `--include-dns=false` to skip) |
| `--include-networking` | `true` | Install Traefik + cert-manager for ingress (default on; pass `--include-networking=false` to skip). Requires `--external-cloud-provider` (the ingress LoadBalancer is provisioned by the cloud controller manager) |
| `--kubernetes-version` | | Kubernetes version (optional; see `ankra cluster kubeadm-versions` or `ankra cluster k3s-versions`) |
| `--name` | | Cluster name (required) |
| `--network-ip-range` | | Private network IP range (optional). Left unset, Ankra picks a range that is free in your UpCloud account; pass one only to pin it (a range overlapping an existing network in the zone is refused) |
| `--network-mode` | | Network mode: private\_network or wireguard\_mesh. Derived when omitted (wireguard\_mesh for a multi-zone pool). Pass wireguard\_mesh on a single-zone kubeadm cluster to make it mesh-capable so zones can be added later with 'ankra cluster upcloud zones'; a mesh cannot be retrofitted |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ssh-key-credential-id` | | SSH key credential ID (required) |
| `--worker-count` | `1` | Number of worker nodes |
| `--worker-plan` | | Worker plan (server default: PREMIUM-2xCPU-4GB) |
| `--zone` | | UpCloud zone (required); the primary zone of a multi-zone cluster (bastion, first control plane, default network) |
| `--zones` | `[]` | Zone pool for a multi-zone cluster (e.g. fi-hel1,fi-hel2,se-sto1). Must include `--zone`. Needs at least 3 zones and `--control-plane-count=3` so the control plane survives the loss of any one zone; each extra zone gets its own private network and NAT gateway, and the nodes are joined by a platform-managed WireGuard mesh. kubeadm only. Omitted keeps the cluster in `--zone` |

## ankra cluster upcloud k8s-version

Get current Kubernetes version for an UpCloud cluster

```bash theme={null}
ankra cluster upcloud k8s-version <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud node-group

List, add, scale, upgrade, and delete node groups.

## ankra cluster upcloud nodes

Inspect every server Ankra manages for the cluster (control plane, workers,
and bastion or gateway). Soft-deleted entries from a stopped cluster are
included so the saved topology is visible before re-provisioning.

## ankra cluster upcloud nodes cloud-init-log

Fetch 'cloud-init status `--long`' and the tail of
/var/log/cloud-init-output.log from the node over the platform's bastion SSH
lane, as a tracked read-only operation. This is the debug surface for
node-group user-data: it shows whether the first-boot document ran and what
it printed, without needing the cluster's SSH key. Repeated calls attach to
an in-flight fetch instead of dispatching duplicates. Find node ids with
'nodes list'.

```bash theme={null}
ankra cluster upcloud nodes cloud-init-log <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud nodes diagnose

Dispatch the platform's read-only node diagnose job and wait for its report:
over the bastion SSH lane it snapshots the node's OS-level state - the
Kubernetes service unit and its journal, disk, memory, uptime, the kernel log
and the firewall path to the API server - and names the symptoms it finds.
Nothing on the node is changed. This is what to reach for when a node is
NotReady or its kubelet stopped posting status, below what 'cluster get' can
see. The same diagnosis the Ankra assistant runs as ssh\_diagnose\_node.

The platform waits up to two minutes for the job; a slower run hands back the
operation id to poll with 'cluster operations list', and repeated calls attach
to the run already in flight. Find node ids with 'nodes list'. Needs the
clusters.operate permission on the cluster.

```bash theme={null}
ankra cluster upcloud nodes diagnose <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `3m0s` | Maximum time to wait for the diagnosis report |

## ankra cluster upcloud nodes get

Show full spec and metadata for a single node

```bash theme={null}
ankra cluster upcloud nodes get <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud nodes list

List all nodes for the cluster

```bash theme={null}
ankra cluster upcloud nodes list <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud nodes restart

Schedule a native reboot (falling back to a power cycle) of the node as a
tracked operation. The node must be in the 'up' state and have no restart
already in flight. Workloads on the node are briefly unavailable while it
reboots. Works for any node returned by 'nodes list', including the
bastion/gateway.

```bash theme={null}
ankra cluster upcloud nodes restart <cluster_id|name> <node_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud start

Start (re-provision) a stopped UpCloud cluster. Use `--scope` control\_plane to bring up only the control plane.

```bash theme={null}
ankra cluster upcloud start <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--restore-state` | | Cluster state on start: omit to restore the newest state snapshot captured at stop when there is one; 'true' to require one (refused otherwise); 'false' to start a fresh cluster. |
| `--scope` | `all` | Provisioning scope: 'all' or 'control\_plane' |

## ankra cluster upcloud stop

Stop an UpCloud cluster's compute while keeping its configuration so it can be started again later.

`--force` also deletes the cluster's load balancers. The CSI storage volumes are kept, forced or not, and keep billing while the cluster is stopped; deprovision the cluster to delete them.

```bash theme={null}
ankra cluster upcloud stop <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Force stop: cancel every in-flight operation and block new operations for 60 seconds while the stop lands, and also delete the cluster's load balancers. The cluster's CSI storage volumes are kept and keep billing while stopped: only a deprovision deletes them |
| `--mode` | | How the stop leaves the VMs: 'delete\_resources' (default) terminates them (capturing the cluster state first where supported); 'pause' powers the servers off and keeps them with their disks, so etcd, local data and node identities survive and start powers them back on - compute and storage keep billing while paused. Pause is available for k3s clusters on Hetzner, UpCloud and DigitalOcean (a stop on AWS and Scaleway always pauses), cannot be combined with `--force`, and takes no `--preserve-state`. |
| `--preserve-state` | | Cluster state across the stop: omit to let Ankra capture an encrypted etcd snapshot whenever the provider and distribution support it (the VMs are terminated only once it is stored, and the next start restores it); 'true' to require the capture (a stop whose state cannot be captured is refused); 'false' to tear down without it (everything stored in the cluster itself is lost; cloud block volumes are kept). `--force` never captures. |

## ankra cluster upcloud workers

Get current worker count for an UpCloud cluster

```bash theme={null}
ankra cluster upcloud workers <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upcloud zones

Extend the zone pool of an UpCloud cluster created with `--network-mode` wireguard\_mesh
(or with `--zones`). Pass the full desired pool, primary zone first: zones can only be
added, never removed, and the pool must keep at least 3 zones with 3 control planes.
Every new zone gets its own private network and NAT gateway; node groups added or
scaled afterwards spread across the grown pool, and the cloud-provider stack
republishes with load balancers and volumes scoped to the primary zone.

```bash theme={null}
ankra cluster upcloud zones <cluster_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |
| `--zones` | `[]` | The desired zone pool, primary zone first (required). Every current zone must still be listed; new zones are added in the given order |

## ankra cluster update

Set the environment of an existing cluster - production, staging, development,
testing, local, or a name of your own - and the reporting level its insights
are graded at.

The environment is what alert rules, dynamic cluster groups and the cluster
list filter on; 'local' also stops offline alerts for the cluster. The
reporting level decides how severe the cluster's findings are graded:
production reports everything the scan finds, and staging, development and
disposable each need a wider blast radius before an issue is treated as
critical.

A preset environment brings its usual reporting level, the same pairing the
portal writes: production, staging and development keep their own name,
testing is graded as development and local as disposable. `--criticality`
overrides it. An environment of your own leaves the reporting level as it is
unless `--criticality` is given.

The environment is not part of an ImportCluster file: 'ankra cluster apply'
never changes it on an existing cluster, so a value set here stays until it
is changed here or in the portal.

The cluster is given by name or id; without one, the selected cluster is
updated.

```bash theme={null}
ankra cluster update [cluster] [flags]
```

**Examples**

```bash theme={null}
ankra cluster update so-infrastructure --environment development
ankra cluster update --environment eu-qa --criticality staging
ankra cluster update 3d0e2935-963b-4c7b-a494-b7266776ec68 --environment production -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--criticality` | | Reporting level: production, staging, development or disposable (default: the preset environment's own level; unchanged for a name of your own) |
| `--environment` | | Environment: production, staging, development, testing, local, or a name of your own (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upgrade

Upgrade the Kubernetes version on all nodes in a cloud cluster.

The cloud provider (Hetzner, OVH, UpCloud, DigitalOcean, Scaleway, Ankra Cloud, AWS, Proxmox VE, or
HPE Morpheus) is detected automatically from the cluster, so you do not need to
remember which provider it runs on. Both kubeadm and k3s clusters are
supported; list the available target versions with
'ankra cluster kubeadm-versions' or 'ankra cluster k3s-versions'.

Nodes upgrade one at a time (control plane first, then workers): each node is
cordoned, drained respecting PodDisruptionBudgets, upgraded, and gated on
being Ready at the target version before the rollout moves on. An etcd
snapshot is taken before the control plane upgrade. A drain blocked by a
PodDisruptionBudget aborts the rollout; pass `--force` to proceed anyway.
Downgrades and skipping minor versions are not supported.

The upgrade preflight runs first and is printed before anything changes (run it
alone with 'ankra cluster upgrade preflight'). A blocking check stops the upgrade
with exit code 8 and nothing changed; `--force` goes past only the
PodDisruptionBudget block, never the version, catalogue or restore-point checks.

Examples:

```bash theme={null}
ankra cluster upgrade 62f4559a-a44d-46d7-aab3-a57c9dd6b4c6 v1.33.2         # kubeadm
ankra cluster upgrade 62f4559a-a44d-46d7-aab3-a57c9dd6b4c6 v1.36.1+k3s1    # k3s
```

```bash theme={null}
ankra cluster upgrade <cluster_id|name> <target_version> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | proceed even when a node drain is blocked (bypasses PodDisruptionBudget failures and the preflight's PodDisruptionBudget block) |

## ankra cluster upgrade preflight

Run the read-only upgrade preflight for a hop to \<target\_version>.

Each check answers pass, warn, block or skipped, with a sentence and the evidence:

```text theme={null}
hop_plan                    versions per node, which nodes upgrade or are skipped; blocks a
                            minor skip (and prints the one-minor hops to take), a downgrade
                            or a version outside the catalogue
operations                  running operations, reconciling nodes, an operations block
pod_disruption_budgets      a budget that allows no disruption parks the drain on the node it
                            names (the one block 'ankra cluster upgrade --force' goes past)
cloudnative_pg              stopDelay longer than the 300 s drain timeout, single instances
control_plane_memory        MemAvailable now and over 24 h, from the cluster's metrics source
restore_points              newest cluster-state snapshot, backup vault, unprotected stacks
control_plane_reachability  SSH failures to a control plane in the last 24 h
k3s_address_pin             bind-address, advertise-address and node-ip on k3s control planes
```

A warning or a skipped check whose evidence could not be read was NOT checked; it did
not pass. 'ankra cluster upgrade' runs the same preflight first.

Exit codes: 0 when the verdict is ready (warnings included), 8 when a check blocks.

Examples:

```bash theme={null}
ankra cluster upgrade preflight my-cluster v1.35.9+k3s1
ankra cluster upgrade preflight my-cluster v1.35.9 -o json
```

```bash theme={null}
ankra cluster upgrade preflight <cluster_id|name> <target_version> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster upgrade rollback-record

Repair a cluster's Kubernetes version record after its nodes were rolled back
by hand from a failed version hop.

A failed hop leaves the platform's record pinning the new version, and the
platform then re-runs the hop as soon as it may act again. This writes every
control plane's record back to \<version> and up, each worker to \<version> (or
to the newer version it runs), and the cluster's Kubernetes version to
\<version>. The platform refuses it unless an operations hold is in force with at
least 10 minutes left, no write is running on the cluster, and its last read of
every control plane shows exactly \<version> (as the node reports it, e.g.
v1.34.5+k3s1). Then wait for 'ankra cluster operations hold get' to show the
record confirmed before lifting the hold.

This is an Ankra staff operation: set ANKRA\_STAFF\_SESSION and pass the cluster
by id. It asks for confirmation unless `--yes` is given.

Examples:

```bash theme={null}
ankra cluster upgrade rollback-record 62f4559a-a44d-46d7-aab3-a57c9dd6b4c6 v1.34.5+k3s1 --reason "cp-0 rolled back (tier 1)"
```

```bash theme={null}
ankra cluster upgrade rollback-record <cluster_id> <version> --reason <text> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | which rollback the record is brought in line with (audited) |
| `-y`, `--yes` | `false` | skip the confirmation prompt |

## ankra cluster validate

Validate an ImportCluster YAML file. The local structural, dependency,
and YAML checks run first (the same ones as 'ankra cluster apply `--dry-run`'),
then the file is sent to the Ankra API for server-side validation that the
offline checks cannot perform:

* chart existence in the Helm registries connected to your organisation
* plaintext Kubernetes Secret / unencrypted addon value detection
* parent references resolved against a cluster's existing resources

Nothing is applied. Use `--cluster` \<name|id> to validate the spec against an
existing cluster's deployed resources, and `--strict-secrets` to treat
plaintext secrets as errors instead of warnings.

```bash theme={null}
ankra cluster validate [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Validate against an existing cluster's resources (cluster name or ID) |
| `-f`, `--file` | | Path to the ImportCluster YAML file to validate |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--strict-secrets` | `false` | Treat plaintext secrets as errors instead of warnings |

## ankra cluster variables

Manage cluster-scoped variables that are available to every stack on the
cluster as template substitutions in manifests and addon values. Cluster
variables shadow organisation variables of the same name on this cluster.

```bash theme={null}
ankra cluster variables list
ankra cluster variables get DB_HOST --cluster prod
ankra cluster variables set DB_HOST db.prod.example.com
ankra cluster variables delete DB_HOST
```

When `--cluster` is omitted, the active selection is used.

## ankra cluster variables delete

Delete a cluster variable

```bash theme={null}
ankra cluster variables delete <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra cluster variables get

Get a single cluster variable

```bash theme={null}
ankra cluster variables get <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster variables list

List variables for a cluster

```bash theme={null}
ankra cluster variables list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cluster variables set

Create or update a cluster variable (upsert). The value can be read from
stdin by passing "-".

```bash theme={null}
ankra cluster variables set <name> <value> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster (name or ID); defaults to the active selection |
| `--description` | | Optional human-readable description |


# ankra completion
Source: https://docs.ankra.ai/reference/cli/completion

Generate or install shell completion scripts

## ankra completion

Generate or install shell completion scripts for ankra.

To print a completion script to stdout:

```bash theme={null}
ankra completion bash
ankra completion zsh
ankra completion fish
ankra completion powershell
```

To auto-detect your shell and install completions:

```bash theme={null}
ankra completion install
```

To install for a specific shell:

```bash theme={null}
ankra completion install --shell zsh
```

## ankra completion bash

Print bash completion script

```bash theme={null}
ankra completion bash
```

## ankra completion fish

Print fish completion script

```bash theme={null}
ankra completion fish
```

## ankra completion install

Detect your shell and install completion scripts automatically.

The command writes the completion script to the standard location for your
shell and updates your shell profile to source it (if needed).

Use `--shell` to override auto-detection.

```bash theme={null}
ankra completion install [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--shell` | | shell type (bash, zsh, fish, powershell) |

## ankra completion powershell

Print powershell completion script

```bash theme={null}
ankra completion powershell
```

## ankra completion zsh

Print zsh completion script

```bash theme={null}
ankra completion zsh
```


# ankra config
Source: https://docs.ankra.ai/reference/cli/config

Manage Ankra CLI settings

## ankra config

View and change local Ankra CLI preferences, such as the update channel.

## ankra config beta

Control whether 'ankra upgrade' installs pre-release (release candidate)
versions.

When enabled, 'ankra upgrade' resolves the newest release including
pre-releases such as v0.3.0-rc.1. When disabled (the default), only stable
x.x.x releases are installed.

## ankra config beta disable

Disable the beta update channel (use stable releases)

```bash theme={null}
ankra config beta disable
```

## ankra config beta enable

Enable the beta update channel

```bash theme={null}
ankra config beta enable
```

## ankra config beta status

Show whether the beta update channel is enabled

```bash theme={null}
ankra config beta status
```


# ankra cost
Source: https://docs.ankra.ai/reference/cli/cost

Read cloud cost: the fleet rollup, a cluster's estimate, the savings model, the measured ledger and the pricing settings

## ankra cost

Read the organisation's cloud cost - the same figures the portal shows under
Cost - for reporting and automation.

Every hour Ankra prices each cluster from its node inventory at the provider
list price and allocates the result to namespaces by their CPU and memory
share, so each team sees the share it drives. The fleet summary rolls every
priced cluster up by provider and lists the costliest clusters; its month to
date also counts what clusters spent this month before they were deleted or
stopped reporting, and names them, since no provider row includes it; a cluster
read adds the component breakdown, the namespace allocation and the daily
trend. The savings model reads the biggest priced clusters and proposes one
lever per cluster (right-size idle capacity, reduce unallocated run rate, or
an off-hours schedule for non-production) with the monthly saving each is
worth. The ledger follows each approved cost change through to the saving
measured seven days after it ran. The display currency and the effective
discount apply to every figure. The network egress estimate setting is stored,
not metered yet: no figure includes network egress today.

The fleet reads (summary, savings, ledger, trend, events, reconcile, budgets,
and the clusters 'autopilot get' lists) cover the project you act in (see
'ankra project current'); pass `--all-projects` to read the whole
organisation, or the global `--project` to read another project. Pass -o json
(or yaml) for the full API document.

## ankra cost autopilot

The cost autopilot decides which cost changes Ankra proposes on its own - the
Autopilot view in the portal. It never makes a change itself: everything it
files is a proposal that waits for a person to approve and run it (ankra cost
decisions).

Every environment kind (production, staging, development, preview, unknown)
defaults to a tier, each described by 'ankra cost autopilot get'. On
scheduled and managed, Ankra proposes stopping the cluster outside working
hours; on hands-off and ephemeral it proposes nothing on its own. A cluster
takes its environment's tier unless a person overrides it. The quiet hours
and the notification route are kept with the policy: the autopilot starts
nothing on its own at any hour and sends no notice to the route today.

An organisation that never set a policy is hands-off for every kind. Reading
the policy is open to every member; changing it needs billing.manage and
clusters.write (at the cluster, for an override).

## ankra cost autopilot clear

Remove a cluster's override, returning it to its environment's tier

```bash theme={null}
ankra cost autopilot clear <cluster> [flags]
```

**Examples**

```bash theme={null}
ankra cost autopilot clear staging-1
ankra cost autopilot clear staging-1 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cost autopilot get

Show the organisation's autopilot policy, the tiers, and the tier of every
live cluster in the project you act in. The policy is the organisation's, so
it reads the same in every project; only the cluster list follows the
project. `--all-projects` lists every project's clusters, and the global
`--project` flag picks another project. A cluster list your cluster
permissions cut short says so.

```bash theme={null}
ankra cost autopilot get [flags]
```

**Examples**

```bash theme={null}
ankra cost autopilot get
ankra cost autopilot get --all-projects
ankra cost autopilot get -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost autopilot override

Put one cluster in a tier whatever its environment kind. `--reason` is the
sentence a card shows for it (3 to 500 characters). The override replaces
the cluster's previous one and lasts until `--expires-at` (an RFC 3339 time) or
for `--expires-in` (a duration such as 72h), or with no expiry when neither is
given. 'ankra cost autopilot clear' returns the cluster to its environment's
tier.

```bash theme={null}
ankra cost autopilot override <cluster> [flags]
```

**Examples**

```bash theme={null}
ankra cost autopilot override staging-1 --tier managed --reason "Load test week, keep it lean"
ankra cost autopilot override prod-eu --tier hands-off --reason "Launch freeze" --expires-in 72h
ankra cost autopilot override prod-eu --tier scheduled --reason "Quarter close" --expires-at 2026-10-01T00:00:00Z
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--expires-at` | | When the override stops applying, as an RFC 3339 time (no expiry when omitted) |
| `--expires-in` | `0s` | How long the override applies from now, e.g. 72h (no expiry when omitted) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why, as a card shows it (3 to 500 characters) |
| `--tier` | | The tier: hands-off, scheduled, managed or ephemeral |

## ankra cost autopilot set

Change the organisation's autopilot policy. Only what you pass is sent, so
every other part keeps its value: `--default` changes only the environment
kinds it names, and the quiet hours and the notification route change only when
you pass them or clear them.

`--default` KIND=TIER may repeat. The kinds are production, staging,
development, preview and unknown; the tiers are hands-off, scheduled, managed
and ephemeral. `--quiet-hours` takes a daily window as START-END in 24-hour
HH:MM (an end before the start runs past midnight) and needs `--timezone`, an
IANA zone.

```bash theme={null}
ankra cost autopilot set [flags]
```

**Examples**

```bash theme={null}
ankra cost autopilot set --default development=managed --default preview=ephemeral
ankra cost autopilot set --quiet-hours 22:00-07:00 --timezone Europe/Stockholm
ankra cost autopilot set --clear-quiet-hours
ankra cost autopilot set --notification-route 5a2b9c6d-0e1f-4a3b-8c5d-6e7f8091a2b3
ankra cost autopilot set --clear-notification-route
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear-notification-route` | `false` | Remove the notification route from the policy |
| `--clear-quiet-hours` | `false` | Remove the quiet hours |
| `--default` | `[]` | KIND=TIER: the tier an environment kind defaults to (repeatable; kinds you do not name keep theirs) |
| `--notification-route` | | The id of a notification route to keep with the policy (no notice is sent to it today) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--quiet-hours` | | A daily window START-END in 24-hour HH:MM, e.g. 22:00-07:00 (needs `--timezone`) |
| `--timezone` | | The IANA timezone of `--quiet-hours`, e.g. Europe/Stockholm |

## ankra cost budgets

Monthly cost budgets for the organisation, one project, one cluster, one
environment label or one application - the budgets the portal shows under Cost.

Each budget carries its month as of the read: spent so far, the projected
month end at the current pace, the hour it crosses the budget, and where the
month lands once the changes already approved or running have landed. A
budget whose scope has no priced cluster reads "unknown", never zero, and a
budget whose scope is only partly priced says how much of it is in the
figures.

Reading budgets is open to every member. Adding, changing and removing one
needs the billing.manage permission.

## ankra cost budgets delete

Remove a budget (its card is no longer raised)

```bash theme={null}
ankra cost budgets delete <budget-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost budgets delete 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
ankra cost budgets delete 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cost budgets list

List the budgets with their month: spent, projected month end, status and crossing hour

```bash theme={null}
ankra cost budgets list [flags]
```

**Examples**

```bash theme={null}
ankra cost budgets list
ankra cost budgets list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost budgets set

Without a budget id, add a monthly budget for one scope: `--scope`, `--name`,
`--amount` and `--currency` are required, and `--notify-at` and `--owner` are
optional (the platform notifies at 80% of the budget unless told otherwise).
A scope holds at most one budget.

With a budget id ('ankra cost budgets list' shows them), change that budget.
Only the flags you pass are sent; every other field keeps its value.
`--clear-owner` removes the owner. A budget's scope never changes: delete it and
add one on the other scope instead.

`--amount` is the budget per month in the currency's major unit (1500 or
1500.50). `--scope-id` names the project (slug, name or id), the cluster (name
or id), the application (name or id) or the environment label; an
organisation budget takes none.

```bash theme={null}
ankra cost budgets set [budget-id] [flags]
```

**Examples**

```bash theme={null}
ankra cost budgets set --scope organisation --name "Fleet" --amount 20000 --currency eur
ankra cost budgets set --scope cluster --scope-id prod-eu --name "prod-eu" --amount 1500 --currency eur --notify-at 90
ankra cost budgets set --scope project --scope-id platform-team --name "Platform team" --amount 5000 --currency eur
ankra cost budgets set --scope environment --scope-id production --name "Production" --amount 8000 --currency usd
ankra cost budgets set 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --amount 1800
ankra cost budgets set 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --clear-owner
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--amount` | | The budget per month in the currency's major unit, e.g. 1500 or 1500.50 |
| `--clear-owner` | `false` | Remove the budget's owner (changing a budget only) |
| `--currency` | | The budget's currency, e.g. usd, eur or gbp |
| `--name` | | The budget's name (1 to 120 characters) |
| `--notify-at` | `0` | The share of the budget, in percent (1-100), the projection must reach to raise the budget's card |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--owner` | | The user id of the member the budget is for |
| `--scope` | | What the new budget covers: organisation, project, cluster, environment or application |
| `--scope-id` | | The project (slug, name or id), the cluster (name or id), the application (name or id) or the environment label the new budget covers |

## ankra cost cluster

A cluster's cost estimate: totals, component breakdown, namespace allocation and readiness

```bash theme={null}
ankra cost cluster <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost cluster prod-eu
ankra cost cluster 1834920e-3001-4157-8938-33c447031033 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost decisions

The decision ledger holds every cost change Ankra proposes - a right-size, a
right-size ladder, an off-hours schedule, a waste cleanup - with its plan,
where it stands, who decided and what running it did.

A proposal is proposed until a person approves or sets it aside; an approved
one runs when a person executes it. The cost autopilot only files proposals:
it never approves or runs one. A right-size ladder runs one wave at
a time: each wave is its own right\_size proposal under the ladder, and the
next wave runs only once the last one has passed its seven-day verification.

Reading is open to every member. Approving, setting aside and running need
billing.manage, and running a right-size also needs clusters.write.

## ankra cost decisions activity

Everything that happened to a proposal, newest first

```bash theme={null}
ankra cost decisions activity <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions activity 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
ankra cost decisions activity 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost decisions approve

Approve a proposal's plan. The approval is of one plan: the platform refuses
it, and approves nothing, when the proposal was proposed again with another
plan in the meantime (the cost autopilot and the web page refresh proposals
that nobody has decided yet).

Pass `--plan-hash` with the plan\_hash 'ankra cost decisions get' showed you to
approve exactly the plan you reviewed. Without it the proposal is read first,
its plan is shown, and you are asked before anything is approved; `--yes`
approves the plan just shown without asking. Without a terminal to ask on,
or with -o json|yaml, approving needs `--plan-hash` or `--yes`: a script that
never saw the plan does not approve it. Either way the platform refuses the
approval, and approves nothing, when the plan changed after it was shown.

```bash theme={null}
ankra cost decisions approve <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions get 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
ankra cost decisions approve 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --plan-hash <plan_hash from get>
ankra cost decisions approve 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --note "Checked with the platform team"
ankra cost decisions approve 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --yes -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | A note recorded with the decision (up to 2000 characters) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--plan-hash` | | The plan\_hash 'ankra cost decisions get' showed: approve that plan or nothing (read, shown and asked first when omitted) |
| `-y`, `--yes` | `false` | Without `--plan-hash`, approve the plan the proposal holds now without asking (it is still shown on stderr) |

## ankra cost decisions execute

Run an approved proposal as you: the platform dispatches the operation its
kind maps to (an off-hours schedule creates the stop and start power
schedules, a waste cleanup files the cloud cleanup job, a right-size ladder
files and runs its next wave) and records the receipt. The answer is the
proposal as the run left it: running with the operation to follow,
succeeded, or failed with the receipt saying why (exit 1).

A plan that deletes something no snapshot keeps (an unattached volume) runs
only with written consent: pass `--acknowledge-no-snapshot` once you accept
that the deletion is final. Without it the platform refuses and nothing is
attempted. For a waste cleanup the consent sent names what kind of resource
it removes (a volume, a stopped server, an address, a load balancer) where
the platform names one, and the prompt shows what you agree to; otherwise it
is the general consent to a deletion with no snapshot. `--min-unattached-days`
sets the minimum age of what a waste cleanup deletes (the platform raises
anything under 30). Neither is ever sent unless you pass it.

A ladder whose latest wave is still running, inside its seven-day
verification or tripped by it is not run: the platform says which, and
running it again before that changes is refused the same way.

```bash theme={null}
ankra cost decisions execute <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions execute 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
ankra cost decisions execute 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --acknowledge-no-snapshot --min-unattached-days 60 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--acknowledge-no-snapshot` | `false` | Give the written consent a plan that deletes something no snapshot keeps needs: the deletion is final (a waste cleanup sends the consent naming what it removes) |
| `--min-unattached-days` | `0` | The minimum age, in days, of what a waste cleanup deletes (0-3650; the platform raises anything under 30) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cost decisions get

Show one proposal: its plan, decision, outcome, receipt and, for a ladder, its waves

```bash theme={null}
ankra cost decisions get <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions get 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
ankra cost decisions get 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost decisions hold

Hold an approved proposal before it runs. A held proposal is run by nothing,
not even execute. It stays held until someone releases it (ankra cost
decisions release) or sets it aside. Only an approved proposal can be held;
any other status is refused and the proposal stays as it stands.

```bash theme={null}
ankra cost decisions hold <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions hold 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --note "Wait until the launch is over"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | A note recorded with the decision (up to 2000 characters) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost decisions list

List the organisation's cost proposals, newest first. A right-size ladder's
waves sit under the ladder when it is on the same page.

`--status` is applied by the platform (proposed, approved, held, set\_aside,
running, succeeded, failed, superseded). `--kind` and `--cluster` narrow the page
the platform returned, by the proposal's kind and by the cluster its change
is measured on; -o json returns that narrowed page. The platform serves the
newest 200 by default; `--limit` asks for up to 500.

A running proposal the platform could not check against its operation on this
read is marked as such: it may already have finished.

```bash theme={null}
ankra cost decisions list [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions list
ankra cost decisions list --status approved
ankra cost decisions list --kind right_size_ladder --cluster prod-eu
ankra cost decisions list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only proposals whose change is measured on this cluster (name or id) |
| `--kind` | | Only proposals of this kind, e.g. right\_size, right\_size\_ladder, off\_hours\_schedule, waste\_cleanup |
| `--limit` | `0` | How many of the newest proposals the platform returns (1-500; 200 when omitted) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | | Only proposals in this status: proposed, approved, held, set\_aside, running, succeeded, failed or superseded |

## ankra cost decisions release

Return a held proposal to approved, where it waits for someone to run it
(ankra cost decisions execute). Only a held proposal can be released; any
other status is refused and the proposal stays as it stands.

```bash theme={null}
ankra cost decisions release <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions release 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --note "Launch is over"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | A note recorded with the decision (up to 2000 characters) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost decisions set-aside

Decline a proposal, with your reason (an approved or held one is withdrawn before it runs)

```bash theme={null}
ankra cost decisions set-aside <decision-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost decisions set-aside 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --note "Needed for the launch"
ankra cost decisions set-aside 0b7c4d1e-5f6a-4b8c-9d0e-1f2a3b4c5d6e --note "Needed for the launch" --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | A note recorded with the decision (up to 2000 characters) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra cost events

Read the events that moved the organisation's cost run rate, newest first:
application releases, node-count changes, scheduled and manual stops and
starts, executed cost decisions, clusters entering or leaving pricing, and
resolved cloud waste.

A cluster's run rate is metered hourly, so an event's move is how the
cluster's run rate changed between the priced hour before it and the first
priced hour at least 30 minutes after it. When the event was alone in that
window the move is its own. When several events share the window (a release
and the scale-up it caused) the move is theirs together and each row says
"shared" rather than claim a split. A start alone in a window whose run rate
fell, or a stop alone in one whose run rate rose, did not make that move:
something else did, so its own move is unknown and the row says which way
the run rate went. With no priced hour on one side the move is unknown,
never zero. A coverage event's move is coverage, not spend; a
resolved finding's is its own monthly cost. The platform's note on an event
sits under its row.

When the cluster was not priced for some hours inside an event's window (a
start after a stop it was not metered through, or a metering hour that was
missed), the move cannot be told apart from the cluster leaving or entering
pricing. The row says "unknown (not priced for part of the window)", never
zero.

A kind of event the platform could not read is named above the table: its
events are missing, not quiet. The platform serves at most the newest 500.

`--days` sets the window (at most 34; 30 when omitted). Pass -o json (or yaml)
for the full document.

```bash theme={null}
ankra cost events [flags]
```

**Examples**

```bash theme={null}
ankra cost events
ankra cost events --days 7
ankra cost events -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `--days` | `0` | How many UTC days to cover, ending today (1-34; the platform's default of 30 when omitted) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost ledger

Read the organisation's cost ledger - every cost decision that was approved,
is running or has run, with the monthly saving it was expected to bring and
the saving that was measured.

Seven days after a change runs, Ankra compares the cluster's run rate before
the change with its run rate at day seven, both read from the cluster's
hourly cost snapshots, and records the difference as the measured saving. A
negative measured figure is a measurement too: the run rate rose. A saving
that could not be measured stays unknown, never zero, and the row says why:
the cluster was not priced the same way on both sides of the change
(coverage moved), or there was no snapshot to read. A change undone inside
its window reads reverted. A right-size also carries its usage verification
(in progress, passed, failed with a rollback proposed, or unverified when
metrics were missing), shown under its row.

An approval lasts seven days. A change approved longer ago that never started
reads "approval lapsed": it will not run until it is approved again. A
rollback approved that long ago reads "approved · may have lapsed", because
its approval stands only if it is confirmed to undo its right-size, which
'ankra cost decisions get' tells.

The header totals cover the whole ledger even when the row list stops at the
newest changes: the savings measured this calendar month (UTC), everything
measured so far, and the expected saving of the changes still approved,
running or verifying, which counts as saved only once it is measured. A
lapsed approval, or one that may have lapsed, is not in that total.

Every figure is a monthly run rate in the organisation's display currency.

```bash theme={null}
ankra cost ledger [flags]
```

**Examples**

```bash theme={null}
ankra cost ledger
ankra cost ledger -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost namespaces

Read how a cluster's cost was allocated to each of its namespaces over time,
from the hourly metering (the platform keeps 35 days).

`--days` sets the window (1-35; 30 when omitted) and `--granularity` the bucket:
day (the default) or hour (at most 7 days; 7 when `--days` is omitted).

The metering runs once an hour. A bucket none of whose hours were metered is
unknown for every namespace, drawn '·' and never counted as zero; a namespace
missing from a metered bucket was allocated nothing there, drawn '\_'. The
header says how many buckets were metered. TOTAL sums the metered hours,
LATEST is the current (partial) bucket and PEAK the highest bucket. The trend
is drawn per namespace, scaled to its own peak, for windows of at most 48
buckets. Nothing is extrapolated: these are list-price estimates, not the bill.

The costliest 25 namespaces are listed. Pass -o json (or yaml) for every
namespace and every bucket.

```bash theme={null}
ankra cost namespaces <cluster-name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost namespaces prod-eu
ankra cost namespaces prod-eu --days 7
ankra cost namespaces prod-eu --days 2 --granularity hour
ankra cost namespaces prod-eu -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--days` | `0` | How many days to cover, ending now (1-35, at most 7 by the hour; the platform's default when omitted) |
| `--granularity` | | The bucket size: day (the default) or hour |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost object

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

## ankra cost object application

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

```bash theme={null}
ankra cost object application <application-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost object application 2b8c7c1e-7d6a-4f0e-9d3c-0c5a1b2c3d4e
ankra cost object application 2b8c7c1e-7d6a-4f0e-9d3c-0c5a1b2c3d4e -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost object cluster

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

```bash theme={null}
ankra cost object cluster <cluster-name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost object cluster prod-eu
ankra cost object cluster 1834920e-3001-4157-8938-33c447031033 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost object credential

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

```bash theme={null}
ankra cost object credential <credential-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost object credential 9f1d2e3c-4b5a-4968-8776-655443322110
ankra cost object credential 9f1d2e3c-4b5a-4968-8776-655443322110 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost object namespace

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

```bash theme={null}
ankra cost object namespace <cluster-name-or-id> <namespace> [flags]
```

**Examples**

```bash theme={null}
ankra cost object namespace prod-eu shop
ankra cost object namespace prod-eu shop -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost object project

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

```bash theme={null}
ankra cost object project <project-slug-name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra cost object project platform-team
ankra cost object project 071d45b1-f8fe-4f47-b13a-4f13a01689f1 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost object stack

Read what one object costs now and over the last 30 days, from the same
hourly snapshots the fleet summary reads, so the object's figure and the
fleet's agree.

A cluster and a credential cost their clusters' run rate, idle capacity
included. A namespace, a stack and an application cost their namespaces'
allocations; idle capacity belongs to the cluster, so their idle share is
unknown. Open cloud waste is found per cloud resource, so only a cluster and a
credential carry it.

Every figure the platform cannot give prints as unknown, never as zero. An
object with no priced cluster behind it says why. When coverage is incomplete
the monthly figure is a floor ("at least"), and the clusters that contributed
nothing, or could not price a node or billed resource, are named.

The trend is daily spend, what the object cost each UTC day, not the monthly
run rate. It draws one mark per day, scaled to the object's own peak whole
day: '·' is a day no cluster was metered (unknown), '\_' a metered day that
cost nothing, '…' today, which is still metering, and '≥' a day short of
metered hours, whose figure is only a floor. Today's figure prints on its own
line with the hours it covers so far; it is never the latest figure compared
with whole days. Each day short of metered hours prints on its own line with
the hours it is missing and its floor ("at least").

Pass -o json (or yaml) for the projection exactly as the platform serves it.

```bash theme={null}
ankra cost object stack <cluster-name-or-id> <stack-name> [flags]
```

**Examples**

```bash theme={null}
ankra cost object stack prod-eu observability
ankra cost object stack prod-eu observability -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost reconcile

Set what each cloud credential's provider billed for a month against what
Ankra's metering estimated for the same clusters.

The provider's figures are imported from its billing API (OVHcloud and
UpCloud today) and stay in the provider's own currency; the estimate is
converted into it at the rate shown. Each billed line is placed on a cluster
where the organisation's own records say which (a label Ankra set, a server
it provisioned, a node's provider id, a volume's handle). Tax and credits are
reported apart, since the estimate carries neither.

Nothing unknown reads as agreement. A credential no billing document was
imported for is unknown, not zero; a failed import says why. A difference is
stated only when the provider's figures are final, and then only over the
clusters the metering covered for the hours they existed that month (a missed
hour or so is allowed), never as the accuracy of the whole invoice: the
Difference covers column says how many of the invoice's clusters that is,
the share of the billed amount they hold, and the share of all the named
clusters' hours that was metered for them. When no cluster qualifies, or the
share is too small, no difference is stated and the reason is shown. Billed lines no cluster could
be placed on are counted with their amount.

`--month` reads a UTC calendar month as YYYY-MM (the last closed month when
omitted; the running month is month to date on both sides). Pass -o json (or
yaml) for the full document, including every cluster and unplaced line.

```bash theme={null}
ankra cost reconcile [flags]
```

**Examples**

```bash theme={null}
ankra cost reconcile
ankra cost reconcile --month 2026-08
ankra cost reconcile -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `--month` | | UTC calendar month as YYYY-MM (the last closed month when omitted) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost savings

Read the organisation's savings model - the same recommendations the portal
shows under Cost.

The model analyses the biggest priced clusters (up to the organisation's
analysed-cluster limit, see 'ankra cost settings', and within the platform's
analysis time budget) and proposes the levers that apply to each: right-size idle capacity, reduce run rate no namespace claims,
or an off-hours schedule (weeknights and weekends) for a known non-production
cluster with no enabled power schedule. A cluster can carry several. The total
counts each cluster once, at its best lever, so it is smaller than the sum of
the rows when a cluster has more than one. Each row's Basis says what its
saving rests on: measured (observed usage planned a right-size step), billed
(an off-hours stop on billed compute) or estimate (capacity less requests,
with no usage measured). The total counts only measured and billed levers;
what the estimates add is shown beside it and never counted. Clusters the
model could not analyse are listed rather than treated as having nothing to
save: unpriced (never had a cost snapshot), stale (metering stopped over a
day ago), unreadable on this pass, and offline (the agent has not checked
in, so nothing is recommended for them). The waste summary counts the open
cloud-waste findings.

Every figure is a list-price estimate in the organisation's display currency.

```bash theme={null}
ankra cost savings [flags]
```

**Examples**

```bash theme={null}
ankra cost savings
ankra cost savings --all-projects
ankra cost savings -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost settings

Pricing settings: display currency, effective discount, the network egress estimate and the analysed-cluster limit

## ankra cost settings get

Show the organisation's pricing settings

```bash theme={null}
ankra cost settings get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost settings set

Change one or more pricing settings. Only the flags you pass change; the
other settings keep their current values. The route is organisation-admin
only and every fleet and cluster figure re-prices on the next read.

`--include-egress` is stored, not metered yet: no figure includes network egress
today, whichever way it is set.

`--analysed-cluster-limit` sets how many of the costliest priced clusters the
savings model analyses (1 to 50); `--analysed-cluster-limit` default returns it
to the platform default of 8. Without the flag the limit is not sent, so it
keeps its stored value.

```bash theme={null}
ankra cost settings set [flags]
```

**Examples**

```bash theme={null}
ankra cost settings set --currency eur
ankra cost settings set --discount 12.5
ankra cost settings set --include-egress=false
ankra cost settings set --analysed-cluster-limit 20
ankra cost settings set --analysed-cluster-limit default
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--analysed-cluster-limit` | | How many of the costliest priced clusters the savings model analyses (1-50), or default for the platform's 8 |
| `--currency` | | Display currency: usd, eur or gbp |
| `--discount` | `0` | Effective discount in percent (0-100), applied on top of list prices; 10 means 10% |
| `--include-egress` | `false` | Whether figures should include a network egress estimate once egress is metered (stored, not metered yet: no figure includes it today; `--include-egress=false` clears it) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost summary

Fleet cost rollup: projected month end, month to date, run rate, by provider, by project and costliest clusters

```bash theme={null}
ankra cost summary [flags]
```

**Examples**

```bash theme={null}
ankra cost summary
ankra cost summary --all-projects
ankra cost summary --by credential
ankra cost summary --by project --all-projects
ankra cost summary -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `--by` | | Show only one breakdown: provider, credential or project (default: the full rollup) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra cost trend

Read the organisation's cloud cost run rate per UTC day over every priced
cluster - the line the portal draws under Cost.

A cost snapshot exists only for an hour a cluster was priced, so a cluster
missing from a day was not priced that day: it did not cost nothing. Each day
says how many clusters it covers, and a day with no priced cluster is "not
priced", never zero. A day where some priced clusters were only partly
priced (a node or billed resource with no price) is a floor.

When the set of priced clusters changes - a cluster is created, deleted,
stopped or loses its pricing - the line moves without anything being spent.
Those days are listed apart, with the clusters that entered and left and what
that moved the line by: a coverage move, not a spend move. The last day is
the current run rate, the same figure 'ankra cost summary' shows.

`--days` sets the window (the platform keeps 35 days of snapshots and serves at
most 34; 30 when omitted). Pass -o json (or yaml) for the full document.

```bash theme={null}
ankra cost trend [flags]
```

**Examples**

```bash theme={null}
ankra cost trend
ankra cost trend --days 7
ankra cost trend -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all-projects` | `false` | Read the whole organisation instead of the project you act in |
| `--days` | `0` | How many UTC days to cover, ending today (1-34; the platform's default of 30 when omitted) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra credentials
Source: https://docs.ankra.ai/reference/cli/credentials

Manage credentials

## ankra credentials

Commands to list, view, validate, and delete credentials.

## ankra credentials ankracloud

List and create Ankra Cloud API credentials.

One Ankra Cloud credential serves both self-managed clusters
('ankra cluster ankracloud create') and Ankra Cloud Kubernetes
('ankra cluster managed create `--provider` ankracloud\_k8s').

Ankra Cloud servers take any SSH key credential of the organisation for
`--ssh-key-credential-id`; create one with, for example,
'ankra credentials hetzner ssh-key create `--name` my-key `--generate`'.

## ankra credentials ankracloud create

Create an Ankra Cloud API credential from an API token (act\_...).

The token is never taken from a flag. It is read from stdin with
`--token-stdin`, else from the ANKRA\_CLOUD\_API\_TOKEN environment variable,
else from a masked prompt on a terminal.

`--endpoint` names a non-default Ankra Cloud installation (https only); it
defaults to [https://cloud.ankra.app](https://cloud.ankra.app).

Examples:

```bash theme={null}
ankra credentials ankracloud create --name ankra-cloud
ANKRA_CLOUD_API_TOKEN=act_... ankra credentials ankracloud create --name ankra-cloud
cat token.txt | ankra credentials ankracloud create --name dev --endpoint https://cloud.ankra.dev --token-stdin
```

```bash theme={null}
ankra credentials ankracloud create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--endpoint` | | Ankra Cloud API endpoint, https only (default [https://cloud.ankra.app](https://cloud.ankra.app)) |
| `--name` | | Credential name (required) |
| `--token-stdin` | `false` | Read the API token from stdin |

## ankra credentials ankracloud list

List Ankra Cloud API credentials

```bash theme={null}
ankra credentials ankracloud list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials aws

Connect and list the AWS credentials (access key pairs and assumable roles)
the organisation uses for cost reporting, EKS and self-managed EC2 clusters.

Connecting a role:

1. 'onboarding `--scope` self\_managed' prints the external id the platform
   generated and the CloudFormation launch-stack URL that creates a role
   trusting the platform with that id. Open the URL, launch the stack, and
   copy the role ARN from its outputs.
2. 'create-role `--name` \<n> `--role-arn` \<arn> `--external-id` \<id> `--scope`
   self\_managed' registers the role. The scope must be the one the stack
   was launched for; a cost-scoped role cannot build clusters.

Connecting an access key pair instead: 'create-keys `--name` \<n>
`--access-key-id` \<id>' prompts for the secret access key (masked; pipe it on
stdin in scripts) - it is never taken on the command line.

Once connected, the credential's id is what 'ankra cluster aws create
`--credential-id`' takes; 'list' shows the ids.

SSH key credentials are shared across providers: create one with any
provider's ssh-key group (for example 'ankra credentials hetzner ssh-key
create `--name` ops-key `--generate`') and pass its id as
`--ssh-key-credential-id`.

## ankra credentials aws create-keys

Register an IAM access key pair. The access key id is a flag; the secret
access key is collected via a masked prompt (or read from stdin when piped)
and never taken on the command line, so it stays out of shell history.

Example:

```bash theme={null}
ankra credentials aws create-keys --name aws-prod --access-key-id AKIA... --region eu-north-1
printf '%s' "$AWS_SECRET_ACCESS_KEY" | ankra credentials aws create-keys --name aws-prod --access-key-id AKIA...
```

```bash theme={null}
ankra credentials aws create-keys [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--access-key-id` | | IAM access key id (required); the secret is prompted for |
| `--name` | | Credential name (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | Default AWS region for the credential (server default: us-east-1) |

## ankra credentials aws create-role

Register an IAM role the platform can assume. The role has to trust the
platform's principal with the external id 'onboarding' handed out, which
the launch stack sets up; pass that same external id here. The scope must
match the stack the role was created by: a 'cost' role cannot build
clusters, 'ankra cluster aws create' needs 'provisioning' or 'self\_managed'.

Example:

```bash theme={null}
ankra credentials aws create-role --name aws-prod \
  --role-arn arn:aws:iam::123456789012:role/AnkraSelfManaged \
  --external-id <id from onboarding> --region eu-north-1 --scope self_managed
```

```bash theme={null}
ankra credentials aws create-role [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--external-id` | | External id the role's trust policy requires - the one 'onboarding' printed (required) |
| `--name` | | Credential name (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | Default AWS region for the credential (server default: us-east-1) |
| `--role-arn` | | ARN of the IAM role the platform assumes (required) |
| `--scope` | | Credential scope the role was onboarded under: cost, provisioning or self\_managed (server default: cost) |

## ankra credentials aws list

List AWS credentials

```bash theme={null}
ankra credentials aws list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials aws onboarding

Print what connecting an AWS account through an assumable role needs: the
external id the platform generated for the role's trust policy, the
principal the role has to trust, and the CloudFormation launch-stack URL
that creates the role with exactly that trust and the permissions the scope
needs. Each call generates a fresh external id; the one you launch the
stack with is the one 'create-role `--external-id`' has to be given.

Scopes: 'cost' (read-only billing access, the default), 'provisioning'
(EKS) and 'self\_managed' (EC2 clusters built by 'ankra cluster aws').

The launch-stack URL and trust principal are null when the platform is not
configured for the scope ("configured: no"); the role then has to be
created by hand.

```bash theme={null}
ankra credentials aws onboarding [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--scope` | | Credential scope: cost, provisioning or self\_managed (server default: cost) |

## ankra credentials azure

Commands to list and create Azure service principal credentials used for Azure Kubernetes Service (AKS).

## ankra credentials azure create

Store an Azure service principal for AKS. The client secret is read from
the AZURE\_CLIENT\_SECRET environment variable when set, and prompted
for (masked) otherwise - it is never accepted as a flag.

```bash theme={null}
ankra credentials azure create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--client-id` | | Service principal application (client) ID |
| `--name` | | Credential name |
| `--subscription-id` | | Azure subscription ID the service principal manages |
| `--tenant-id` | | Microsoft Entra tenant ID |

## ankra credentials azure list

List Azure credentials

```bash theme={null}
ankra credentials azure list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials delete

Delete a credential

```bash theme={null}
ankra credentials delete <credential_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra credentials digitalocean

Commands to list and create DigitalOcean API credentials and SSH key credentials.

## ankra credentials digitalocean create

Create an DigitalOcean API credential

```bash theme={null}
ankra credentials digitalocean create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Credential name (required) |

## ankra credentials digitalocean list

List DigitalOcean API credentials

```bash theme={null}
ankra credentials digitalocean list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials digitalocean ssh-key

Manage SSH key credentials

## ankra credentials digitalocean ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials digitalocean ssh-key create --name my-key --generate
ankra credentials digitalocean ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials digitalocean ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials digitalocean ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials digitalocean ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials get

Get details of a credential by its ID or by its name (as shown in `ankra credentials list`).

```bash theme={null}
ankra credentials get <credential_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials hetzner

Commands to list and create Hetzner API credentials and SSH key credentials.

## ankra credentials hetzner create

Create a Hetzner API credential

```bash theme={null}
ankra credentials hetzner create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Credential name (required) |

## ankra credentials hetzner list

List Hetzner API credentials

```bash theme={null}
ankra credentials hetzner list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials hetzner ssh-key

Manage SSH key credentials

## ankra credentials hetzner ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials hetzner ssh-key create --name my-key --generate
ankra credentials hetzner ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials hetzner ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials hetzner ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials hetzner ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials list

List all credentials

```bash theme={null}
ankra credentials list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `asc` | Sort direction with `--sort`: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Filter by provider (e.g., github) |
| `--sort` | | Sort by column: id, name, provider, state, available, repos, last-synced, created (default: server order) |

## ankra credentials morpheus

Commands to list and create HPE Morpheus API credentials and SSH key credentials.

## ankra credentials morpheus create

Create an HPE Morpheus API credential. The API access token is collected
via a masked prompt, never on the command line.

An optional SSH jumphost lets the platform reach a Morpheus API that is
not directly routable; pass `--jumphost-host` together with
`--jumphost-private-key-file` (port defaults to 22, username to root).

Examples:

```bash theme={null}
ankra credentials morpheus create --name my-morpheus --api-url https://morpheus.example
ankra credentials morpheus create --name my-morpheus --api-url https://morpheus.example \
  --jumphost-host 203.0.113.10 --jumphost-private-key-file ~/.ssh/id_ed25519
```

```bash theme={null}
ankra credentials morpheus create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-url` | | HPE Morpheus API URL, e.g. [https://morpheus.example](https://morpheus.example) (required) |
| `--jumphost-host` | | SSH jumphost address used to reach the API |
| `--jumphost-port` | `22` | SSH jumphost port |
| `--jumphost-private-key-file` | | Path to the SSH private key for the jumphost |
| `--jumphost-username` | `root` | SSH jumphost username |
| `--name` | | Credential name (required) |
| `--tls-insecure` | `false` | Skip TLS certificate verification for the API URL |

## ankra credentials morpheus list

List HPE Morpheus API credentials

```bash theme={null}
ankra credentials morpheus list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials morpheus ssh-key

Manage SSH key credentials

## ankra credentials morpheus ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials morpheus ssh-key create --name my-key --generate
ankra credentials morpheus ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials morpheus ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials morpheus ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials morpheus ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials ovh

Commands to list and create OVH API credentials and SSH key credentials.

## ankra credentials ovh create

Create an OVH API credential. You will be prompted for the required secrets.

Generate your OVH API credentials at [https://api.ovh.com/createToken/](https://api.ovh.com/createToken/) with
GET, POST, PUT, DELETE rights on /cloud/project/\* and /cloud/project.

Examples:

```bash theme={null}
ankra credentials ovh create --name my-ovh-cred --project-id <project-id>
```

```bash theme={null}
ankra credentials ovh create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Credential name (required) |
| `--project-id` | | OVH Cloud project ID (required) |

## ankra credentials ovh list

List OVH API credentials

```bash theme={null}
ankra credentials ovh list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials ovh ssh-key

Manage SSH key credentials for OVH

## ankra credentials ovh ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials ovh ssh-key create --name my-key --generate
ankra credentials ovh ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials ovh ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials ovh ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials ovh ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials proxmox

Commands to list and create Proxmox VE API credentials and SSH key credentials.

## ankra credentials proxmox create

Create a Proxmox VE API credential. The API token secret is collected
via a masked prompt, never on the command line.

An optional SSH jumphost lets the platform reach a Proxmox VE API that is
not directly routable; pass `--jumphost-host` together with
`--jumphost-private-key-file` (port defaults to 22, username to root).

Examples:

```bash theme={null}
ankra credentials proxmox create --name my-lab --api-url https://pve.example:8006 --token-id root@pam!ankra
ankra credentials proxmox create --name my-lab --api-url https://pve.example:8006 --token-id root@pam!ankra \
  --jumphost-host 203.0.113.10 --jumphost-private-key-file ~/.ssh/id_ed25519
```

```bash theme={null}
ankra credentials proxmox create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--api-url` | | Proxmox VE API URL, e.g. [https://pve.example:8006](https://pve.example:8006) (required) |
| `--jumphost-host` | | SSH jumphost address used to reach the API |
| `--jumphost-port` | `22` | SSH jumphost port |
| `--jumphost-private-key-file` | | Path to the SSH private key for the jumphost |
| `--jumphost-username` | `root` | SSH jumphost username |
| `--name` | | Credential name (required) |
| `--tls-insecure` | `false` | Skip TLS certificate verification for the API URL |
| `--token-id` | | Proxmox VE API token ID, e.g. root\@pam!ankra (required) |

## ankra credentials proxmox list

List Proxmox VE API credentials

```bash theme={null}
ankra credentials proxmox list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials proxmox ssh-key

Manage SSH key credentials

## ankra credentials proxmox ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials proxmox ssh-key create --name my-key --generate
ankra credentials proxmox ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials proxmox ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials proxmox ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials proxmox ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials proxmox tailscale

Commands to set or clear the Tailscale/Headscale settings a Proxmox VE
credential passes to the VMs it builds.

## ankra credentials proxmox tailscale clear

Remove the Tailscale/Headscale settings from a Proxmox VE credential. VMs
built afterwards no longer join the tailnet; VMs already on it stay there.

```bash theme={null}
ankra credentials proxmox tailscale clear <credential-id>
```

## ankra credentials proxmox tailscale set

Set the Tailscale/Headscale settings a Proxmox VE credential passes to the
VMs it builds. Every VM - the bastion/gateway included - joins the tailnet
through the QEMU guest agent as it is created.

Set this before creating a cluster whose bridge is an SDN vnet: a Proxmox SDN
is node-local, so the tailnet join is the only way the platform can reach
those VMs. The settings apply to VMs built afterwards; VMs that already exist
are not joined retrospectively.

The auth key is collected via a masked prompt, never on the command line.

Examples:

```bash theme={null}
ankra credentials proxmox tailscale set 63fe1425-4ec1-4058-9fef-7e4caec04c79 \
  --login-server https://headscale.example
ankra credentials proxmox tailscale set 63fe1425-4ec1-4058-9fef-7e4caec04c79 \
  --login-server https://headscale.example --advertise-routes 10.20.0.0/16
```

```bash theme={null}
ankra credentials proxmox tailscale set <credential-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-routes` | `false` | Accept subnet routes advertised on the tailnet |
| `--advertise-routes` | | Comma-separated CIDRs the VMs advertise to the tailnet, e.g. 10.20.0.0/16 |
| `--login-server` | | Headscale/Tailscale control server URL, e.g. [https://headscale.example](https://headscale.example) (required) |

## ankra credentials repositories

Read the repositories a GitHub credential's installation can reach right now, against the repositories Ankra needs from it, and report where they disagree.

The accessible list is read live from the provider rather than from the cached count shown in `ankra credentials list`, because that count is only refreshed while the credential reports healthy - so a credential that has stopped being able to read its repository keeps reporting the count it had before it broke.

```bash theme={null}
ankra credentials repositories <credential_id|name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials scaleway

Commands to list and create Scaleway API credentials and SSH key credentials.

## ankra credentials scaleway create

Create a Scaleway API credential from a project-scoped IAM application key.
The secret key is collected via a masked prompt, never on the command line -
Scaleway shows it once, so store it in a secret manager.

The project id is required: it is not derivable from the key, and every
resource Ankra creates is scoped to that one project.

Examples:

```bash theme={null}
ankra credentials scaleway create --name scw-production --project-id 11111111-2222-3333-4444-555555555555 --access-key SCWXXXXXXXXXXXXXXXXX
```

```bash theme={null}
ankra credentials scaleway create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--access-key` | | Scaleway API access key (required) |
| `--name` | | Credential name (required) |
| `--project-id` | | Scaleway Project ID (required) |

## ankra credentials scaleway list

List Scaleway API credentials

```bash theme={null}
ankra credentials scaleway list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials scaleway ssh-key

Manage SSH key credentials

## ankra credentials scaleway ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials scaleway ssh-key create --name my-key --generate
ankra credentials scaleway ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials scaleway ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials scaleway ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials scaleway ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials ssh-key

Create and list SSH key credentials.

An SSH key credential holds one public key and belongs to the whole
organisation: attach it to any cloud cluster with
'ankra cluster ssh-keys set \<cluster> `--ssh-key-credential-ids` \<id>'.
'ankra credentials get \<name>' shows the public key a credential holds and
its SHA256 fingerprint.

## ankra credentials ssh-key create

Create an organisation-wide SSH key credential.

Give the public key inline (`--public-key`), from a file (`--public-key-file`,
for example \~/.ssh/id\_ed25519.pub), or let the platform generate a new
keypair (`--generate`). A generated private key is shown once and never stored
by Ankra, so `--generate` requires `--private-key-file`: the key is written there
with mode 0600, and the command refuses to overwrite an existing file.

A private key passed by mistake (for example \~/.ssh/id\_ed25519 instead of the
.pub file) is refused before anything is sent.

The platform refuses a public key the organisation already holds and names
the credential that holds it.

```bash theme={null}
ankra credentials ssh-key create [flags]
```

**Examples**

```bash theme={null}
ankra credentials ssh-key create --name ops-laptop --public-key-file ~/.ssh/id_ed25519.pub
ankra credentials ssh-key create --name ops-laptop --public-key "ssh-ed25519 AAAA... me@laptop"
ankra credentials ssh-key create --name break-glass --generate --private-key-file ./break-glass.pem
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Have the platform generate a new keypair (requires `--private-key-file`) |
| `--name` | | Credential name (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--private-key-file` | | With `--generate`: write the generated private key here (mode 0600; must not exist) |
| `--public-key` | | The public key itself, e.g. "ssh-ed25519 AAAA... me\@laptop" |
| `--public-key-file` | | Read the public key from this file, e.g. \~/.ssh/id\_ed25519.pub |

## ankra credentials ssh-key list

List the organisation's SSH key credentials.

The platform's list does not include the public key or its fingerprint
today; a Fingerprint column appears when it does. To see which key a
credential holds, run 'ankra credentials get \<name>'.

```bash theme={null}
ankra credentials ssh-key list [flags]
```

**Examples**

```bash theme={null}
ankra credentials ssh-key list
ankra credentials ssh-key list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials upcloud

Commands to list and create UpCloud API credentials and SSH key credentials.

## ankra credentials upcloud create

Create an UpCloud API credential

```bash theme={null}
ankra credentials upcloud create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Credential name (required) |

## ankra credentials upcloud list

List UpCloud API credentials

```bash theme={null}
ankra credentials upcloud list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials upcloud ssh-key

Manage SSH key credentials

## ankra credentials upcloud ssh-key create

Create an SSH key credential. Either provide a public key or generate a new keypair.

Examples:

```bash theme={null}
ankra credentials upcloud ssh-key create --name my-key --generate
ankra credentials upcloud ssh-key create --name my-key --public-key "ssh-ed25519 AAAA..."
```

```bash theme={null}
ankra credentials upcloud ssh-key create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--generate` | `false` | Generate a new SSH keypair |
| `--name` | | Credential name (required) |
| `--public-key` | | SSH public key |

## ankra credentials upcloud ssh-key list

List SSH key credentials

```bash theme={null}
ankra credentials upcloud ssh-key list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra credentials validate

Validate a credential name

```bash theme={null}
ankra credentials validate <name>
```


# ankra delete
Source: https://docs.ankra.ai/reference/cli/delete

Delete a resource

## ankra delete

Delete a resource (e.g., a cluster) from the Ankra platform.

## ankra delete cluster

Delete a cluster by name

```bash theme={null}
ankra delete cluster NAME [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--dry-run` | `false` | Show what would be deleted without calling the API |
| `-f`, `--force` | `false` | Skip confirmation prompt |


# ankra deployments
Source: https://docs.ankra.ai/reference/cli/deployments

Inspect releases deployed to host deploy targets

## ankra deployments

Inspect deployments: each 'kind: deploy' pipeline stage that ran releases
one published artefact digest to every active host target of its environment,
and each deployment records how every host fared.

## ankra deployments get

Show a deployment and how each host target fared

```bash theme={null}
ankra deployments get <id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra deployments list

List deployments, newest first

```bash theme={null}
ankra deployments list [flags]
```

**Examples**

```bash theme={null}
ankra deployments list --environment production
ankra deployments list --repository <pipeline-repository-id> -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cursor` | | Continue from the cursor a previous page printed |
| `--environment` | | Only list deployments to this environment |
| `--limit` | `0` | Deployments per page (default: the platform's page size) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Only list deployments from this pipeline repository id |


# ankra dev
Source: https://docs.ankra.ai/reference/cli/dev

Run this machine's heavy dev commands (test, lint, typecheck) in an Ankra Workspace

## ankra dev

Send the heavy commands of a development loop - go test, go vet, go build,
golangci-lint, pnpm typecheck / test / lint, vitest, tsc `--noEmit`, Playwright
suites - to the checkout's Ankra Workspace instead of running them on this
machine, without changing what you or a coding agent type.

'ankra dev install' puts small shims named go, gofmt, golangci-lint, pnpm, npm
and npx in front of the real tools on PATH. Each shim asks 'ankra' where the
invocation belongs:

```text theme={null}
routed          go test|vet|build (no -o, -c, coverage or profile files),
                golangci-lint run, gofmt -l|-d <paths>, pnpm|npm typecheck,
                test, test:ci, test:unit, test:shard, lint, lint:*,
                format-check, knip, vitest run, tsc --noEmit
routed, changes go generate, go mod tidy|vendor|edit, go get, go fix, go fmt,
applied here    go tool ..., gofmt -w, golangci-lint run --fix, golangci-lint fmt
routed, results Playwright test runs (pnpm|npm test:e2e*, e2e*, [exec]
copied back     playwright, npx playwright test): test-results and reports
local           everything else: go run, go install, go -C, dev servers,
                builds, pnpm install|add, anything interactive (--ui,
                --debug, --headed, codegen), gofmt reading stdin
```

A routed command runs exactly like 'ankra exec': same output, same exit code.
When the checkout has no workspace to use (not a repository connected to Ankra
Pipelines, not logged in, offline) or the workspace could not run it, the real
tool runs on this machine instead, so nothing ever blocks on the platform.

The workspace kind follows the tool: go, gofmt and golangci-lint use the
repository's "go" workspace profile, pnpm, npm and npx its "node" profile and
Playwright runs its "e2e" (or "playwright") profile - when the repository has
that profile. Otherwise they all share its default workspace.

Mode: ANKRA\_EXEC=auto|remote|local for one command, 'ankra dev mode' for the
default. ANKRA\_EXEC\_EXPLAIN=1 \<command> prints route or local and runs nothing.

**Examples**

```bash theme={null}
ankra dev install
ankra dev status
ANKRA_EXEC_EXPLAIN=1 go test ./...
ANKRA_EXEC=local pnpm typecheck
ankra dev mode local
```

## ankra dev install

Write the routing shims for go, gofmt, golangci-lint, pnpm, npm and npx and
put them in front of the real tools.

The shims go to \~/.ankra/dev/shims (`--dir`) and are linked into a directory
that is already on PATH, \~/.local/bin by default (`--link-dir`), so running
sessions and git hooks pick them up at once. When no such directory is on
PATH, or a real tool still comes first, the exact PATH line to add to your
shell profile is printed; no profile is ever edited for you.

Safe to run again (it upgrades the shims in place). A name that is taken by
a real file or by a link to something else is left alone and reported. Links
that point at the earlier claude-tools remote-exec shim are replaced only
with `--replace-legacy`.

`--uninstall` removes exactly what an install created: the links that point at
its shims and the shim files themselves. Commands then run locally again.

Each shim is a few lines of POSIX sh that hand the invocation to
'ankra dev shim'; without an ankra CLI it runs the real tool, so removing the
CLI never breaks go or pnpm. See 'ankra dev `--help`' for what routes.

```bash theme={null}
ankra dev install [flags]
```

**Examples**

```bash theme={null}
ankra dev install
ankra dev install --link-dir ~/bin
ankra dev install --dir ~/.local/share/ankra/shims --link-dir ""
ankra dev install --uninstall
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--dir` | | Directory the shims are written to (default \~/.ankra/dev/shims) |
| `--link-dir` | | Directory already on PATH to link the shims into (default \~/.local/bin when it is on PATH; empty links nothing) |
| `--replace-legacy` | `false` | Replace links that point at the claude-tools remote-exec shim |
| `--uninstall` | `false` | Remove the shims and links a previous install created |

## ankra dev mode

Show the routing mode the dev shims use, or set the default.

```text theme={null}
auto    route when the checkout has a workspace, otherwise run locally (default)
remote  the same, and say so in one line when a routable command runs locally
local   never route: every command runs on this machine
```

The ANKRA\_EXEC environment variable overrides the default for one command. A
default that was never set here is read from \~/.config/ankra-exec/mode, where
the earlier remote-exec scripts kept theirs.

```bash theme={null}
ankra dev mode [auto|remote|local]
```

**Examples**

```bash theme={null}
ankra dev mode
ankra dev mode local
```

## ankra dev status

Show how the dev shims are set up on this machine: the routing mode and where
it comes from, the shim directory, and for each tool whether its shim is
installed and whether it is what the name resolves to first on PATH (a tool
installed in front of it would bypass routing). Reads nothing from the
platform.

```bash theme={null}
ankra dev status [flags]
```

**Examples**

```bash theme={null}
ankra dev status
ankra dev status -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra exec
Source: https://docs.ankra.ai/reference/cli/exec

Run a heavy command for this worktree in its Ankra Workspace, streaming the output back

## ankra exec

Run a command (go test, golangci-lint run, pnpm typecheck, vitest run, a
Playwright suite) for this git worktree in your Ankra Workspace instead of on
this machine. Output streams back live and the exit code is the remote
command's own.

The worktree is sent as it is - tracked files plus untracked files that are
not ignored - as a snapshot commit built in a temporary index (the branch, the
index and the working tree are untouched). Only what the workspace lacks is
uploaded: which commits it holds is recorded under refs/ankra-exec/synced/.
The command runs in the same relative directory, with only an allowlisted
environment forwarded (GOFLAGS, GOMEMLIMIT, NODE\_OPTIONS, TZ, ... and the
names in ANKRA\_EXEC\_FORWARD\_ENV).

The workspace is this checkout's (origin remote, a repository connected to
Ankra Pipelines) of the `--kind` given, brought up on first use.

```text theme={null}
--apply       the command rewrites files (gofmt -w, go generate): its changes
              come back as a patch applied to this worktree. A patch that no
              longer applies is kept under .git/ankra-exec-unapplied-<run>.patch.
--fetch DIR   copy DIR back from the workspace after the run, replacing the
              local one, whatever the exit code (test-results, reports).
--check       exit 0 when this worktree can use a workspace (cheap, cached).
```

Exit codes: the remote command's own when it ran; 196 when it did not run
remotely (and \$ANKRA\_EXEC\_NOTRUN\_FILE is created when set, which is what the
routing shims fall back on); 130 after Ctrl-C, which stops the remote command;
2 for a usage error. Each run appends a line to \~/.claude/logs/ankra-exec.log
(ANKRA\_EXEC\_LOG).

```bash theme={null}
ankra exec [flags] [--] <command> [args...]
```

**Examples**

```bash theme={null}
ankra exec -- go test ./internal/...
ankra exec pnpm typecheck
ankra exec --apply -- gofmt -w ./cmd
ankra exec --kind playwright --fetch test-results -- pnpm test:e2e
ankra exec --check && echo routable
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--apply` | `false` | Apply the changes the command makes in the workspace to this worktree |
| `--check` | `false` | Exit 0 when this worktree can use a workspace, 1 otherwise |
| `--fetch` | `[]` | Copy this directory back from the workspace after the run (repeatable) |
| `--kind` | | Workspace kind (default: the repository's default workspace) |


# ankra helm
Source: https://docs.ankra.ai/reference/cli/helm

Manage Helm registries and credentials

## ankra helm

Commands to manage Helm chart registries and registry credentials.

## ankra helm credentials

Manage Helm registry credentials

## ankra helm credentials create

Create a Helm registry credential with username and password.
The password is prompted interactively, or read from stdin with
`--password-stdin` so scripts and agents can create it without a terminal.

Examples:

```bash theme={null}
ankra helm credentials create --name my-cred --username user
printf '%s' "$REGISTRY_TOKEN" | ankra helm credentials create --name my-cred --username robot --password-stdin
```

```bash theme={null}
ankra helm credentials create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Credential name (required) |
| `--password-stdin` | `false` | Read the password from stdin instead of prompting |
| `--username` | | Registry username (required) |

## ankra helm credentials delete

Delete a Helm registry credential, addressed by its name or by the id
'ankra helm credentials list' prints.

```bash theme={null}
ankra helm credentials delete <name-or-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-f`, `--force` | `false` | Skip confirmation prompt |

## ankra helm credentials get

Show a Helm registry credential by its name or by the id
'ankra helm credentials list' prints. The password is never returned.

```bash theme={null}
ankra helm credentials get <name-or-id>
```

## ankra helm credentials list

List Helm registry credentials

```bash theme={null}
ankra helm credentials list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra helm credentials update

Update a Helm registry credential's username and password, addressed by
its name or by the id 'ankra helm credentials list' prints.
The password is prompted interactively, or read from stdin with
`--password-stdin`.

Examples:

```bash theme={null}
ankra helm credentials update my-cred --username user
printf '%s' "$REGISTRY_TOKEN" | ankra helm credentials update my-cred --username robot --password-stdin
```

```bash theme={null}
ankra helm credentials update <name-or-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--password-stdin` | `false` | Read the password from stdin instead of prompting |
| `--username` | | Registry username (required) |

## ankra helm registries

Manage Helm chart registries

## ankra helm registries create

Create a Helm chart registry from a spec file (-f, JSON or YAML) or
directly from `--name` and `--url`.

In a spec file the registry must be nested under exactly one of
"helm\_oci\_registry" or "helm\_http\_registry":

```json theme={null}
{"spec": {"helm_oci_registry": {"name": "my-charts", "url": "oci://ghcr.io/acme/charts"}}}
{"spec": {"helm_http_registry": {"name": "my-charts", "url": "https://charts.example.com"}}}
```

A flat \{"name": ..., "url": ...} file is accepted and nested automatically,
inferring the registry type from the URL scheme: oci:// creates an OCI
registry, http\:// or https\:// an HTTP chart repository. The flag form uses
the same inference.

Examples:

```bash theme={null}
ankra helm registries create -f registry-spec.json
ankra helm registries create -f registry-spec.yaml
ankra helm registries create --name my-charts --url oci://ghcr.io/acme/charts
ankra helm registries create --name my-charts --url https://charts.example.com \
  --credential-name my-cred --exclude-charts legacy-chart
```

```bash theme={null}
ankra helm registries create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential-name` | | Name of an existing Helm registry credential for private registries |
| `--exclude-charts` | `[]` | Chart name to exclude from indexing (repeatable) |
| `-f`, `--file` | | Path to a registry spec file, JSON or YAML |
| `--name` | | Registry name (with `--url`; alternative to `--file`) |
| `--url` | | Registry URL: oci:// for OCI registries, http\:// or https\:// for HTTP chart repositories |

## ankra helm registries delete

Delete a Helm chart registry

```bash theme={null}
ankra helm registries delete <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-f`, `--force` | `false` | Skip confirmation prompt |

## ankra helm registries get

Get details of a Helm chart registry.

The registry's chart listing is paginated; use `--page`/`--page-size` to select
which chart page the response (and -o json/yaml output) carries.

Examples:

```bash theme={null}
ankra helm registries get bitnami
ankra helm registries get bitnami --page 2 --page-size 100 -o json
```

```bash theme={null}
ankra helm registries get <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Charts page number |
| `--page-size` | `20` | Number of charts per page (max 100) |

## ankra helm registries list

List Helm chart registries.

Results are paginated (20 per page by default). Use `--search` to filter
by name, `--page`/`--page-size` to navigate, or `--all` to fetch every page.

Examples:

```bash theme={null}
ankra helm registries list --search bitnami
ankra helm registries list --page 2 --page-size 100
ankra helm registries list --all
ankra helm registries list --sort-by chart_count --sort-order desc
```

```bash theme={null}
ankra helm registries list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Fetch every page and list all registries (mutually exclusive with `--page`) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `20` | Number of registries per page (max 100) |
| `--search` | | Filter registries by name (case-insensitive substring) |
| `--sort-by` | | Sort column: name, url, created\_at, updated\_at, chart\_count, last\_indexed\_at, is\_global |
| `--sort-order` | | Sort order: asc or desc |

## ankra helm registries sync

Trigger a manual sync of a Helm chart registry

```bash theme={null}
ankra helm registries sync <name>
```

## ankra helm registries sync-jobs

List sync jobs for a Helm chart registry

```bash theme={null}
ankra helm registries sync-jobs <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `25` | Number of jobs per page |

## ankra helm registries update

Update a Helm chart registry

```bash theme={null}
ankra helm registries update <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--read-job-interval` | `0` | Seconds between automatic background syncs (required) |


# CLI Command Reference
Source: https://docs.ankra.ai/reference/cli/index

Every ankra CLI command, flag, and default — generated from the CLI source.

This reference is generated from ankra CLI **v0.57.2**. For installation and authentication, see the [CLI overview](/integrations/ankra-cli).

## Commands

| Command | Description |
| - | - |
| [ankra agents](/reference/cli/agents) | Inspect and control AI agent runs |
| [ankra ai](/reference/cli/ai) | Manage AI provider settings and the model catalog |
| [ankra alerts](/reference/cli/alerts) | Manage alert destinations and notification routes |
| [ankra application](/reference/cli/application) | Manage applications |
| [ankra backup](/reference/cli/backup) | Backup operations |
| [ankra bucket](/reference/cli/bucket) | Manage object storage buckets Ankra creates on your provider credentials |
| [ankra canvas](/reference/cli/canvas) | Publish canvas pages at a public, unguessable URL |
| [ankra charts](/reference/cli/charts) | Browse Helm charts |
| [ankra chat](/reference/cli/chat) | AI-powered chat for troubleshooting and assistance |
| [ankra cluster](/reference/cli/cluster) | Cluster operations |
| [ankra completion](/reference/cli/completion) | Generate or install shell completion scripts |
| [ankra config](/reference/cli/config) | Manage Ankra CLI settings |
| [ankra cost](/reference/cli/cost) | Read cloud cost: the fleet rollup, a cluster's estimate, the savings model, the measured ledger and the pricing settings |
| [ankra credentials](/reference/cli/credentials) | Manage credentials |
| [ankra delete](/reference/cli/delete) | Delete a resource |
| [ankra deployments](/reference/cli/deployments) | Inspect releases deployed to host deploy targets |
| [ankra dev](/reference/cli/dev) | Run this machine's heavy dev commands (test, lint, typecheck) in an Ankra Workspace |
| [ankra exec](/reference/cli/exec) | Run a heavy command for this worktree in its Ankra Workspace, streaming the output back |
| [ankra helm](/reference/cli/helm) | Manage Helm registries and credentials |
| [ankra login](/reference/cli/login) | Authenticate with the Ankra platform |
| [ankra logout](/reference/cli/logout) | Revoke the login token and remove saved credentials |
| [ankra migrate](/reference/cli/migrate) | Move an existing deployment (docker-compose, Dockerfile, running containers) into a cluster Ankra runs |
| [ankra openclaw](/reference/cli/openclaw) | Integrate Ankra with the OpenClaw assistant |
| [ankra org](/reference/cli/org) | Manage organisations |
| [ankra pipeline](/reference/cli/pipeline) | Manage Ankra Pipelines |
| [ankra plugins](/reference/cli/plugins) | List the external plugins that extend this CLI |
| [ankra profile](/reference/cli/profile) | Manage your Ankra profile |
| [ankra project](/reference/cli/project) | Manage the organisation's projects: a team-sized scope for clusters, applications and cost |
| [ankra registry](/reference/cli/registry) | Manage the organisation's Ankra registry |
| [ankra runs](/reference/cli/runs) | Inspect and act on the organisation's runs |
| [ankra secrets](/reference/cli/secrets) | Manage organisation secrets that manifests and addon values reference by sentinel |
| [ankra security](/reference/cli/security) | Read the Security Center: exploited-in-the-wild findings, fleet posture and scanner coverage |
| [ankra services](/reference/cli/services) | Set up, inspect, disconnect and retire managed services (PostgreSQL, Valkey, OpenSearch, ...) |
| [ankra skills](/reference/cli/skills) | Install Ankra Agent Skills into your AI coding assistants |
| [ankra stack-profiles](/reference/cli/stack-profiles) | Manage reusable stack profiles |
| [ankra support](/reference/cli/support) | Create and track Ankra support requests |
| [ankra targets](/reference/cli/targets) | Manage host deploy targets |
| [ankra tickets](/reference/cli/tickets) | Work the AI board: list tickets, read one, comment, move it, answer a decision |
| [ankra tokens](/reference/cli/tokens) | Manage API tokens |
| [ankra upgrade](/reference/cli/upgrade) | Upgrade the Ankra CLI to the latest release |
| [ankra workspace](/reference/cli/workspace) | Manage this checkout's Ankra Workspace, where 'ankra exec' runs commands |

## Global Flags

These flags are accepted by every command:

| Flag | Default | Description |
| - | - | - |
| `--base-url` | | Base URL for the Ankra API (or set ANKRA\_BASE\_URL) |
| `--config` | | config file (default is \$HOME/.ankra.yaml) |
| `--org` | | Organisation name or ID to run this command against, overriding the selected organisation (or set ANKRA\_ORG) |
| `--project` | | Project slug, name or ID to run this command in, overriding the selected project (or set ANKRA\_PROJECT) |
| `--token` | | API token for authentication (or set ANKRA\_API\_TOKEN) |


# ankra login
Source: https://docs.ankra.ai/reference/cli/login

Authenticate with the Ankra platform

## ankra login

Authenticate with the Ankra platform using your browser.

This command will:

1. Open your browser to the Ankra login page
2. After you authenticate, ask you to approve the sign-in in the browser
3. Complete the two-factor challenge in the browser, if your account has one
4. Save your credentials locally so you can use all ankra CLI commands

The whole login happens between your browser and the platform; the CLI
never opens a local network port.

Your credentials will be saved to \~/.ankra.yaml

```bash theme={null}
ankra login [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--audience` | | audience to request for the GitHub ID token (default [https://ankra.ai/oidc/github](https://ankra.ai/oidc/github)) |
| `--github-oidc` | `false` | authenticate with this GitHub Actions job's OIDC identity (needs 'permissions: id-token: write') |
| `--organisation-id` | | organisation whose OIDC trust policies apply (UUID; defaults to `--org` / ANKRA\_ORG) |

## ankra login status

Report the login state without any browser interaction: whether
credentials are configured, the API base URL in use, where the token came
from (the saved config file, the environment, or a flag), and the currently
selected organisation.

Exit code 6 when not logged in or the token is rejected, so scripts can probe
the login state without parsing output.

```bash theme={null}
ankra login status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra logout
Source: https://docs.ankra.ai/reference/cli/logout

Revoke the login token and remove saved credentials

## ankra logout

Revoke the saved login token on the platform and remove the saved
credentials from \~/.ankra.yaml.

Revocation is best-effort: when the platform cannot be reached the local
credentials are still cleared, with a warning that the token may remain
valid until it expires. Use `--local-only` to skip the revocation call
entirely (for example on an air-gapped machine).

```bash theme={null}
ankra logout [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--local-only` | `false` | clear saved credentials without revoking the token on the platform |


# ankra migrate
Source: https://docs.ankra.ai/reference/cli/migrate

Move an existing deployment (docker-compose, Dockerfile, running containers) into a cluster Ankra runs

## ankra migrate

Move an existing deployment into a cluster that Ankra runs.

'ankra migrate up \<dir> `--cluster` \<name>' does the whole journey in one
command: it plans (what will move, how big it is, what stays behind),
converts the deployment into a stack, deploys the stack, dumps every
database from the source and restores it in the cluster. Run it once as a
rehearsal, then again with `--stop-source` for the cutover.

The steps are also separate commands, for when you want to look at each
result: 'convert' writes the stack, 'ankra cluster apply' deploys it,
'export' dumps the data, 'restore' loads it, 'data' does export and
restore together. 'convert', 'detect', 'export' and 'modules' work offline;
'up', 'restore', 'restore-status' and 'data' talk to the platform.

Conversion and export are done by modules. The 'docker' module is built in
and reads docker-compose files, bare Dockerfiles, and the running Docker
daemon. Anyone can add a module for another format by putting an executable
named 'ankra-module-\<name>' on PATH or in \~/.ankra/modules - see
'ankra migrate modules `--help`' for the contract.

## ankra migrate convert

Convert the deployment described in a directory (default: the current one)
into an output directory holding cluster.yaml and the manifests it refers to.

The module is chosen by asking each one whether it recognises the directory;
pass `--module` to choose explicitly. Module-specific settings go through
`--option` key=value, repeated as needed. For the built-in docker module:

```text theme={null}
--option source=compose|dockerfile|daemon   which source to read (default: detected)
--option profiles=app,dns                   compose profiles to include
--option all-profiles=true                  include every compose profile
--option use-environment=true               let your shell satisfy ${VAR} references
--option project=<name>                     compose project, for source=daemon
--option containers=a,b                     specific containers, for source=daemon
--option docker-host=ssh://root@host        a remote daemon, for source=daemon
--option image.<workload>=<registry/repo:tag>  image for a locally built workload
--option ingress.<workload>=<host>          expose a workload through an Ingress
--option cluster-issuer=letsencrypt-prod    request TLS for every Ingress
--option volume-size=20Gi                   size of every PersistentVolumeClaim
--option storage-class=<name>               storageClassName for every claim
```

Read the warnings: they list what the module could not carry over - locally
built images, host directories, unresolved variables, credentials written in
plain text - and each one names the fix.

Then review the output and apply it:

```bash theme={null}
ankra cluster apply -f <out>/cluster.yaml
```

```bash theme={null}
ankra migrate convert [dir] [flags]
```

**Examples**

```bash theme={null}
ankra migrate convert
ankra migrate convert ./app --out ./app-k8s --option profiles=app
ankra migrate convert --option source=daemon --option project=aura-office
ankra migrate convert --option ingress.app=example.com --option cluster-issuer=letsencrypt-prod
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster-name` | | Name for the generated ImportCluster (default: the directory name) |
| `--dry-run` | `false` | Print cluster.yaml and the files that would be written, without writing |
| `--force` | `false` | Overwrite an output directory that is not empty |
| `--module` | | Module to use (default: the most confident detection) |
| `--namespace` | | Namespace for the generated workloads (default: the cluster name) |
| `--option` | `[]` | Module option as key=value (repeatable) |
| `--out` | `ankra-migration` | Output directory |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stack` | | Name for the generated stack (default: the source's own project name) |

## ankra migrate data

Run 'ankra migrate export' on the directory (default: the current one) and
'ankra migrate restore' on the result, back to back: the one command that
moves a Docker deployment's data into the cluster once its workloads are
running there. Every flag of both commands applies. The cluster and the
vault are resolved before anything is dumped, so a wrong target fails fast.

Each dump is a snapshot of a live server. Rehearse while the source is
running, then stop its writers and run it once more for the real cutover.
That second run replaces the rehearsal's data, so it names each database it
may replace with `--overwrite-database`; without it the restore is refused,
which is what keeps a re-run after the cutover from reverting live data.

```bash theme={null}
ankra migrate data [dir] [flags]
```

**Examples**

```bash theme={null}
ankra migrate data ./app --cluster shop --wait
ankra migrate data ./app --option docker-host=ssh://root@203.0.113.7 --option project=aura-office --cluster shop --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster to restore into, by name or id (default: the selected cluster) |
| `--force` | `false` | Overwrite an output directory that is not empty |
| `--module` | | Module to use (default: the most confident detection) |
| `--namespace` | | Namespace the converted workloads run in (default: the directory name, as for convert) |
| `--option` | `[]` | Module option as key=value (repeatable) |
| `--out` | `ankra-migration-data` | Output directory for the export |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--overwrite-database` | `[]` | Database the restore may replace although an earlier restore into this cluster already loaded it - everything written to it since is lost - as \<server>/\<database>, or the database name when only one server has it (repeatable) |
| `--stack` | | Stack the data belongs to (default: derived from the export) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault to upload through, by name or id (default: the organisation's only ready vault) |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra migrate detect

Ask every module whether it recognises the directory (default: the current
one). Use it to see what 'ankra migrate convert' would pick, or why it picks
nothing.

```bash theme={null}
ankra migrate detect [dir] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra migrate export

Dump every database the deployment in a directory (default: the current one)
runs - PostgreSQL and MySQL/MariaDB today - into an output directory, with a
manifest.json that says where each dump restores to: the Service that
'ankra migrate convert' generated for the database and the Secret holding its
password.

The dumps are taken through the docker CLI from the running containers, so
the source must be up. A deployment on another host is reached the way docker
itself reaches it:

```text theme={null}
--option docker-host=ssh://root@203.0.113.7  dump from a remote Docker daemon
--option project=<name>                      the compose project name, when it
                                             differs from the directory name
--option container.<workload>=<name>         dump from a specific container
--option databases.<workload>=a,b            only these databases (default: all)
--option profiles=app,dns                    compose profiles, as for convert
```

Each dump is a snapshot of a live server. Rehearse with the source running,
then stop its writers and export once more right before the final cutover.

The output directory is self-contained: manifest.json describes every
artifact and where it belongs, and SHA256SUMS lets 'sha256sum -c' verify it.
Load it into the cluster with 'ankra migrate restore \<out>'.

```bash theme={null}
ankra migrate export [dir] [flags]
```

**Examples**

```bash theme={null}
ankra migrate export ./app --out ./app-data
ankra migrate export ./app --option docker-host=ssh://root@203.0.113.7 --option project=aura-office
ankra migrate export --option databases.postgres=office,pdns
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Overwrite an output directory that is not empty |
| `--module` | | Module to use (default: the most confident detection) |
| `--namespace` | | Namespace the converted workloads run in (default: the directory name, as for convert) |
| `--option` | `[]` | Module option as key=value (repeatable) |
| `--out` | `ankra-migration-data` | Output directory |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra migrate imports

Every 'ankra migrate restore' (and 'up', and 'data') uploads the export's
dumps into the organisation's backup vault under imports/\<import-id>/ and
keeps them there, so the same upload can be restored again. These verbs
show what a vault holds and remove an import - its dumps in the vault and
the record - once it is no longer needed.

## ankra migrate imports delete

Delete the dumps an import uploaded into the backup vault and hide the
import. An import whose restore is still running is refused: its job is
reading those dumps. Objects the vault cannot be asked to remove are noted
in the audit record; the import is gone either way.

```bash theme={null}
ankra migrate imports delete <import-id> [flags]
```

**Examples**

```bash theme={null}
ankra migrate imports delete 6f1c8e2a-... --yes
ankra migrate imports delete 6f1c8e2a-... --vault backups
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--vault` | | Backup vault the import went through, by name or id (default: the organisation's only ready vault) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra migrate imports list

List the imports a backup vault holds

```bash theme={null}
ankra migrate imports list [flags]
```

**Examples**

```bash theme={null}
ankra migrate imports list
ankra migrate imports list --vault backups -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--vault` | | Backup vault, by name or id (default: the organisation's only ready vault) |

## ankra migrate modules

List every conversion module 'ankra migrate' can use.

Built-in modules ship with the CLI. External modules are executables named
'ankra-module-\<name>' found in \~/.ankra/modules or on PATH, in that order; a
name that collides with a built-in is ignored.

An external module answers three verbs, each with a JSON request on stdin
and a JSON reply on stdout:

```bash theme={null}
ankra-module-<name> describe
    -> {"name":"<name>","version":"1.2","protocol":1,"summary":"...",
        "file_patterns":["Procfile"]}
ankra-module-<name> detect
    <- {"dir":"/path/to/project"}
    -> {"confidence":0.9,"files":["Procfile"],"reason":"Procfile present"}
ankra-module-<name> convert
    <- {"dir":"...","cluster_name":"...","stack_name":"...",
        "namespace":"...","options":{"k":"v"}}
    -> {"cluster":{<ImportCluster>},"files":{"manifests/web.yaml":"..."},
        "warnings":["..."]}
```

"stack\_name" is the name the generated stack must carry; it is absent when
the user left the choice to the module. Confidence runs 0 (not mine) to 1
(certain); reserve 1 for an unambiguous
marker file so a specific module wins over a general one. File paths in the
reply are relative to the output directory and may not escape it. A non-zero
exit fails the verb and the module's stderr is shown as the reason.
Warnings are for anything the module could not translate faithfully: a
partial conversion a person can finish beats none.

A module that lists "export" under "capabilities" in its description also
answers a fourth verb, which backs 'ankra migrate export':

```bash theme={null}
ankra-module-<name> export
    <- {"dir":"...","output_dir":"/abs/path","namespace":"...","options":{}}
    -> {"databases":[{"workload":"db","engine":"postgres","server_version":"17.2",
         "target":{"namespace":"...","host":"db","port":5432,"username":"app",
                   "password_secret":"db-secrets","password_key":"POSTGRES_PASSWORD"},
         "artifacts":[{"path":"db/globals.sql","kind":"globals","format":"sql"},
                      {"path":"db/app.dump","kind":"database","format":"pg_custom","database":"app"}]}],
        "warnings":["..."]}
```

The module writes the dumps under output\_dir and reports their paths; the
CLI measures sizes and checksums itself. Stderr is relayed live while an
export runs, so narrate progress there.

Install a module without touching PATH with 'ankra migrate modules
install \<https-url-or-file>' (validated via its describe verb; `--sha256`
pins the download) and remove it with 'ankra migrate modules uninstall
\<name>'.

The protocol version is 1. The reference implementation is the built-in
'docker' module; a worked external example lives in the CLI repository under
examples/modules/.

```bash theme={null}
ankra migrate modules [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra migrate modules install

Fetch one module executable - from an https URL or a local file - into
\~/.ankra/modules, where 'ankra migrate' discovers it without touching PATH.

Before anything is kept, the module's describe verb is run and its answer
checked: the protocol version, and the name the module calls itself, which
is the name it is installed under. A module runs with your permissions, on
your files and your Docker socket; install only modules you trust, and pass
`--sha256` when the author publishes a checksum.

```bash theme={null}
ankra migrate modules install <url-or-file> [flags]
```

**Examples**

```bash theme={null}
ankra migrate modules install https://github.com/org/x/releases/download/v1/ankra-module-procfile
ankra migrate modules install ./ankra-module-procfile --yes
ankra migrate modules install https://example.com/m --sha256 9f86d081...
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Replace a module of the same name that is already installed |
| `--name` | | Expected module name; refused when the module calls itself something else |
| `--sha256` | | Hex sha256 the download must match |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra migrate modules uninstall

Delete an installed module's executable from \~/.ankra/modules. A module
found on PATH is managed by whatever put it there and is refused with its
location, so nothing outside the CLI's own directory is ever removed.

```bash theme={null}
ankra migrate modules uninstall <name> [flags]
```

**Examples**

```bash theme={null}
ankra migrate modules uninstall procfile --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra migrate restore

Load the databases 'ankra migrate export' dumped into the cluster that now
runs the converted deployment. The export directory's manifest says where
each dump belongs - the Service and Secret 'ankra migrate convert' generated
for the database - so nothing has to be looked up by hand.

The dumps are uploaded straight to the organisation's backup vault with
presigned URLs, the platform verifies every object arrived intact, and the
cluster's agent runs the restore inside the cluster: roles and globals
first, then each database with the engine's own tools. Ankra never holds
the data, and this machine needs neither kubectl nor a database client.

Prerequisites: a backup vault in the organisation ('ankra backup vaults
provision' creates one), the converted stack applied to the cluster
('ankra cluster apply'), and a cluster agent that supports data restores.
The vault is picked automatically when the organisation has exactly one
ready vault; pass `--vault` otherwise.

Pass `--wait` to follow the restore to its end; `--timeout` bounds only that
wait, never the upload. Without `--wait` the command returns once the restore
is running, and 'ankra migrate restore-status \<import-id>' reports progress.

A restore replaces everything in each database it loads. Once a database
in the cluster has been restored into, it may hold writes made since - after
a cutover, the application's live data - so the platform refuses to restore
into it again unless you name it with `--overwrite-database` \<server>/\<database>
(or just the database name when only one server has it). The check runs
before anything is uploaded, and the command names every database it needs.

```bash theme={null}
ankra migrate restore <export-dir> [flags]
```

**Examples**

```bash theme={null}
ankra migrate restore ./app-data --cluster shop --wait
ankra migrate restore ./app-data --cluster shop --vault backups --stack shop
ankra migrate restore ./app-data --cluster shop --overwrite-database db/office --wait
ankra migrate restore ./app-data -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster to restore into, by name or id (default: the selected cluster) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--overwrite-database` | `[]` | Database the restore may replace although an earlier restore into this cluster already loaded it - everything written to it since is lost - as \<server>/\<database>, or the database name when only one server has it (repeatable) |
| `--stack` | | Stack the data belongs to (default: derived from the export) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault to upload through, by name or id (default: the organisation's only ready vault) |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra migrate restore-status

Read an import and the state of its restore jobs, one per database server.
Pass `--wait` to block until the restore has completed or failed.

```bash theme={null}
ankra migrate restore-status <import-id> [flags]
```

**Examples**

```bash theme={null}
ankra migrate restore-status 6f1c8e2a-... --vault backups
ankra migrate restore-status 6f1c8e2a-... --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault the import went through, by name or id (default: the organisation's only ready vault) |
| `--wait` | `false` | Wait for the operation to finish and report success or failure (default: submit and return immediately) |

## ankra migrate up

Move the deployment described in a directory (default: the current one)
into a cluster that Ankra runs, end to end:

1. Plan.    Detect the source, find every database it runs and its size,
   resolve the cluster, the stack and the backup vault, and say
   what the migration will and will not carry. Nothing is
   touched until the plan checks out; `--plan` stops here.
2. Convert. Turn the deployment into a stack (cluster.yaml plus the
   manifests) under \<out>/stack, as 'ankra migrate convert' does.
3. Deploy.  Apply the stack to the cluster and wait for its database
   workloads to be running.
4. Export.  Dump every database from the source, as 'ankra migrate
   export' does, into \<out>/data. With `--stop-source` the
   source's other services are stopped first, so the dump is
   the last word on the data: that is the cutover.
5. Restore. Upload the dumps through the backup vault and load them
   into the cluster, as 'ankra migrate restore' does, and wait.

The command is safe to run more than once, into the same output directory:
the stack is re-applied and the databases are dumped again. A restore
replaces everything in a database, so once the cluster's copy may hold
writes of its own, a re-run restores into it only when you name it with
`--overwrite-database` \<server>/\<database>; otherwise it stops before
uploading and names every such database. Rehearse while the source runs,
then run it once more with `--stop-source` and `--overwrite-database` for each
database when you are ready to switch.
`--timeout` bounds each waiting step (deploy, readiness, restore).

Not carried: files kept in the volumes of non-database workloads, and data
in engines the export does not dump (Redis, MongoDB, search indexes). The
plan names every such item so nothing is left behind unnoticed.

```bash theme={null}
ankra migrate up [dir] [flags]
```

**Examples**

```bash theme={null}
ankra migrate up ./app --cluster shop --plan
ankra migrate up ./app --cluster shop --option ingress.app=shop.example.com --option cluster-issuer=letsencrypt-prod
ankra migrate up ./app --cluster shop --stop-source --overwrite-database db/office --yes
ankra migrate up ./app --cluster shop --option docker-host=ssh://root@203.0.113.7
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster to migrate into, by name or id (default: the selected cluster) |
| `--force` | `false` | Overwrite an output directory that holds files no earlier run of this command wrote |
| `--module` | | Module to use (default: the most confident detection) |
| `--namespace` | | Namespace the workloads run in (default: the stack name) |
| `--no-data` | `false` | Deploy the workloads only; carry no data over |
| `--option` | `[]` | Module option as key=value (repeatable); convert and export options both apply |
| `--out` | `ankra-migration` | Output directory: \<out>/stack for the conversion, \<out>/data for the dumps |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--overwrite-database` | `[]` | Database the restore may replace although an earlier restore into this cluster already loaded it - everything written to it since is lost - as \<server>/\<database>, or the database name when only one server has it (repeatable) |
| `--plan` | `false` | Print the plan and stop; change nothing |
| `--stack` | | Name of the stack on the cluster (default: the name the module gives the source, such as a compose project name, else the directory name) |
| `--stop-source` | `false` | Stop the source's non-database services before the export, so the dump is final (the cutover) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--vault` | | Backup vault the data goes through, by name or id (default: the organisation's only ready vault) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |


# ankra openclaw
Source: https://docs.ankra.ai/reference/cli/openclaw

Integrate Ankra with the OpenClaw assistant

## ankra openclaw

Generate an OpenClaw skill (a SKILL.md) describing the selected
Ankra cluster so OpenClaw can run informed local automations.

## ankra openclaw skill

Generate a SKILL.md for the selected cluster: its name, ID and portal page,
when to hand work to Ankra's AI Agents, and the AI Agents run endpoints.

OpenClaw only loads a skill from a SKILL.md inside its own directory, so the
default output is \$HOME/.openclaw/skills/ankra-\<cluster>/SKILL.md (the
directory is created). `--output` writes to any other path instead.

```bash theme={null}
ankra openclaw skill [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Target cluster name or ID (defaults to the selected cluster) |
| `-o`, `--output` | | Path to write SKILL.md to (default \~/.openclaw/skills/ankra-\<cluster>/SKILL.md) |


# ankra org
Source: https://docs.ankra.ai/reference/cli/org

Manage organisations

## ankra org

Commands to list, switch, create, and manage organisations.

## ankra org access-gateway

Inspect the Cloud proxy's Platform organisation access gate

## ankra org access-gateway get

Show a Cloud DNS zone's access policy

```bash theme={null}
ankra org access-gateway get <zone-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org access-gateway set

Set a Cloud DNS zone's access policy

```bash theme={null}
ankra org access-gateway set <zone-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--mode` | | Access mode: public or organisation |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--role` | `[]` | Allowed organisation role; repeat to allow several (empty means all members) |

## ankra org access-gateway status

Read both clusters live through Ankra. Check the API and relay deployments, broker URL and Secret references without revealing credentials. Redacted Secret digests are cluster-keyed and cannot prove token equality. This does not perform a browser SSO sign-in or read a Cloud DNS zone policy.

```bash theme={null}
ankra org access-gateway status [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--platform-cluster` | | Ankra cluster running the Platform API |
| `--relay-cluster` | | Ankra cluster running the Cloud tunnel relay |

## ankra org access-gateway zones

List Cloud DNS zones in this organisation

```bash theme={null}
ankra org access-gateway zones [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org access-policy

Show the limits every kubectl access grant in this organisation is held
to, an admin's included, or propose a change to them:

```text theme={null}
creator role       what whoever creates or imports a cluster gets on it
ceiling            the most access anyone can be given
elevated lifetime  how long a grant above view may last (also the window
                   'ankra cluster access elevate' may ask for; 4 hours
                   when the policy sets none)
reason from        the lowest role whose grants need a reason
```

The policy is changed by a person, never by a token. 'ankra org
access-policy set' proposes a change and prints a link; an organisation
owner or admin opens the link, signed in, and applies it. The CLI cannot
apply it.

Commands:

```text theme={null}
get              the policy in force, and a pending proposal if there is one
set              propose a change (needs kube_access.manage)
proposals        list proposals
proposal <id>    show one proposal and its apply link
```

Reading requires managing kubectl access, the policy, or holding
break-glass (kube\_access.elevate).

## ankra org access-policy get

Show the organisation's Kubernetes access policy.

The first line says whether the organisation has set a policy at all
(Configured: yes or no); with none, the platform defaults apply. -o json
and -o yaml carry it as is\_configured. When a proposed change is waiting
for an owner or admin, the last line names it and its apply link
(pending\_proposal in -o json and -o yaml).

```bash theme={null}
ankra org access-policy get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org access-policy proposal

Show one proposed change to the organisation's Kubernetes access policy:
who proposed it and why, the policy before and after (changed rows marked
\*), its status, and while it is pending the link an owner or admin applies
it from. The CLI cannot apply it.

```bash theme={null}
ankra org access-policy proposal <id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org access-policy proposals

List proposed changes to the organisation's Kubernetes access policy,
newest first. `--status` pending (the default) shows the one waiting for an
owner or admin; `--status` all shows every proposal, and applied, dismissed,
expired or superseded show those alone.

```bash theme={null}
ankra org access-policy proposals [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | `pending` | pending, applied, dismissed, expired, superseded or all |

## ankra org access-policy set

Propose a change to the organisation's Kubernetes access policy.

Nothing changes when this runs. The platform records the proposal and
answers a link; an organisation owner or admin must open the link, signed
in, and apply it. The CLI cannot apply it: the policy is changed by a
person, never by a token.

Pass only what should change; every other field keeps its live value. The
command prints the policy before and after (changed rows marked \*), the
proposal id, when it expires (7 days) and the apply link. A new proposal
replaces one that is still pending.

```text theme={null}
--creator-role         none, view, edit, admin or cluster-admin
--max-role             view, edit, admin or cluster-admin (the ceiling)
--elevated-max-ttl     how long a grant above view may last: 30m, 4h,
                       7d; none removes the limit
--require-reason-from  view, edit, admin or cluster-admin; none means
                       only break-glass needs a reason
```

`--wait` blocks until the proposal is decided. Exit codes: 0 applied, 4
dismissed by an owner or admin, 1 expired or replaced by a newer
proposal, 5 still pending when `--timeout` ran out (it stays pending and
can still be applied).

Proposing needs kube\_access.manage.

Examples:

```bash theme={null}
ankra org access-policy set --max-role edit --creator-role view --reason "PLA-878: no standing admin"
ankra org access-policy set --elevated-max-ttl 4h --require-reason-from edit --reason "audit finding 12"
ankra org access-policy set --max-role edit --reason "tighten" --wait --timeout 1h
```

```bash theme={null}
ankra org access-policy set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--creator-role` | | Role whoever creates or imports a cluster gets on it: none, view, edit, admin or cluster-admin |
| `--elevated-max-ttl` | | How long a grant above view may last (30m, 4h, 7d), or none for no limit |
| `--max-role` | | The most access anyone can be given (the ceiling): view, edit, admin or cluster-admin |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the policy should change; the owner or admin who applies it reads it (required) |
| `--require-reason-from` | | Lowest role whose grants need a reason: view, edit, admin or cluster-admin, or none |
| `--timeout` | `30m0s` | How long `--wait` waits |
| `--wait` | `false` | Wait until an owner or admin applies or dismisses the proposal |

## ankra org ai-environment

Show or change the organisation's preview settings - where an on-demand
demo or PR preview is published, and how it terminates TLS - and where AI
workspaces and demos run (the staging cluster), how long they live, and the
mode new AI gateway connections start in.

```bash theme={null}
ankra org ai-environment get
ankra org ai-environment set --staging-cluster staging --demo-ttl-hours 48
ankra org ai-environment set --demo-base-domain previews.example.com
ankra org ai-environment set --demo-cert-issuer letsencrypt-prod
ankra org ai-environment set --demo-base-domain ""
```

THE PREVIEW DOMAIN IS NOT THE ROOT DOMAIN

Both settings live on the same portal screen (AI > Settings > Workspaces) and
they are easy to confuse, so:

```text theme={null}
--demo-base-domain    "Preview domain". A wildcard zone YOU point at the
(this command)        staging cluster's ingress. Demos are published at
                      <namespace>.<that domain>. Ankra writes nothing in it
                      and nothing else changes. One field, no blockers.
```

```bash theme={null}
ankra org domain      "Custom Ankra domain". The root every Ankra-generated
                      hostname nests under. Ankra delegates a subzone in it,
                      and the switch is refused while cluster DNS zones or
                      DNS records still live under the old root.
```

If you only want demos on your own domain, this command is the one you want.

PUBLISHING THE RECORDS IS YOURS

Ankra mints each demo a hostname under the preview domain, but it publishes
DNS only inside the subzones it delegates, and the external-dns credential it
provisions for a cluster is scoped to that cluster's own Ankra subzone and
nothing else. Nothing in the platform can create a record on your domain, so
a preview hostname resolves only because you published it - in practice a
wildcard pointing at the staging cluster's ingress.

Without it a demo still deploys and still reports ready, and its URL does not
load. The certificate goes the same way: an HTTP-01 challenge is answered
over the hostname being certified, so if the name does not resolve Let's
Encrypt cannot reach the solver and none is ever issued. An unpublished
preview domain costs you the URL and the TLS together.

'get' relays the platform's verdict, which names the wildcard to create and
the address to point it at when the domain answers nothing. A platform that
reports no verdict at all is called out as that, rather than left to read as
an all-clear. On the Ankra subzone none of this applies: the platform provisions the zone and the in-cluster external-dns
publishes each preview record itself.

TLS ON YOUR OWN PREVIEW DOMAIN

Demos on your own base domain request a per-preview certificate from the
staging cluster's cert-manager issuer, the same way demos on an Ankra subzone
do. Each demo hostname is concrete when the ingress is written, so an HTTP-01
challenge answers for it; no wildcard is involved. Two flags change that:

```text theme={null}
--demo-tls-secret     A secret already holding a certificate for the preview
                      domain. Ankra serves it and requests nothing.
--demo-cert-issuer    A different cert-manager ClusterIssuer to ask, for a
                      cluster whose issuer is not the one Ankra's networking
                      stack installs.
```

A cluster carrying no ACME HTTP-01 issuer cannot be asked for a certificate,
so its previews stay on plain http. 'get' says so when that is the case.

Reading requires organisation membership; changing it requires organisation
admin.

## ankra org ai-environment get

Show the organisation's AI workspace and preview settings

```bash theme={null}
ankra org ai-environment get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org ai-environment set

Change where PR demos are published, and how they terminate TLS.

Only the flags you pass are written; the rest keep their stored values. Pass a
flag with an empty value to clear that field:

```bash theme={null}
ankra org ai-environment set --demo-base-domain previews.example.com
ankra org ai-environment set --demo-cert-issuer letsencrypt-prod
ankra org ai-environment set --demo-cert-issuer ""
```

The same command sets where AI workspaces and demos run and how long they live:

```bash theme={null}
ankra org ai-environment set --staging-cluster staging
ankra org ai-environment set --workspace-ttl-hours 12 --demo-ttl-hours 48
ankra org ai-environment set --demo-ttl-role-cap member=24 --demo-ttl-role-cap operator=96
ankra org ai-environment set --default-gateway-mode ask
```

`--staging-cluster` takes a cluster name or id; an empty value clears it.
`--workspace-ttl-hours` is 1-168, `--demo-ttl-hours` 1-720, and each
`--demo-ttl-role-cap` (admin, operator or member) is the longest demo that role
may ask for, 1-720 hours; roles not named keep their cap.
`--default-gateway-mode` is the mode new AI gateway connections start in: ask
or agent.

`--demo-cert-issuer` only applies alongside a demo base domain: on the Ankra
subzone Ankra picks the issuer itself, from the networking stack it can
verify. Naming one without a base domain is refused rather than stored.

A write that leaves previews on plain http reports it in the output rather
than succeeding silently.

Requires organisation admin.

```bash theme={null}
ankra org ai-environment set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--default-gateway-mode` | | Mode new AI gateway connections start in: ask or agent |
| `--demo-base-domain` | | Wildcard zone demos are published under; empty clears it |
| `--demo-cert-issuer` | | cert-manager ClusterIssuer to ask instead of the cluster's own; empty clears it |
| `--demo-ingress-class` | | Ingress class for demo ingresses; empty clears it |
| `--demo-tls-secret` | | Secret holding a certificate for the preview domain; empty clears it |
| `--demo-ttl-hours` | `0` | How long a PR demo lives by default, in hours (1-720) |
| `--demo-ttl-role-cap` | `[]` | Longest demo a role may ask for, as \<role>=\<hours> (admin, operator or member; 1-720; repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--staging-cluster` | | Cluster name or id AI workspaces and PR demos run on; empty clears it |
| `--workspace-ttl-hours` | `0` | How long an AI workspace lives, in hours (1-168) |

## ankra org ai-review

Configure the organisation's AI code review.

'repos' turns the review on or off for one repository (and sets its model,
draft reviews and review cap); 'related-repos' states which other repositories
a review may read. A connection's own settings stay in the portal's Source
control & AI review settings, and the organisation-wide review model is chosen
with 'ankra ai lanes set pr\_review \<model>'.

## ankra org ai-review related-repos

State which repositories an AI code review may also read.

When a pull request removes something other code may depend on, the review
searches the repositories related to the one under review for code that still
uses it. Applications Ankra installs on the same cluster are related with no
configuration. These commands state the relationships a deploy graph cannot
know about: a client and the API it calls, or a shared library.

```bash theme={null}
ankra org ai-review related-repos list
ankra org ai-review related-repos add my-org/portal my-org/api
ankra org ai-review related-repos remove my-org/portal my-org/api
```

A relationship has no direction: reviews of either repository consider the
other, so there is no mirror to add.

Relationships belong to one GitHub App installation, and both repositories must
be ones that installation can reach. Ankra reads them with the installation's
own token, so a pair naming a repository outside it is refused rather than
stored. Pick the installation with `--credential`, a GitHub credential name or ID
from 'ankra credentials list `--provider` github'. It can be left out when the
organisation has exactly one GitHub App credential.

Listing requires organisation membership; adding and removing require
organisation admin.

## ankra org ai-review related-repos add

Relate two repositories, so an AI code review of either may read the other.

Both are the provider's repository path, owner/name. Ankra checks with GitHub
that the chosen installation reaches both before it stores the pair, and
refuses a pair it could never read.

Requires organisation admin.

```bash theme={null}
ankra org ai-review related-repos add <repository> <related-repository> [flags]
```

**Examples**

```bash theme={null}
ankra org ai-review related-repos add my-org/portal my-org/api
ankra org ai-review related-repos add my-org/web my-org/shared-lib --credential github-app-my-org
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | GitHub App credential (name or ID) whose installation the relationships belong to; defaults to the organisation's only one |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org ai-review related-repos list

List the related repositories stated under a GitHub App installation

```bash theme={null}
ankra org ai-review related-repos list [flags]
```

**Examples**

```bash theme={null}
ankra org ai-review related-repos list
ankra org ai-review related-repos list --credential github-app-my-org -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | GitHub App credential (name or ID) whose installation the relationships belong to; defaults to the organisation's only one |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org ai-review related-repos remove

Stop an AI code review consulting a related repository.

Name the relationship by its ID from 'list', or by its two repositories in
either order. A relationship has no direction, so naming the repositories
removes every stored row relating them, whichever order each was stated in.
Removing a relationship changes nothing about reviews already posted.

`--credential` is only read when the repositories are named, to find the
installation the relationship is stated under.

Requires organisation admin.

```bash theme={null}
ankra org ai-review related-repos remove (<id> | <repository> <related-repository>) [flags]
```

**Examples**

```bash theme={null}
ankra org ai-review related-repos remove my-org/portal my-org/api
ankra org ai-review related-repos remove 0b6f6d1e-6c1d-4f3a-9b43-7f6c2b1e9d10 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | GitHub App credential (name or ID) whose installation the relationships belong to; defaults to the organisation's only one |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra org ai-review repos

Turn the AI code review on or off for one repository.

Each source-control connection (a GitHub App installation, or a GitLab or
Bitbucket credential) has binding-level AI review settings that every
repository on it inherits. A repository rule replaces them for that one
repository: whether the review runs, whether the AI answers @mentions, and
whether pull requests get previews, plus optionally the review model, draft
reviews and the per-pull-request review cap.

```bash theme={null}
ankra org ai-review repos list
ankra org ai-review repos set my-org/my-repo --review --mentions
ankra org ai-review repos unset my-org/my-repo
```

'set' changes only the switches you pass: the rest keep the repository's
current rule, or the connection's settings when it has none. 'unset' removes
the rule, so the repository follows the connection's settings again.

The connection is found from the repository: a GitHub App installation whose
account owns it, or the connection that already holds a rule for it. Pass
`--binding` \<provider>/\<id> (from 'list') when that is ambiguous.

Listing requires organisation membership; set and unset require organisation
admin.

## ankra org ai-review repos list

List the source-control connections, their AI review settings and repository rules

```bash theme={null}
ankra org ai-review repos list [flags]
```

**Examples**

```bash theme={null}
ankra org ai-review repos list
ankra org ai-review repos list --reachable --binding github/12345678
ankra org ai-review repos list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--binding` | | Source-control connection as \<provider>/\<id> from 'list' (default: found from the repository) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reachable` | `false` | Also list the repositories each GitHub App installation reaches |

## ankra org ai-review repos set

Set one repository's AI review rule.

Only the switches you pass change. The others keep the repository's current
rule, or the connection's settings when the repository has no rule yet, so
'set my-org/my-repo `--review`' never switches @mention replies or previews off
by accident.

Requires organisation admin.

```bash theme={null}
ankra org ai-review repos set <owner/repository> [flags]
```

**Examples**

```bash theme={null}
ankra org ai-review repos set my-org/my-repo --review
ankra org ai-review repos set my-org/my-repo --review=false
ankra org ai-review repos set my-org/my-repo --review --mentions --review-drafts --max-reviews-per-pr 3
ankra org ai-review repos set my-group/sub/project --binding gitlab/0b6f6d1e-6c1d-4f3a-9b43-7f6c2b1e9d10 --previews
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--binding` | | Source-control connection as \<provider>/\<id> from 'list' (default: found from the repository) |
| `--max-reviews-per-pr` | `0` | Cap on automatic reviews per pull request (0 = no cap) |
| `--mentions` | `false` | Answer @mentions on this repository (`--mentions=false` to stop) |
| `--model` | | Review model (catalogue key); an empty value inherits the connection's model |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--previews` | `false` | Build pull request previews for this repository (`--previews=false` to stop) |
| `--review` | `false` | Run the AI review on this repository's pull requests (`--review=false` to stop) |
| `--review-drafts` | `false` | Review draft pull requests automatically too (`--review-drafts=false` to skip them) |

## ankra org ai-review repos unset

Remove one repository's AI review rule, so it follows the connection's settings

```bash theme={null}
ankra org ai-review repos unset <owner/repository> [flags]
```

**Examples**

```bash theme={null}
ankra org ai-review repos unset my-org/my-repo
ankra org ai-review repos unset my-org/my-repo --binding github/12345678 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--binding` | | Source-control connection as \<provider>/\<id> from 'list' (default: found from the repository) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra org ai-spend-cap

The organisation's daily AI caps. The money cap bounds what chat may spend
per UTC day; the token caps bound the unattended runs: past the soft cap
every run degrades to the quick tier for the rest of the day, past the hard
cap new runs are refused until midnight UTC.

## ankra org ai-spend-cap set

Set one or more caps. Each flag takes a number or "none" to clear that cap;
a cap whose flag is not passed is left as it is. The hard token cap can
never be set below the soft one.

```bash theme={null}
ankra org ai-spend-cap set --daily-usd 25
ankra org ai-spend-cap set --token-soft-cap 2000000 --token-hard-cap 5000000
ankra org ai-spend-cap set --token-hard-cap none
```

```bash theme={null}
ankra org ai-spend-cap set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--daily-usd` | | daily money cap in USD, or none to clear |
| `--token-hard-cap` | | daily token hard cap (runs are refused past it), or none to clear |
| `--token-soft-cap` | | daily token soft cap (runs degrade to quick past it), or none to clear |

## ankra org ai-spend-cap show

Show the caps and today's spend

```bash theme={null}
ankra org ai-spend-cap show
```

## ankra org assign

Grant a member of the current organisation a role at one scope, through
the platform's RBAC assignments API. The member is named by email or user id
(see 'ankra org members').

`--role` is a built-in role slug (owner, admin, operator, member, viewer) or the
id of an organisation custom role. `--scope` is one of organisation (the
default), cluster, cluster\_group or project; every scope but organisation
needs `--scope-id`:

```text theme={null}
cluster        a cluster name or id
cluster_group  a cluster group id
project        a project slug, name or id (the global --project works too)
```

Examples:

```bash theme={null}
ankra org assign dev@example.com --role viewer
ankra org assign dev@example.com --role operator --scope cluster --scope-id prod-eu
ankra org assign dev@example.com --role admin --scope project --scope-id edge
```

```bash theme={null}
ankra org assign <member> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--role` | | Built-in role slug (owner, admin, operator, member, viewer) or a custom role id |
| `--scope` | `organisation` | Scope of the assignment: organisation, cluster, cluster\_group or project |
| `--scope-id` | | The cluster (name or id), cluster group (id) or project (slug, name or id) the role applies to |

## ankra org ci-settings

Show or change the settings every pipeline in this organisation runs under.

```bash theme={null}
ankra org ci-settings get
ankra org ci-settings set --cluster build-cluster
ankra org ci-settings set --build-fallback platform_builders
```

'get' also shows the pipeline cluster's capacity: how many of its CI slots
are in use, and how many of this organisation's runs and steps are waiting.

The two that decide whether a run can start at all:

```text theme={null}
--cluster           The cluster pipeline steps execute on. Without one,
                    steps have nowhere to run and conclude with a named
                    reason rather than guessing a cluster.
--build-fallback    Whether a 'build' step may fall back to the
                    Ankra-operated build cluster when the pipeline cluster
                    cannot build it. Two things put a build there: the
                    cluster's agent does not run pipeline steps at all, or
                    it does but the node runtime confines the rootless
                    image builder (AppArmor or seccomp, as on k3s and
                    Ubuntu nodes), so the build cannot run in-cluster.
                      platform_builders  keep the fallback available (default)
                      none               refuse the build instead, for
                                         organisations whose source may not
                                         leave their own infrastructure
```

Reading requires organisation membership; changing requires organisation admin.
Both act on the selected organisation; pass the global `--org` flag to read or
change another organisation you administer.

## ankra org ci-settings get

Show the organisation's pipeline settings and capacity

```bash theme={null}
ankra org ci-settings get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org ci-settings pool

Show or change the organisation's CI cluster pool: the clusters its pipeline
runs are spread across.

```bash theme={null}
ankra org ci-settings pool list
ankra org ci-settings pool add ci-hel1-b
ankra org ci-settings pool add ci-upcloud --weight 50
ankra org ci-settings pool remove ci-hel1-b
```

The organisation's pipeline cluster ('ankra org ci-settings set `--cluster`') is
always a member - the primary. Each run is pinned, when its first step is
dispatched, to the least-loaded member whose agent can take a step: steps in
flight over the member's CI workers, scaled by its weight, so a member weighted
200 takes runs until it carries twice the load of a member weighted 100. When
two members are close, the one where the repository ran last wins, because it
holds the repository's warm caches. A run never moves between clusters.

An organisation that lists no members runs every pipeline on its pipeline
cluster exactly as before.

A member must be a cluster of this organisation whose agent runs pipeline
steps (give it workers first with 'ankra cluster agent ci set `--workers` N'),
and a cluster may be in one organisation's pool only.

Reading requires organisation membership; changing requires organisation admin.

## ankra org ci-settings pool add

Add a cluster (name or id) to the organisation's CI pool, or change the
weight of one already in it.

`--weight` is the member's relative share of runs, 1 to 1000. Without it a new
member gets 100 and a member already listed keeps its weight.

Runs queued after this land on the member as soon as it is the least loaded.
Requires organisation admin.

```bash theme={null}
ankra org ci-settings pool add <cluster> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--weight` | `0` | The member's relative share of runs, 1-1000 (100 when new) |

## ankra org ci-settings pool list

List the organisation's CI pool members

```bash theme={null}
ankra org ci-settings pool list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org ci-settings pool remove

Remove a cluster (name or id) from the organisation's CI pool.

New runs stop going to it; runs already pinned to it finish there. Removing the
organisation's pipeline cluster only drops its weight - it stays the primary
member until the pipeline cluster itself is changed. Requires organisation
admin.

```bash theme={null}
ankra org ci-settings pool remove <cluster> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra org ci-settings set

Change the settings every pipeline in this organisation runs under.

Only the flags you pass are written; every other setting keeps its stored
value, so raising one number can never clear the image policy. Clear the
pipeline cluster with an empty value:

```bash theme={null}
ankra org ci-settings set --cluster build-cluster
ankra org ci-settings set --cluster ""
ankra org ci-settings set --build-fallback none
ankra org ci-settings set --allowed-image-prefix ghcr.io/ankraio --allowed-image-prefix docker.io/library
ankra org ci-settings set --allowed-image-prefix ""
ankra org ci-settings set --egress-allowed-cidr 10.0.0.0/8 --egress-allowed-cidr 192.168.10.0/24
ankra org ci-settings set --run-retention-days 180
ankra org ci-settings set --ignore-unfixed=false
ankra org ci-settings set --always-run-stage security-scan --always-run-stage lint
ankra org ci-settings set --full-run-on-default-branch --skip-markers never
```

`--always-run-stage`, `--full-run-on-default-branch` and `--skip-markers` are the
safety net around path filters. An always-run stage (and every stage it
needs) runs whatever its path filters say; a full run on the default branch
sets the filters aside for every push there; `--skip-markers` decides where a
\[skip ci] marker in a pushed commit skips the run: everywhere,
except\_default\_branch (Ankra's default) or never. A merge train car and a tag
push never honour a marker.

`--allowed-image-prefix` and `--egress-allowed-cidr` replace their whole list
rather than adding to it, because a list you can only grow is one you cannot
correct. Passing either once with an empty value clears it: no image
restriction, or no private egress beyond the public internet.

`--ignore-unfixed` is the floor under every pipeline's image gate. It is true by
default, letting a gate stage leave findings with no available fix out of its
verdict; set it to false and every unfixed finding blocks, whatever any
pipeline asks for.

One thing 'get' shows has no flag here and never will:
platform\_builds\_enabled, printed as "Platform builds enabled". It is Ankra's
grant of the platform-builders capability to this organisation, not a setting
of it - a read-only report of a decision only Ankra can take. The endpoint
refuses a body that names it with HTTP 422 ("platform\_builds\_enabled is
Ankra's grant, not a setting of this organisation"), so writing back a 'get'
payload wholesale is refused rather than half-applied. Ask Ankra to enable it.

Requires organisation admin. A member's attempt is refused with exit code 7.

```bash theme={null}
ankra org ci-settings set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allowed-image-prefix` | `[]` | Image prefix a step may name (repeatable); replaces the list, empty clears it |
| `--always-run-stage` | `[]` | Stage that runs whatever its path filters say, with every stage it needs (repeatable); replaces the list, empty clears it |
| `--artifact-retention-days` | `0` | How long a run's artifacts survive |
| `--build-fallback` | | Whether a build may fall back to Ankra's build cluster when the pipeline cluster's agent does not run pipeline steps, or its node runtime confines the rootless builder: platform\_builders or none |
| `--cache-retention-days` | `0` | How long a run's caches survive |
| `--cluster` | | Cluster name or id that pipeline steps run on; empty clears it |
| `--egress-allowed-cidr` | `[]` | Private CIDR pipeline steps may reach (repeatable); replaces the list, empty clears it |
| `--full-run-on-default-branch` | `false` | Run every stage on a push to a repository's default branch, setting path filters aside; =false applies them |
| `--ignore-unfixed` | `true` | Let a gate stage leave findings with no available fix out of its verdict; =false makes every unfixed finding block |
| `--image-gate` | | Which image findings block a publish: app, all or off |
| `--max-parallel-runs` | `0` | How many of this organisation's pipeline runs may be in flight at once |
| `--max-parallel-steps` | `0` | How many steps of one run may be in flight at once |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--run-retention-days` | `0` | How long a repository's concluded run history survives (7-365) |
| `--skip-markers` | | Where a \[skip ci] marker in a pushed commit skips the run: everywhere, except\_default\_branch (default) or never |

## ankra org cloudflare

Manage the domains your Cloudflare account holds, from Ankra.

Connect a scoped Cloudflare API token once, then list your domains and manage
their DNS records. Records are written into your own Cloudflare account and
take effect immediately - there is no pending state to wait for.

```bash theme={null}
ankra org cloudflare connect production
ankra org cloudflare domains
ankra org cloudflare records example.com
ankra org cloudflare add example.com app A 203.0.113.10 --ttl 300
ankra org cloudflare update example.com app 203.0.113.11
ankra org cloudflare delete example.com app
```

Connecting a credential and changing records requires organisation admin.

Ankra needs a scoped API token, never a Global API Key: a key carries every
permission on every zone in your account. Create a token with Zone:Read on the
zones Ankra should see and DNS:Edit on the zones it should write to.

## ankra org cloudflare add

Add a DNS record. The name is a bare label inside the domain, a
fully-qualified name inside it, or '@' for the domain itself.

```bash theme={null}
ankra org cloudflare add example.com app A 203.0.113.10 --ttl 300
ankra org cloudflare add example.com www CNAME app.example.com --proxied
ankra org cloudflare add example.com @ TXT "v=spf1 -all"
ankra org cloudflare add example.com @ MX mail.example.com --priority 10
```

Only A, AAAA and CNAME records can be proxied through Cloudflare. A proxied
record's TTL is managed by Cloudflare, so `--ttl` is refused with `--proxied`.

```bash theme={null}
ankra org cloudflare add <domain> <name> <type> <content> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--comment` | | Comment stored on the record |
| `--credential` | | Which connected Cloudflare credential to use (only needed with several) |
| `--priority` | `0` | Priority for MX and SRV records |
| `--proxied` | `false` | Route the record through Cloudflare's proxy (A, AAAA and CNAME only) |
| `--ttl` | `0` | TTL in seconds (60..86400); omitted means Cloudflare's Auto |

## ankra org cloudflare connect

Connect a scoped Cloudflare API token under the given credential name.

The token is read from the ANKRA\_CLOUDFLARE\_API\_TOKEN environment variable, or
from stdin with `--token-stdin` - never from a flag, so it does not land in your
shell history or the process list. Ankra verifies it with Cloudflare before
storing anything, and refuses a token that reaches no zones: such a token
authenticates perfectly and manages nothing.

Pass `--verify-only` to check a token without storing it.

```bash theme={null}
ANKRA_CLOUDFLARE_API_TOKEN=... ankra org cloudflare connect production
cat token.txt | ankra org cloudflare connect production --token-stdin
ANKRA_CLOUDFLARE_API_TOKEN=... ankra org cloudflare connect --verify-only
```

```bash theme={null}
ankra org cloudflare connect <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--account-id` | | Pin every domain listing to one Cloudflare account (only needed for a token spanning several) |
| `--token-stdin` | `false` | Read the API token from stdin instead of ANKRA\_CLOUDFLARE\_API\_TOKEN |
| `--verify-only` | `false` | Check the token without storing it |

## ankra org cloudflare credentials

List the organisation's connected Cloudflare credentials

```bash theme={null}
ankra org cloudflare credentials [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org cloudflare delete

Delete a DNS record, referenced by its id or by its name. When several
records share a name, disambiguate with `--type`.

The record lives in your own Cloudflare account: Ankra cannot restore it, and
removing a record live traffic depends on takes the hostname down immediately.
The prompt names the record before removing it.

```bash theme={null}
ankra org cloudflare delete <domain> <record> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | Which connected Cloudflare credential to use (only needed with several) |
| `--type` | | Record type to disambiguate a name reference |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra org cloudflare domains

List the domains (zones) the connected Cloudflare credential reaches.

Pass a domain name to resolve just that one, which costs a single lookup
rather than a walk through every domain in the account. An empty result means
Ankra does not reach that domain - either it is not in Cloudflare, or the
connected token is scoped away from it.

```bash theme={null}
ankra org cloudflare domains [name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | Which connected Cloudflare credential to use (only needed with several) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org cloudflare records

List a domain's DNS records. The domain is referenced by name or by its
Cloudflare zone id.

Each record reports whether Ankra created it (MANAGED "ankra") or it was made
elsewhere (MANAGED "external") - which is how to tell a platform-published
record from one written by hand, by Terraform, or by a cluster controller.

```bash theme={null}
ankra org cloudflare records <domain> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--credential` | | Which connected Cloudflare credential to use (only needed with several) |
| `--name` | | Filter to this exact record name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--type` | | Filter to this record type |

## ankra org cloudflare update

Re-point a record at new content. The record is referenced by its id or by
its name; a record's name and type never change - delete and re-add instead.

Only the fields you pass change: an omitted `--ttl`, `--proxied` or `--priority`
keeps the record's current value.

```bash theme={null}
ankra org cloudflare update <domain> <record> <content> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--comment` | | Comment stored on the record |
| `--credential` | | Which connected Cloudflare credential to use (only needed with several) |
| `--priority` | `0` | Priority for MX and SRV records; omitted keeps the current priority |
| `--proxied` | `false` | Route the record through Cloudflare's proxy; omitted keeps the current setting |
| `--ttl` | `0` | TTL in seconds (60..86400); omitted keeps the record's current TTL |
| `--type` | | Record type to disambiguate a name reference |

## ankra org create

Create a new organisation

```bash theme={null}
ankra org create <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--country` | | Country code for the organisation |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org current

Show the currently selected organisation

```bash theme={null}
ankra org current [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org custom-dns-zones

Declare, list, and withdraw the DNS zones every cluster in the organisation
serves with one of the organisation's own DNS credentials - an external-dns
webhook credential or a Cloudflare credential - alongside the generated domain
Ankra serves itself.

A zone declared here behaves like the generated domain: every cluster in the
organisation, the ones that exist and the ones created later, gets its own
external-dns for it, rendered and reconciled by Ankra with a DNS credential
you supply ('ankra org dns credentials', or 'ankra org cloudflare connect' for
a Cloudflare zone). Each cluster's controller is pinned
to exactly the zone with its own record ownership, so it can never fight
Ankra's controller, another cluster's, or records you publish yourself.

'ankra cluster custom-dns-zones' declares the same thing for one cluster. A
cluster's own declaration of a zone wins over the organisation's on that
cluster, which is how one cluster serves the zone with a different
credential.

Withdrawing a zone removes the controllers Ankra rendered from every cluster
that inherited it; clusters that declared the zone themselves keep theirs,
and the zone's records are yours and are left untouched.

## ankra org custom-dns-zones add

Declare a zone every cluster in the organisation serves, with the DNS
credential that can publish into it. Ankra renders an external-dns for the
zone on each cluster on the next reconciler pass, and on every cluster
created afterwards without further declaration.

Use `--cloudflare-credential` for a zone hosted at Cloudflare: the zone is
published by external-dns's native Cloudflare provider through that
organisation Cloudflare credential, checked with Cloudflare before anything is
stored, and every cluster's controller runs upsert-only - it never changes or
deletes a record someone else made.

Refused when the zone is not a domain name, when the organisation has no
credential of that name (or, with `--cloudflare-credential`, no Cloudflare
credential of that name), when a Cloudflare token cannot reach the zone or may
not edit its DNS, or when the zone overlaps the domain Ankra already serves
for the organisation - that would put a second controller on names Ankra's own
external-dns publishes.

```bash theme={null}
ankra org custom-dns-zones add [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cloudflare-credential` | | Name of the organisation Cloudflare credential that publishes into the zone with the native Cloudflare provider |
| `--credential` | | Name of the organisation credential that publishes into the zone, of whichever kind (this or `--cloudflare-credential` is required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--zone` | | Zone to declare for every cluster, e.g. example.com (required) |

## ankra org custom-dns-zones list

List the zones declared for every cluster in the organisation

```bash theme={null}
ankra org custom-dns-zones list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org custom-dns-zones remove

Withdraw an organisation-wide zone. Ankra removes the controllers it rendered
from every cluster that inherited the zone on the next reconciler pass;
clusters that declared the zone themselves keep theirs. The zone's records
are yours and are left untouched.

```bash theme={null}
ankra org custom-dns-zones remove [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--zone` | | Zone to withdraw (required) |

## ankra org dns

Manage CNAME/A/AAAA/TXT records under the organisation's own delegated DNS
zone (shown by 'ankra org dns zone'). Records are reconciled asynchronously:
a new or edited record starts in state pending and turns active once it is
published to the authoritative nameservers.

```bash theme={null}
ankra org dns zone
ankra org dns zones
ankra org dns list
ankra org dns add chat CNAME lb-1234.example-lb.com --ttl 300
ankra org dns update chat target.example.com
ankra org dns delete chat
```

Creating, editing, and deleting records requires organisation admin.

## ankra org dns add

Add a record to the organisation's delegated zone. The name is the label
inside the zone (the zone fqdn is appended server-side), the type is one of
CNAME, A, AAAA, or TXT, and the content is the record target. An AAAA
record takes an IPv6 address and needs the zone on Ankra Cloud.

```bash theme={null}
ankra org dns add chat CNAME lb-1234.example-lb.com --ttl 300
ankra org dns add app A 203.0.113.10
ankra org dns add relay AAAA 2001:db8::10
ankra org dns add eu TXT "v=spf1 ~all"
```

```bash theme={null}
ankra org dns add <name> <type> <content> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--ttl` | `0` | TTL in seconds (30..86400); omitted means Auto |

## ankra org dns credentials

Store and list the organisation's DNS webhook credentials - the ones the
custom DNS zone lane serves your own zones with ('ankra org
custom-dns-zones' for every cluster in the organisation, 'ankra cluster
custom-dns-zones' for one cluster).

The webhook provider URL embeds the provider token, so it is written to the
platform's secret store on create and never returned by any read: 'list'
shows names and ids only. Re-creating a credential under the same name
re-points every cluster binding that names it, which is how a rotated token
rolls out.

## ankra org dns credentials create

Store a DNS webhook credential. The webhook provider URL is the external-dns
webhook endpoint including its token; it goes to the platform's secret store
and is never echoed back.

Creating a credential under a name that already exists replaces its stored
URL, which re-points every cluster binding that names it - the rotation path.

```bash theme={null}
ankra org dns credentials create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Credential name, referenced by 'org custom-dns-zones add `--credential`' and 'cluster custom-dns-zones add `--credential`' (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--webhook-provider-url` | | external-dns webhook endpoint including its token (required) |

## ankra org dns credentials list

List the organisation's DNS credentials

```bash theme={null}
ankra org dns credentials list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org dns delete

Delete a record, referenced by its id or by its name (the label or the
full fqdn). When several records share a name, disambiguate with `--type`.

```bash theme={null}
ankra org dns delete <record> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--type` | | Record type (CNAME, A, AAAA, TXT) to disambiguate a name reference |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra org dns list

List the organisation's DNS records

```bash theme={null}
ankra org dns list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org dns update

Re-point a record at new content. The record is referenced by its id or
by its name (the label or the full fqdn); the name and type of a record
never change - delete and re-add to rename. Pass `--ttl` to change the ttl at
the same time.

```bash theme={null}
ankra org dns update <record> <content> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--ttl` | `0` | TTL in seconds (30..86400); omitted keeps the record's current ttl |
| `--type` | | Record type (CNAME, A, AAAA, TXT) to disambiguate a name reference |

## ankra org dns zone

Show the organisation's delegated DNS zone

```bash theme={null}
ankra org dns zone [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org dns zones

List every cluster-level DNS zone in the organisation: the cluster, the
zone fqdn, and its reconciliation state.

This is the inventory a root-domain switch has to clear. Switching the
organisation's Ankra root domain ('ankra org domain set') is refused while any
cluster zone still lives under the old root, and a zone is removed with
'ankra cluster domain \<cluster> `--remove`'.

Listing is a read: it never creates a zone.

```bash theme={null}
ankra org dns zones [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org domain

Show or register the root domain every Ankra-generated hostname in the
organisation nests under - the organisation's delegated DNS zone, its clusters'
domains, and the preview hostnames built from them.

Unset, the platform default (ankra.cc) applies. Registering your own domain
requires it to be delegated to the Ankra nameservers first; the write is
refused otherwise, naming the nameservers to point at.

```bash theme={null}
ankra org domain get
ankra org domain set example.com
ankra org domain set --default
```

This is the same setting the portal writes at AI > Settings > Workspaces
("Custom Ankra domain").

The SECOND domain field on that screen, "Preview domain", is a different
setting: it decides only where PR demos and on-demand previews are published,
it changes nothing else, and it is not gated by the guard below. If previews
on your own domain are what you are after, you want
'ankra org ai-environment set `--demo-base-domain`', not this command.

Changing the root domain is refused while cluster DNS zones or DNS records
still live under the old root; the refusal lists exactly what to remove. Use
'ankra org dns zones' and 'ankra org dns list' to inventory them, and
'ankra cluster domain \<cluster> `--remove`' and 'ankra org dns delete \<record>'
to clear them. Ankra re-creates the organisation zone under the new domain
automatically once the switch is accepted.

WHAT ANKRA TOUCHES IN YOUR DOMAIN

The domain you register becomes the organisation's zone itself: Ankra adopts
it as the apex rather than carving a subzone out of it, and each cluster
gets its own \<cluster\_short\_id>.\<domain> subzone under it. The external-dns
Ankra installs on every cluster in the organisation holds a token pinned to
the whole domain, so an Ingress on any hostname under it - a top-level name
like app.\<domain> included - is published by the cluster serving it, with no
credential of your own. Records you already publish that no cluster's
Ingress claims are left alone: each cluster's external-dns owns only the
records it created.

That is the lane for a domain hosted in Ankra's own DNS account. For a zone
you hold in your own provider account, declare it with your own credential
instead ('ankra org dns credentials create' + 'ankra org custom-dns-zones
add').

WHAT A SWITCH DOES NOT CHANGE

Zone labels are derived from the organisation and cluster ids, so they are the
same under any root. A cluster keeps its label across a switch, and with it
the `--txt-owner-id` of the external-dns Ankra manages for it and any GitOps
path built from it. A switch never re-stamps an owner id and never leaves an
external-dns pointed at a TXT registry it no longer matches.

Reading requires organisation membership; changing it requires organisation
admin.

## ankra org domain get

Show the organisation's Ankra root domain

```bash theme={null}
ankra org domain get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org domain set

Register the organisation's own root domain, or clear it back to the
platform default with `--default`.

The domain must be a bare domain you own (example.com, not sub.example.com or
a domain under the platform default), already delegated to the Ankra
nameservers.

Existing records in that domain are preserved. Ankra creates one subzone,
\<org\_short\_id>.\<domain>, and confines itself to it - nothing at the apex or
under any other name is read, written or deleted, by this command or by
anything Ankra runs afterwards.

The switch is refused while cluster DNS zones or DNS records still live under
the old root; the refusal lists them, and says which of them you clear
yourself and which are published by something you have to remove first:

```text theme={null}
Cluster domains  ankra cluster domain <cluster> --remove
                 Each such cluster runs Ankra's external-dns against its own
                 zone. The removal is held once it completes, so external-dns
                 cannot re-create the zone while you finish the switch.
                 Restore it afterwards with --enable, which re-mints the zone
                 under the new root and keeps the cluster's label and
                 external-dns --txt-owner-id exactly as they were.
Your DNS records ankra org dns delete <record>
Ankra's records  These are reconciled, so deleting one lasts until the lane
                 that owns it runs again. The refusal names what publishes
                 them - today, a playground, cleared with
                 'ankra cluster playground destroy <cluster_id>'.
```

Clearing every blocker by hand is the current sequence. See
'ankra org domain `--help`' for what a switch does and does not change.

```bash theme={null}
ankra org domain set [domain] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--default` | `false` | Clear the custom domain and follow the platform default |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org invite

Invite a user by email to the current organisation.

Valid roles: owner, admin, operator, member (default), viewer, read-only,
project. owner/operator alias onto admin/member on the invite; once the member
has joined, grant the exact role at any scope with 'ankra org assign'. Run
'ankra org roles' for the full list.

`--role` project invites a project-only member: they reach the one project
named with the global `--project` (slug, name or id) and nothing else of the
organisation, with the project role `--project-role` (admin, operator, member
or viewer; member by default). Needs projects enabled for the organisation.

Examples:

```bash theme={null}
ankra org invite user@example.com
ankra org invite user@example.com --role admin
ankra org invite user@example.com --role viewer
ankra org invite contractor@example.com --role project --project edge --project-role operator
```

```bash theme={null}
ankra org invite <email> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--project-role` | `member` | With `--role` project: the role inside the project (admin, operator, member or viewer) |
| `--role` | `member` | Role for the invited user (owner, admin, operator, member, viewer, read-only, project) |

## ankra org limits

Some limits cannot be raised self-serve: the playground memory budget, the free monthly AI allowance and the registry storage limit. Requests go to the Ankra team for review; you are notified when one is decided.

## ankra org limits list

Show your latest limit-increase request per kind

```bash theme={null}
ankra org limits list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org limits request

Request a higher limit, reviewed by the Ankra team.

```text theme={null}
--kind playground-memory --gb <n>    a bigger playground memory budget
--kind ai-tokens --usd <n>           a bigger free monthly AI allowance
--kind registry-storage --gb <n>     a bigger registry storage limit, in GiB per registry project
                                     (same as 'ankra registry storage request')
```

```bash theme={null}
ankra org limits request [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--gb` | `0` | requested playground memory budget in GB, or registry storage limit in GiB per registry project |
| `--justification` | | a sentence or two on why (required) |
| `--kind` | | playground-memory, ai-tokens or registry-storage |
| `--usd` | `0` | requested monthly AI allowance, in USD |

## ankra org list

List all organisations you belong to

```bash theme={null}
ankra org list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `asc` | Sort direction with `--sort`: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--sort` | | Sort by column: id, name, slug, role, status (default: server order) |

## ankra org mcp-servers

Register, inspect, and gate external MCP (Model Context Protocol) tool
servers for the organisation. A registered server's tools become callable
from agent runs, subject to the server's permission tier, its allowed-tools
list, and per-tool role grants.

Credential headers are never stored or sent in plaintext: 'add
`--secret-header`' first stores the value in an organisation secret slot and
registers the server with the slot's "\$\{SECRET\_SLOT:\<id>}" sentinel - the
backend refuses plaintext values under sensitive-looking header names. The
curated adapter catalog ('ankra org mcp-servers catalog') documents the
exact header value form each provider expects (for example "Bearer \<token>",
or "Sentry-Bearer \<token>" for Sentry).

```bash theme={null}
ankra org mcp-servers catalog
ankra org mcp-servers add sentry --adapter sentry --url https://mcp.sentry.dev/mcp \
  --secret-header Authorization
ankra org mcp-servers grant sentry get_issue --role member
ankra org mcp-servers health sentry
```

Managing MCP servers requires organisation admin rights.

## ankra org mcp-servers add

Register an MCP server so agent runs can call its tools.

Credential headers come in two forms. `--header` sends a plaintext header (for
non-secret values only; the backend refuses plaintext under
sensitive-looking names). `--secret-header` stores the value in an
organisation secret slot labeled "\<server-name> \<Header>" and registers the
server with the slot's "\$\{SECRET\_SLOT:\<id>}" sentinel, so the secret never
lands in the server record. Prefer passing only the header name
(`--secret-header` Authorization) to be prompted with hidden input, or pipe
the value on stdin - the inline Key=Value form works but leaves the secret
in your shell history and visible in process listings. The catalog
documents the exact value form each curated provider expects. If a later
step of the registration fails, slots already created for it are removed
again so no secret material is left orphaned.

With `--adapter` and no `--allowed-tools`, the allowed-tools list is seeded from
the adapter's recommended tools. Servers start enabled unless `--disabled` is
given, and `--cluster` (repeatable) restricts which clusters' agent runs may
use the server.

`--url` is required for every transport. For `--transport` stdio the platform
stores the value as the server's identifier only and never dials it, so a
descriptive placeholder such as cmd://\<binary-name> is expected there.

```bash theme={null}
ankra org mcp-servers add <name> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers add sentry --adapter sentry --url https://mcp.sentry.dev/mcp \
  --secret-header Authorization
ankra org mcp-servers add internal-tools --url https://mcp.example.internal/sse \
  --transport sse --tier read_write --allowed-tools search_docs,create_ticket
ankra org mcp-servers add staging-only --url https://mcp.example.com/mcp \
  --cluster 6f1f9aca-2c3d-4e5f-8a9b-0c1d2e3f4a5b --disabled
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--adapter` | | Curated adapter key from 'catalog' to pair with (seeds allowed tools) |
| `--allowed-tools` | `[]` | Comma-separated tool allow-list (default: the adapter's recommended tools when `--adapter` is set) |
| `--cluster` | `[]` | Cluster UUID allowed to use the server (repeatable; default: all clusters) |
| `--description` | | Optional human-readable description |
| `--disabled` | `false` | Register the server disabled |
| `--header` | `[]` | Plaintext header as Key=Value (repeatable; non-secret values only) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--secret-header` | `[]` | Secret header stored in a secret slot and referenced by sentinel (repeatable). Prefer Key alone (hidden prompt, or one line per header on piped stdin); the inline Key=Value form lands in shell history and process listings |
| `--tier` | | Permission tier: read\_only or read\_write (default: backend's read\_only) |
| `--transport` | `http` | Transport: http, sse, or stdio |
| `--url` | | The MCP server endpoint URL (required for every transport; with `--transport` stdio it is stored as the server's identifier and never dialed, so use a placeholder like cmd://\<binary-name>) |

## ankra org mcp-servers catalog

List the curated adapters: known MCP server products with their
transport, URL placeholder, expected credential headers (including the exact
value form, e.g. "Bearer \<token>"), and a recommended tool allow-list.

Passing an adapter key to 'add `--adapter`' records the pairing and seeds the
server's allowed tools from the adapter's recommendation when `--allowed-tools`
is not given.

```bash theme={null}
ankra org mcp-servers catalog [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers catalog
ankra org mcp-servers catalog -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org mcp-servers disable

Disable a server without deleting it. Its configuration and grants are
kept, but agent runs cannot call its tools until it is enabled again.

```bash theme={null}
ankra org mcp-servers disable <name-or-id>
```

**Examples**

```bash theme={null}
ankra org mcp-servers disable sentry
```

## ankra org mcp-servers enable

Enable a server so agent runs can call its granted tools again.

```bash theme={null}
ankra org mcp-servers enable <name-or-id>
```

**Examples**

```bash theme={null}
ankra org mcp-servers enable sentry
```

## ankra org mcp-servers get

Show a server's full configuration: URL, transport, permission tier,
allowed tools, configured env/header names (values are never echoed back -
credential values live in secret slots), cluster allow-list, and connection
state.

```bash theme={null}
ankra org mcp-servers get <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers get sentry
ankra org mcp-servers get sentry -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org mcp-servers grant

Grant a tool to an organisation role, making it callable from agent
runs started by members holding that role. Grants are additive; revoke one
with 'revoke-grant'.

```bash theme={null}
ankra org mcp-servers grant <name-or-id> <tool_name> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers grant sentry get_issue
ankra org mcp-servers grant sentry create_ticket --role admin
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--role` | `member` | Organisation role the tool is granted to |

## ankra org mcp-servers grants

List which tools are granted to which organisation roles on a server.
A tool with no grant is not callable from agent runs regardless of the
allowed-tools list.

```bash theme={null}
ankra org mcp-servers grants <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers grants sentry
ankra org mcp-servers grants sentry -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org mcp-servers health

Probe the server: whether the platform can reach it and which of its
tools the current configuration allows. The raw probe document is available
with -o json.

```bash theme={null}
ankra org mcp-servers health <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers health sentry
ankra org mcp-servers health sentry -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org mcp-servers list

List every registered MCP server with its transport, enabled state,
permission tier, adapter pairing, grant count, and last connection error.

```bash theme={null}
ankra org mcp-servers list [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers list
ankra org mcp-servers list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org mcp-servers remove

Delete a server and its tool grants. Agent runs can no longer call its
tools; secret slots its headers referenced are not deleted (remove those
separately if nothing else uses them).

```bash theme={null}
ankra org mcp-servers remove <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers remove sentry
ankra org mcp-servers remove sentry --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra org mcp-servers revoke-grant

Revoke one tool's grant from one role. Other roles' grants on the same
tool are untouched.

```bash theme={null}
ankra org mcp-servers revoke-grant <name-or-id> <tool_name> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers revoke-grant sentry get_issue
ankra org mcp-servers revoke-grant sentry create_ticket --role admin
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--role` | `member` | Organisation role the grant is revoked from |

## ankra org mcp-servers tools

List the server's tool inventory as the platform sees it, after the
allowed-tools filter. The raw inventory document is available with -o json.

```bash theme={null}
ankra org mcp-servers tools <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers tools sentry
ankra org mcp-servers tools sentry -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org mcp-servers update

Apply a partial update to a server. Only the flags you pass change;
everything else keeps its current value. `--clear-allowed-tools` removes the
allow-list entirely (every tool the permission tier allows becomes
callable), and is mutually exclusive with `--allowed-tools`. Use the separate
'enable' and 'disable' subcommands to flip the server on or off.

```bash theme={null}
ankra org mcp-servers update <name-or-id> [flags]
```

**Examples**

```bash theme={null}
ankra org mcp-servers update sentry --url https://mcp.sentry.dev/mcp
ankra org mcp-servers update sentry --tier read_write --description "Sentry issue triage"
ankra org mcp-servers update sentry --clear-allowed-tools
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allowed-tools` | `[]` | Replace the tool allow-list (comma-separated) |
| `--clear-allowed-tools` | `false` | Remove the tool allow-list entirely |
| `--description` | | New description |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--tier` | | New permission tier: read\_only or read\_write |
| `--url` | | New endpoint URL |

## ankra org member

Manage one member of the current organisation

## ankra org member role

Change the organisation role of a member (named by email or user id).

Valid roles: owner, admin, operator, member, viewer, read-only, project.
`--role` project makes the member project-only: they reach the one project
named with the global `--project` (slug, name or id) and nothing else of the
organisation, with the project role `--project-role` (admin, operator, member
or viewer; member by default). Needs projects enabled for the organisation.

Examples:

```bash theme={null}
ankra org member role dev@example.com --role viewer
ankra org member role contractor@example.com --role project --project edge --project-role operator
```

```bash theme={null}
ankra org member role <member> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--project-role` | `member` | With `--role` project: the role inside the project (admin, operator, member or viewer) |
| `--role` | | New role (owner, admin, operator, member, viewer, read-only, project) |

## ankra org members

List members of an organisation

```bash theme={null}
ankra org members [org_id] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org oidc-trust

Manage the GitHub Actions OIDC trust policies of the organisation.

A policy names ONE repository exactly, by owner/name AND by the numeric
repository and owner ids (which GitHub never reuses, so a renamed or
re-created repository cannot inherit it), and optionally a ref, an
environment and a workflow. A job from that repository then runs

```bash theme={null}
ankra login --github-oidc --organisation-id <id>
```

and receives a token that lasts minutes, carries the policy's role, and is
never stored in a GitHub secret. Pull request runs are refused unless the
policy opts in with `--allow-pull-request`; pull\_request\_target never is.

Find the ids with:  gh api repos/OWNER/NAME `--jq '.id, .owner.id'`

Requires organisation admin.

## ankra org oidc-trust create

Create a trust policy.

```bash theme={null}
ankra org oidc-trust create deploy-main \
  --repository acme/deploy --repository-id 123456 --repository-owner-id 7890 \
  --ref refs/heads/main --environment production --role operator
```

`--repository`, `--repository-id`, `--repository-owner-id` and `--role` are required.
No value accepts wildcards. `--ttl` is how long the minted token lives
(default 15m, at most 1h). Prefer pinning an `--environment` that requires
reviewers in GitHub.

```bash theme={null}
ankra org oidc-trust create <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allow-pull-request` | `false` | also trust pull\_request runs (never fork-safe; default off) |
| `--environment` | | exact GitHub environment the job must use |
| `--job-workflow-ref` | | exact workflow ref, e.g. OWNER/NAME/.github/workflows/ci.yml\@refs/heads/main |
| `--ref` | | exact ref the job must run on, e.g. refs/heads/main |
| `--repository` | | GitHub repository as OWNER/NAME (exact) |
| `--repository-id` | `0` | numeric GitHub repository id (gh api repos/OWNER/NAME `--jq` .id) |
| `--repository-owner-id` | `0` | numeric GitHub owner id (gh api repos/OWNER/NAME `--jq` .owner.id) |
| `--role` | | role the minted token carries (e.g. operator) |
| `--scope` | `[]` | optional token scope restriction (repeatable) |
| `--ttl` | `15m0s` | lifetime of the minted token (1m to 1h) |

## ankra org oidc-trust delete

Delete a trust policy and revoke the tokens it minted

```bash theme={null}
ankra org oidc-trust delete <policy-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-y`, `--yes` | `false` | skip the confirmation prompt |

## ankra org oidc-trust list

List the organisation's OIDC trust policies

```bash theme={null}
ankra org oidc-trust list
```

## ankra org provenance

Verified provenance at deploy: a pipeline's publish step signs a statement about
every image it publishes, and a deploy can refuse an image that is not attested.
This command holds the organisation default and the signing keys.

```bash theme={null}
ankra org provenance get                    the default mode
ankra org provenance set --mode warn        change it
ankra org provenance keys                   the signing keys
ankra org provenance rotate                 start a new key generation
ankra org provenance revoke <key-id>        stop trusting a key
```

An application follows this default unless it has its own mode
('ankra application provenance').

Modes:

```text theme={null}
off      nothing is checked at deploy, exactly as before
warn     every image in the application's registry is checked; the deploy
         goes ahead whatever the result, and an image that is not verified
         files a finding on the application's installation
enforce  the deploy is refused unless every image in the application's
         registry carries a valid attestation from this organisation's
         pipeline, and each verified image is pinned to its digest
```

## ankra org provenance get

Show the organisation's default provenance mode

```bash theme={null}
ankra org provenance get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org provenance keys

List the organisation's provenance signing keys, oldest generation first. Only
public keys are shown.

```text theme={null}
active    signs new attestations and verifies
trusted   an earlier generation: verifies, no longer signs
revoked   nothing it signed verifies any more
```

`--public-keys` prints the PEM of every key that is not revoked, one block per
key. 'cosign verify-attestation `--key`' takes one key per check, so with more than
one trusted key save each block to its own file and try them in turn.

```bash theme={null}
ankra org provenance keys [flags]
```

**Examples**

```bash theme={null}
ankra org provenance keys
ankra org provenance keys --public-keys > provenance.pub
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--public-keys` | `false` | Print the PEM of every key that is not revoked instead of the table |

## ankra org provenance revoke

Revoke a key. Nothing it signed verifies any more: an application under enforce
refuses those images until they are published again, which includes rolling back
to them. Revoking the active key makes the next publish create a successor.
Needs the security.manage permission. Use 'ankra org provenance keys' for key ids.

```bash theme={null}
ankra org provenance revoke <key-id> [flags]
```

**Examples**

```bash theme={null}
ankra org provenance revoke <key-id> --reason "key exposed in a build log"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the key is revoked (recorded in the audit log, at most 500 characters) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra org provenance rotate

Create the next key generation. The next publish signs with it. Earlier
generations stay trusted, so images already published keep verifying. At most
16 generations exist per organisation. Needs the security.manage permission.

```bash theme={null}
ankra org provenance rotate [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org provenance set

Set the mode every application without its own mode runs under, or remove the
default with `--clear`. Needs the security.manage permission.

Modes:

```text theme={null}
off      nothing is checked at deploy, exactly as before
warn     every image in the application's registry is checked; the deploy
         goes ahead whatever the result, and an image that is not verified
         files a finding on the application's installation
enforce  the deploy is refused unless every image in the application's
         registry carries a valid attestation from this organisation's
         pipeline, and each verified image is pinned to its digest
```

Start with warn. enforce as an organisation default refuses the deploys of every
application that follows it and whose images are not attested; under enforce,
versions published before an application's first attested publish cannot be
deployed or rolled back to. This command asks before turning enforce on (`--yes`
skips the question).

```bash theme={null}
ankra org provenance set --mode off|warn|enforce [flags]
```

**Examples**

```bash theme={null}
ankra org provenance set --mode warn
ankra org provenance set --clear
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--clear` | `false` | Remove the organisation default |
| `--mode` | | Provenance mode: off, warn or enforce |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation asked before turning enforce on |

## ankra org remove

Remove a user from the current organisation

```bash theme={null}
ankra org remove <user_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-f`, `--force` | `false` | Skip confirmation prompt |

## ankra org roles

List the assignable organisation roles

```bash theme={null}
ankra org roles
```

## ankra org switch

Switch to a different organisation by slug, name, or ID

```bash theme={null}
ankra org switch <organisation>
```

## ankra org terminal-session

Every pod terminal session opened through Ankra is recorded. The
open\_pod\_terminal audit row carries the session id in its details; this
command prints the session's facts and, with `--transcript`, replays the
recorded output as text (everything the container printed, in order).
`--show-input` lists what was typed as well, with control characters named.

Needs the audit.read permission. A recording contains whatever the shell
printed, secrets included.

Examples:

```bash theme={null}
ankra org terminal-session 11111111-2222-4333-8444-555555555555
ankra org terminal-session 11111111-2222-4333-8444-555555555555 --transcript
ankra org terminal-session 11111111-2222-4333-8444-555555555555 --transcript -o json
```

```bash theme={null}
ankra org terminal-session <session_id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--show-input` | `false` | List what was typed, with control characters named |
| `--transcript` | `false` | Print the recorded output |

## ankra org usage

Show everything the organisation used of Ankra over a window of days, per
meter and period: worker vCPU-hours, ordered playground time, managed service
instance time and storage, hosted logs and metrics accepted, and AI requests
and tokens.

The window defaults to the current month to date. `--period` picks this month
or last month; `--from` and `--to` (exclusive) pick any stretch of UTC days up to
93 days long, within the 400 days usage is kept. `--granularity` splits it
into calendar months or days, and `--group-by` splits each meter by cluster,
by the application a managed service serves, or by managed service instance.
`--group-by` project answers a different question: how the organisation's
worker vCPU-hours over the window split across its projects (showback -
billing stays one invoice per organisation). Only the window applies to it.

Each line says how completely it was measured. A quantity is exact when
every hour of the period was measured, a lower bound (shown as >=) when
some were not or are still being counted, and 'not measured' when none was,
for instance a service whose cluster was offline throughout. Not measured is
never 0; in -o json the quantity is null.

Each line also says what it costs. 'included (pilot)' means Ankra publishes
no rate and charges nothing for it: managed services and hosted logs and
metrics during the pilot. A priced line shows the amount in EUR the
published rate makes of it, as the invoice will. A line no rate applies to
says why, for instance that AI usage has no per-unit rate.

Grouped by application, a service that serves several applications is
counted under each of them (marked shared), so application lines do not add
up to the organisation's total. Grouped by meter, every meter answers every
period; grouped otherwise, a group that used none of a meter in a fully
measured period has no line.

-o table (the default) shows quantities in units a person reads (GB, hours,
thousands separators). -o json and -o yaml carry the platform's own report:
raw quantities with their unit, and null where nothing was measured.

Needs the billing.read permission.

```bash theme={null}
ankra org usage [flags]
```

**Examples**

```bash theme={null}
ankra org usage
ankra org usage --period last-month
ankra org usage --from 2026-09-01 --to 2026-10-01 --granularity day
ankra org usage --group-by cluster
ankra org usage --group-by application -o json
ankra org usage --group-by project --period last-month
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from` | | First UTC day to read, YYYY-MM-DD (default: the first day of this month) |
| `--granularity` | `month` | Period length of each line: month or day |
| `--group-by` | `meter` | Split each meter by: meter, cluster, application or instance; project splits worker vCPU-hours by project |
| `-o`, `--output` | `table` | Output format: table, json or yaml |
| `--period` | | A ready-made window: this-month or last-month (instead of `--from`/`--to`) |
| `--to` | | The day after the last UTC day to read, YYYY-MM-DD (default: tomorrow, so today is included) |

## ankra org variables

Manage organisation-scoped variables that are available to every cluster
in the organisation as template substitutions in stack manifests and addon
values.

```bash theme={null}
ankra org variables list
ankra org variables get DB_HOST
ankra org variables set DB_HOST db.prod.example.com --description "Primary database"
ankra org variables set API_TOKEN - --secret < token.txt
ankra org variables reveal API_TOKEN
ankra org variables delete DB_HOST
```

A secret variable's value is never shown by list or get; reveal reads it back
for members who can change variables, and every reveal is audited.

Variable resolution order at deploy time is stack > cluster > organisation; a
more specific scope overrides a less specific one.

## ankra org variables delete

Delete an organisation variable

```bash theme={null}
ankra org variables delete <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra org variables get

Get a single organisation variable

```bash theme={null}
ankra org variables get <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org variables list

List all organisation variables

```bash theme={null}
ankra org variables list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org variables reveal

Print one organisation variable's stored value. This is the only way to
read back a secret variable: list and get never show it.

Revealing needs permission to change variables, and every reveal is recorded
in the organisation's audit log. The value is printed on its own line, so it
can be captured in a script:

```bash theme={null}
TOKEN="$(ankra org variables reveal API_TOKEN)"
```

```bash theme={null}
ankra org variables reveal <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra org variables set

Create or update an organisation variable (upsert). If the variable
does not exist it is created; otherwise its value (and description, when
supplied) is updated.

`--secret` creates the variable as a secret, or marks an existing one secret:
list and get then never show its value, and only "ankra org variables reveal"
reads it back. `--secret=false` makes an existing secret variable plain again.
Without the flag an update keeps the variable's current setting.

The value can also be read from stdin by passing "-":

```bash theme={null}
echo "secret-token" | ankra org variables set API_TOKEN - --secret
```

Leave the value out to change only an existing variable's secret setting or
description, keeping its value:

```bash theme={null}
ankra org variables set API_TOKEN --secret
```

```bash theme={null}
ankra org variables set <name> [value] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--description` | | Optional human-readable description |
| `--secret` | `false` | Store the value as a secret that list and get never show (`--secret=false` makes an existing secret plain) |


# ankra pipeline
Source: https://docs.ankra.ai/reference/cli/pipeline

Manage Ankra Pipelines

## ankra pipeline

Manage Ankra Pipelines: in-cluster CI/CD runs, the pipeline definition of
record, and its cron schedules.

Every command addresses one pipeline with exactly one of:

```text theme={null}
--application <name-or-id>   the application the pipeline builds and deploys
--repository <repository-id> the pipeline repository directly
```

There is no lookup route yet for a repository by "owner/name" - only by-id and
by-application addressing exist - so `--repository` takes the repository's id
(for example, the "repository.id" field 'ankra pipeline definition get'
returns). Most invocations want `--application` instead.

A run is addressed by its id (the RUN ID column, not the "run\_id" field a
JSON/YAML response also carries - that second field is the cross-lifecycle
umbrella run this pipeline run belongs to, useful for correlating with
'ankra cluster operations', but not what these commands accept).
'pipeline get' can also select a run by its commit, branch or trigger, and
wait on or watch it - see 'ankra pipeline get `--help`'.

'pipeline definitions get|approve' are the one exception: they address a
stored definition directly by its own id and take neither flag - see
'ankra pipeline definitions `--help`'.

## ankra pipeline artifacts

List a pipeline run's stored step logs and declared artifacts, oldest
first.

Every step's complete output is archived as a "step\_log" artifact once the
step concludes ('ankra pipeline logs' reads that one automatically for a
concluded step); anything a stage's own "artifacts:" block declared shows up
as "artifact". An empty first page means the run genuinely has nothing
stored yet - no step has concluded, or the organisation has no ready backup
vault to store into. STATUS is "pending" until the upload is confirmed,
"uploaded" once "artifacts download" can fetch it, "failed" if it never
arrived (see the row's error), or "expired" once retention removed it.

The listing is paged: it prints one server page (50 rows by default) and
says when there is another, which `--cursor` reads. So a run with more
artifacts than one page shows its oldest first, and the list is complete
only once no further page is offered.

```bash theme={null}
ankra pipeline artifacts <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--cursor` | | Page cursor from a previous listing's next\_cursor |
| `--limit` | `0` | Maximum number of artifacts to return (server default 50, max 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline artifacts download

Download a stored artifact, following the platform's redirect to its
presigned storage URL and streaming it to disk.

```bash theme={null}
ankra pipeline artifacts download <artifact-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--out` | | Local file to write the artifact to (default: the artifact id, in the current directory) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline branches

List a pipeline's branches, one row per ref, with the newest run on each.

The repository's default branch leads the listing; everything else follows by
most recent activity. Each row carries the latest run on the ref, the outcome
of the run concluded before it (PREVIOUS), how many runs the ref has ever had,
and how many of those a newer commit superseded - a run cancelled because
something newer took its concurrency group, which is history rather than a
failure to look at.

Branches with no run in the last fourteen days are hidden; `--all` shows them.
The count of what was hidden is printed after the table.

STATUS is the latest run's lifecycle - queued, running or concluded - and
OUTCOME its verdict, which is empty until the run concludes. 'ankra pipeline
get `--help`' documents both fields.

```bash theme={null}
ankra pipeline branches [flags]
```

**Examples**

```bash theme={null}
# Where does every branch of the application you are standing in stand
ankra pipeline branches

# Include the branches nothing has run on for a fortnight
ankra pipeline branches --application orders-api --all

# The branch whose latest run did not succeed, for a script
ankra pipeline branches --application orders-api -o json | jq '.branches[] | select(.latest_run.outcome != "success")'
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Include branches with no run in the last 14 days, which are hidden by default |
| `--application` | | Application name or id whose pipeline to act on |
| `--cursor` | | Page cursor from a previous listing's next\_cursor |
| `--limit` | `0` | Maximum number of branches to return (server default 20, max 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline cancel

Cancel a pipeline run that has not concluded.

A run that had started stops its main and on\_failure stages, then runs its
finally stages before it concludes cancelled. While they run the run reads
"running" and "cancelling". A run that never started concludes at once.

`--force` skips the finally stages: the run concludes cancelled at once. On a
run that is already cancelling it stops the finally stages still running.
Cancelling such a run again without `--force` is refused.

```bash theme={null}
ankra pipeline cancel <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--force` | `false` | Skip the run's finally stages, or stop them if the run is already cancelling |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline definition

Manage the pipeline definition of record

## ankra pipeline definition get

Show the pipeline definition of record

```bash theme={null}
ankra pipeline definition get [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline definition put

Store a generated pipeline definition server-side, replacing the
repository's definition of record. Requires the pipelines.manage permission.

This does not touch the repository's committed .ankra/pipeline.yaml: a
committed file still wins for logic per the DescriptorOfRecord contract,
so 'put' is for a repository whose pipeline Ankra generates and stores rather
than one you author and commit yourself.

```bash theme={null}
ankra pipeline definition put <file> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline definitions

Read and grant an administrator's approval of one stored pipeline
definition's protected sections: the authority-bearing parts of a pipeline -
permissions, credentials, secrets scope, network tier, image policy,
runs\_on, environment gates and more - that a pull request may add logic
around but never grant itself ("logic is open, authority is closed").

These two commands address one stored definition directly by its own id,
unlike 'pipeline definition get|put' which read and write the definition of
record for a repository or application. There is no lookup or listing route
for a definition's id. The one to approve is the repository's current
default-branch definition: 'ankra pipeline get \<run>' prints its approve
command on a run that is not approved ("approve\_definition\_id" in -o json),
and a pull request's status comment names it too. The run's
"authority\_definition\_id" is the definition its trusted authority came from:
useful to inspect with 'get', but not the one to approve - it is normally
already approved, and 'approve' refuses it.

An approval applies to runs planned after it; a run keeps the authority it
was planned under.

## ankra pipeline definitions approve

Record an administrator's approval of one stored pipeline definition's
protected sections. Requires the pipelines.manage permission and a human
actor - a service-account or agent token is refused.

Approving grants whatever permissions, credentials, secrets scope, network
tier and other protected sections the definition declares - inspect them
first with 'ankra pipeline definitions get \<id>' if you have not, since this
command prints only the protected-sections hash, not their content. Confirms
before approving; `--yes` skips the prompt for scripted use.

Only the repository's CURRENT default-branch definition can be approved, and
only once: approving a definition the default branch has since moved past,
or one already approved, answers a 409 this command prints verbatim rather
than treating as success. A definition recorded before its protected
sections were ever hashed answers the same 409.

```bash theme={null}
ankra pipeline definitions approve <id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra pipeline definitions get

Show one pipeline definition's protected-authority approval state

```bash theme={null}
ankra pipeline definitions get <id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra pipeline findings

List a pipeline run's persisted scan findings.

Findings are recorded once a "scan" step has concluded for the run's own
commit; a run with no scan step, or one still running, answers an empty
list rather than an error. The default table sorts worst severity first and
groups by tool, so the findings most likely to block a "gate" step are
always at the top; -o json/yaml prints every field the server carries,
including each finding's tool-specific detail.

```bash theme={null}
ankra pipeline findings <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline get

Show a pipeline run's detail - or wait for it to conclude, or watch it.

Name the run by its id, or select it by what you know about it. Push and pull
request runs are started by the webhook, so a CI job or an agent usually knows
the commit rather than the run id: `--head-sha`, `--branch` and `--trigger` narrow
the pipeline's runs the way 'pipeline list' filters them. Exactly one match is
that run; when several match, `--latest` takes the newest, and without it the
command lists them instead of guessing. `--latest` on its own is the pipeline's
newest run.

`--wait` blocks until the run concludes, then prints its final detail. `--watch`
prints every state change of the run and of each of its steps as it is seen,
until the run concludes; with -o json each change is one JSON object on its
own line, carrying the run or step as the platform answered it. `--timeout`
bounds either one; without it they wait as long as the run takes. When a
selection matches no run yet, `--wait` and `--watch` wait for one to appear - the
webhook that creates it can land a moment after you ask - for up to
`--timeout`, or ten minutes when no `--timeout` is set.

Exit codes: 0 when the run succeeded; 1 when it concluded any other way, or
the platform could not be read; 2 when a selection matches several runs and
`--latest` was not given; 3 when nothing matches; 5 when `--timeout` ran out or,
with `--exit-code`, when the run has not concluded yet. Without `--wait`, `--watch`
or `--exit-code` the command exits 0 whatever the run's outcome, as it always
has.

Status and outcome (-o json): 'status' is the lifecycle, never the verdict.
A run's status is queued, running or concluded; a step's is blocked (waiting
on its dependencies), pending (ready, not yet claimed), running or concluded.
How the work ended is the separate 'outcome' field, which is null until the
status is concluded and then always one of: success, failure (the work
itself failed), cancelled, timed\_out, skipped (it never ran - a dependency
did not succeed, a condition or the trigger filter excluded it) or
infra\_error (Ankra failed, not the work). The same two fields with the same
vocabulary sit on the run and on each step, mirroring GitHub Actions'
status/conclusion split - so a monitor that filters on status finds every
finished run under concluded, and must read outcome for whether it passed.
The human-readable Status line and STATUS column print the outcome once
there is one and the status until then, with a glyph that says which:
✓ success, ✗ failure / timed\_out / infra\_error, ⊘ cancelled, ○ skipped, and
⟳ only for a run or step that has not concluded (○ for a blocked step).

Superseded runs: a run cancelled because a NEWER run took its concurrency
group reads 'superseded' rather than 'cancelled' - on the Status line, in
the STATUS column, on the last line of `--watch` and in the conclusion `--wait`
reports - and 'pipeline get' names the run that took its place. Nobody
stopped that run, and the run worth looking at is the newer one. Only the
word differs: `--wait`, `--watch` and `--exit-code` exit 1 for a superseded run as
for any cancelled one. In -o json the fields are 'error\_class'
("superseded"), 'superseded\_by\_run\_id' and 'superseded\_by\_run\_number';
'outcome' stays "cancelled", so a script filtering on outcome alone still
finds these runs and must read the class to tell them from a run somebody
cancelled.

Cancelled runs (-o json 'cancelled\_by', 'cancel\_reason', 'cancelled\_at';
the Cancelled line): who stopped a run, why and when. 'cancelled\_by' is the actor
in the same form 'requested\_by' uses - "user:\<id>" for a cancel pressed in
the portal, the CLI or the API, "github:\<login>" for the Cancel action on a
pull request's check run, "concurrency:\<run id>" for a supersession,
"merge\_train:\<entry id>" for the merge train - and 'cancel\_reason' is one of:

```text theme={null}
user_requested       somebody cancelled it in the portal, the CLI or the API
source_control       the Cancel action on its check run
superseded           a newer run took its concurrency group
queued_replaced      a newer commit replaced it before it started
merge_train          the merge train no longer needed this change tested
pull_request_closed  its pull request merged or closed (no actor)
step_cancelled       nobody cancelled it: a step was stopped where it ran,
                     for example when the cluster's agent shut down, and
                     the Error line carries that step's sentence (no actor)
```

superseded, queued\_replaced and merge\_train runs read 'superseded' (above).
A reason this list does not name yet is printed as it is.
All three fields are null for a run nobody cancelled and for one cancelled
before Ankra recorded this, which is "not recorded", never "the platform
did it".

Steps that never started (error\_class "never\_scheduled"): a step whose time
ran out while no node had room for what it requests concludes timed\_out,
and so does its run, but nothing ran. The Class line says so; free capacity
on the cluster, add a node, or lower the stage's resources, then rerun.

Authority (-o json 'authority\_state', the Authority line): the protected
authority the run executed under. 'approved' - the default branch's
definition declares no protected section, or an administrator approved
exactly what it declares, and the head changes nothing. 'unapproved' - a run
of the default branch whose definition changed authority no administrator
has approved yet; it executes under the last approved authority, or under
none when nothing was ever approved. 'changed\_on\_head' - a run of another
branch or a pull request whose definition declares different authority; it
executes under the default branch's, and the head's change is ignored and
reported. null - the planner never resolved authority for this run: it is
still queued, it concluded skipped because its trigger filter excluded every
stage before planning, or it was planned before authority was recorded.
null is "not recorded", never "no authority".

```bash theme={null}
ankra pipeline get [run] [flags]
```

**Examples**

```bash theme={null}
# Block until the pull request run for a commit concludes; exit non-zero unless it passed
ankra pipeline get --head-sha "$(git rev-parse HEAD)" --trigger pull_request --latest --wait --timeout 45m

# React to each run and step state change as it happens, one JSON object per line
ankra pipeline get <run-id> --watch -o json

# Read a run once and branch on it: 0 passed, 1 did not, 5 still running
ankra pipeline get <run-id> --exit-code
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--branch` | | Select the run for this trigger branch instead of naming its id |
| `--exit-code` | `false` | Exit 1 when the run concluded without succeeding, and 5 while it has not concluded (`--wait` and `--watch` always exit this way) |
| `--head-sha` | | Select the run for this full commit sha instead of naming its id |
| `--latest` | `false` | Take the newest matching run when several match (on its own: the pipeline's newest run) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--step` | | Also print the per-cache table of the step with this key: each cache's outcome, reason, size and save |
| `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) |
| `--trigger` | | Select the run with this trigger: push, pull\_request, tag, schedule, manual, api, agent, or rerun |
| `--wait` | `false` | Wait for the run to conclude, then print its final detail; exits non-zero unless it succeeded |
| `--watch` | `false` | Print each run and step state change as it happens until the run concludes (-o json: one JSON object per line) |

## ankra pipeline list

List a pipeline's runs, newest first.

`--status` filters on the run's lifecycle - queued, running or concluded - not
on how it ended: every finished run is concluded, and its verdict is the
separate 'outcome' field (success, failure, cancelled, timed\_out, skipped or
infra\_error), which the STATUS column prints in place of the status once
there is one - except for a run a newer run superseded, which reads
'superseded' rather than 'cancelled'. 'ankra pipeline get `--help`' documents
both fields, supersession and the run's 'authority\_state'.

`--latest-per-branch` answers the other question a listing is usually opened
for: not the last N runs of everything, but the newest run of each branch.
It prints the same table as 'ankra pipeline branches' - see that command's
help - and cannot be combined with the run filters, which narrow runs rather
than refs.

```bash theme={null}
ankra pipeline list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | With `--latest-per-branch`, include branches with no run in the last 14 days |
| `--application` | | Application name or id whose pipeline to act on |
| `--branch` | | Filter by trigger branch |
| `--cursor` | | Page cursor from a previous listing's next\_cursor |
| `--head-sha` | | Filter by the exact full commit sha |
| `--latest-per-branch` | `false` | List one row per branch with the newest run on each, the table 'ankra pipeline branches' prints |
| `--limit` | `0` | Maximum number of runs to return (server default 50, max 100); with `--latest-per-branch`, the number of branches (server default 20) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--status` | | Filter by run status: queued, running, or concluded |
| `--trigger` | | Filter by trigger: push, pull\_request, tag, schedule, manual, api, agent, or rerun |

## ankra pipeline logs

Show a pipeline step's output.

A step that has already concluded prints its complete log in one shot -
`--follow` does nothing extra for it, since there is nothing left to produce.
Its archived log is read when the run has one; archiving needs a ready backup
vault, and when there is none the command replays the step's output from the
platform's retained log stream instead and stops when that runs out. A log
still being archived - asked for the moment its step ended - is waited for,
for up to a minute, before the command falls back to that replay; it exits 5
only when neither copy can be read.

A step that is still running is followed over the live log stream: without
`--follow`, the command tails the step until it concludes and then stops; with
`--follow` it keeps reconnecting through a dropped stream instead of giving up.
A live connection starts from the moment it connects unless you pass
`--replay`, which asks the platform for the output the step already produced
first.

A step that has not started yet has no log stream. With `--follow` the command
waits for it - saying what it is blocked on - and attaches as soon as the
step starts; a step that concludes without ever starting prints its outcome
and whatever log it does have. One invocation spends at most 30 minutes
waiting, in total across every time the step goes back to waiting. Without
`--follow` the command says the step has not started and stops.

A step Ankra runs on its own lanes never gets a live stream at all: a build
the platform builders took over because the run's cluster cannot build it,
and a gate, publish or approval the platform settles itself. Its log is
archived and printed here once the step concludes. 'ankra pipeline get' marks
those steps in the EXECUTOR column; with `--follow` the command waits for such
a step to conclude and then prints the archived log, and without it the
command says where the step is running and stops.

A step Ankra retried is several attempts under one key, each with its own
log. `--step` \<key> shows the newest attempt - the one that did the work - and
names the earlier ones on stderr; pass `--step` \<attempt id>, as
'ankra pipeline get' prints it, to read one of those instead.

```bash theme={null}
ankra pipeline logs <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--follow` | `false` | Wait for the step to start if it has not, then keep streaming, reconnecting through transient stream faults, until it concludes; for a step on Ankra's platform builders, which has no live stream, wait for it to conclude and print its archived log |
| `--replay` | `false` | Also show the output a running step produced before this command connected (a concluded step's log is always shown whole) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--step` | | Step key to follow (required when the run has more than one step), or the id of one attempt of it as 'ankra pipeline get' prints for a retried step |

## ankra pipeline repositories

Connect a bare Git repository to Ankra Pipelines, list what the
organisation has connected, read one by id, and disconnect one.

A connected repository is what a push, pull request or tag webhook resolves
against to start a run. Connecting one here does not require an Ankra
application - use it for a repository with no application (docs, website,
values repos) or before one exists; an application already on Ankra links to
its own repository automatically.

## ankra pipeline repositories connect

Connect a bare Git repository to Ankra Pipelines: a push, pull request or
tag webhook on it can then start a run.

Connecting a repository that is already connected does not create a second
row or refresh the first - the platform refuses with the existing
repository's id named in the error, so a setup script that runs this
unconditionally can still learn the id it has either way.

`--application` links the repository to an application already in this
organisation (by id) without changing that application's own pipeline
source - it is refused (422) for an application outside the organisation.
`--cluster` overrides the organisation's declared CI cluster
('ankra ci-settings' / GET /org/ci-settings) for just this repository's
pipelines - it is refused (422) for a cluster outside the organisation, or
one whose agent has not advertised it can run pipeline steps.

For a GitHub repository, the committed .ankra/pipeline.yaml on the default
branch (read through `--credential`) is recorded as the definition of record in
the same call when it parses. A repository with no committed file, or on
another provider, connects with no definition - store one with
'ankra pipeline definition put `--repository` \<id> \<file>'. Running connect a
second time will not pick up a file committed since, because an already-
connected repository is refused rather than re-read (see above); disconnect
the repository and connect it again to force a fresh read.

`--workspaces-only` connects the repository for Ankra Workspaces alone
('ankra exec', 'ankra workspace'): its committed pipeline file is not read,
no definition is recorded, no push, pull request, tag, schedule or manual
dispatch starts a run, and no commit status or check run is posted. Use it
for a repository whose pipeline already runs somewhere else. Switch an
already-connected repository with 'ankra pipeline repositories set-mode'.

```bash theme={null}
ankra pipeline repositories connect [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application id to link this repository to (optional; must belong to this organisation) |
| `--cluster` | | Cluster id to run this repository's pipelines on, overriding the organisation default (optional; its agent must support pipeline steps) |
| `--credential` | | Organisation Git credential used to read the repository; omit to connect without reading the committed pipeline file |
| `--default-branch` | | Branch the pipeline file is read from (default: main) |
| `--name` | | Repository name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--owner` | | Repository owner or organisation |
| `--provider` | | Repository provider: github, gitlab, or bitbucket |
| `--workspaces-only` | `false` | Connect for Ankra Workspaces only: no pipeline runs, commit statuses or check runs, and the pipeline file is not read |

## ankra pipeline repositories disconnect

Disconnect a connected repository: from then on a push, pull request or
tag webhook against it starts no run, and it drops out of
'ankra pipeline repositories list'/'get'.

This is reversible by construction - connecting the same provider/owner/name
again revives this exact row, definitions, runs, artifacts and findings kept -
so disconnecting is not a delete. A repository with a pipeline run still
queued or running refuses to disconnect (409); cancel or wait for it to
conclude, then disconnect again.

```bash theme={null}
ankra pipeline repositories disconnect <repository-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra pipeline repositories get

Show one connected repository by id.

There is no lookup by owner/name yet, only by id - run
'ankra pipeline repositories list' to find it.

```bash theme={null}
ankra pipeline repositories get <repository-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra pipeline repositories list

List the organisation's connected pipeline repositories

```bash theme={null}
ankra pipeline repositories list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cursor` | | Page cursor from a previous listing's next\_cursor |
| `--limit` | `0` | Maximum number of repositories to return (server default 50, max 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--provider` | | Repository provider: github, gitlab, or bitbucket (filter) |

## ankra pipeline repositories set-cluster

Change a connected repository's CI cluster override without disconnecting it.

```bash theme={null}
ankra pipeline repositories set-cluster <repository-id> --cluster build-cluster
ankra pipeline repositories set-cluster <repository-id> --cluster ""
```

The cluster (name or id) must belong to the organisation and its agent must run
pipeline steps. An empty `--cluster` clears the override, so the repository's
runs follow the organisation's CI settings - its pipeline cluster, or its CI
pool - again.

It changes where the repository's next runs go; a run already queued or
running keeps the cluster it was pinned to, because a run's steps never split
across clusters. Requires the pipelines.manage permission.

```bash theme={null}
ankra pipeline repositories set-cluster <repository-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or id the repository's runs go to; empty clears the override |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra pipeline repositories set-mode

Switch a connected repository's mode without disconnecting it.

```bash theme={null}
ankra pipeline repositories set-mode <repository-id> workspaces-only
ankra pipeline repositories set-mode <repository-id> pipelines
```

workspaces-only keeps Ankra Workspaces ('ankra exec', 'ankra workspace')
working and stops everything else: no push, pull request, tag, schedule or
manual dispatch starts a run, no commit status or check run is posted, and
the committed pipeline file is not read. It is refused (409) while a pipeline
run is queued or running; cancel it or wait for it to conclude first.

pipelines makes it an ordinary pipeline repository again: its committed
.ankra/pipeline.yaml is read on the next reconcile and its webhooks start runs.
Requires the pipelines.manage permission.

```bash theme={null}
ankra pipeline repositories set-mode <repository-id> <workspaces-only|pipelines> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra pipeline rerun

Open a new run from a run that already happened.

The new run is a fresh run, not a retry of the old one: the old run's outcome
stays the record of what happened. The new run is recorded with trigger
'rerun', and 'rerun\_of\_run\_id' ties the two together.

A re-run repeats the original event. A re-run of a push run is planned as a
push, so its push-only stages run. A re-run of a pull request run (or of a
merge train car) is planned as a pull request, and a re-run of a schedule run
as that schedule. A re-run of a tag run or of a manual or API dispatch is
planned as a plain re-run, so stages limited to other events are skipped.

A re-run's publish pushes the sha- image, but that image does not become the
push-to-deploy candidate, so a re-run does not roll the deployment.

`--failed-only` restricts the new run to the steps that failed, the steps that
were skipped because of a failure, whatever depends on them, and the steps
they build on. The new run starts from an empty workspace, so the checkout and
every upstream step whose output a repeated step reads run again with it;
steps that succeeded and that nothing repeated needs do not. A failed-only
re-run that would still skip one of those steps (for example a tag-only
release behind a failed build, on a re-run of a tag run) is refused with the
reason rather than passing without it.

`--full` sets the pipeline's path filters aside for the new run, so every stage
whose filters left it out runs, and the run records that you asked. A re-run
of a run that was already a full run is one again without the flag.

```bash theme={null}
ankra pipeline rerun <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--failed-only` | `false` | Re-run only the steps that did not succeed, whatever depends on them, and the steps they build on (checkout included) |
| `--full` | `false` | Run every stage: set the pipeline's path filters aside for the new run |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) |
| `--wait` | `false` | Wait for the new run to conclude before returning |

## ankra pipeline run

Dispatch a manual run of a pipeline's stored definition.

A run executes one commit, and Ankra checks it against the repository's own
host before anything is queued: a `--sha` that is not reachable from `--ref` (or
the repository's default branch) on that repository is refused.

Without `--sha`, the commit is:

* the working directory's HEAD, when the checkout is the repository the
  pipeline builds and `--ref` is not given. `--application` is read from the
  checkout too, so 'ankra pipeline run' on its own runs what you are
  looking at;
* otherwise the tip of `--ref`, or of the default branch, which Ankra reads
  from the repository's host when it dispatches.

A checkout of any other repository never supplies the commit, so
'ankra pipeline run `--application` other-app' from the wrong directory runs
other-app's default branch, not your local HEAD.

`--full` runs every stage: the pipeline's path filters (on.\<event>.paths,
when.paths and paths:) are set aside for this run, and the run records that
you asked. A stage's if: still decides.

```bash theme={null}
ankra pipeline run [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--full` | `false` | Run every stage: set the pipeline's path filters aside for this run |
| `--input` | `[]` | Dispatch input as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Human note recorded on the run |
| `--ref` | | Git reference to run at (defaults to the repository's default branch) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--sha` | | Full commit sha to run (defaults to HEAD of a checkout of this pipeline's repository, else the tip of `--ref`) |
| `--spec-file` | | Run this pipeline definition instead of the stored one (requires pipelines.manage) |
| `--timeout` | `0s` | Give up waiting after this long and exit 5, e.g. 45m (default: wait until the run concludes) |
| `--wait` | `false` | Wait for the run to conclude before returning |

## ankra pipeline schedules

Manage a pipeline's cron schedules

## ankra pipeline schedules create

Add a cron schedule

```bash theme={null}
ankra pipeline schedules create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--cron` | | Cron expression (required) |
| `--enabled` | `true` | Whether the schedule fires |
| `--input` | `[]` | Dispatch input as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ref` | | Git reference the schedule runs at (default the repository's default branch) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--timezone` | | IANA timezone the cron is evaluated in (default UTC) |

## ankra pipeline schedules delete

Remove a cron schedule

```bash theme={null}
ankra pipeline schedules delete <schedule-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra pipeline schedules list

List a pipeline's cron schedules

```bash theme={null}
ankra pipeline schedules list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline schedules update

Change a cron schedule. Every flag is optional and only what is given
changes - an update that names only `--enabled` leaves the cron, timezone, ref,
and inputs exactly as they were.

```bash theme={null}
ankra pipeline schedules update <schedule-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--cron` | | New cron expression |
| `--disabled` | `false` | Disable the schedule |
| `--enabled` | `false` | Enable the schedule |
| `--input` | `[]` | Replace the dispatch inputs entirely, as key=value (repeatable) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ref` | | New git reference |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--timezone` | | New IANA timezone |

## ankra pipeline tests

Show the test results Ankra recorded for a pipeline run.

A stage declares the reports its test command writes under test\_results
(JUnit, go test -json, pytest or Playwright), and Ankra reads every test's
outcome from them. 'ankra pipeline tests \<run>' lists the run's reports and
what became of each, then its failed, flaky and slowest tests. A run that
declared no reports says so: that is not a passing run.

```bash theme={null}
ankra pipeline tests <run>                          one run's summary
ankra pipeline tests history <test key>             one test across the branch's runs
ankra pipeline tests timings --stage <stage>        mean durations, for sharding
ankra pipeline tests quarantine                     the repository's flaky test quarantine
```

The test key is the one 'tests \<run> -o json' prints for each test. -o
json/yaml prints every field the server carries.

A repository can quarantine a known-flaky test ('ankra pipeline tests
quarantine `--help`'): a run step whose only failed tests are quarantined then
succeeds. The run's summary still lists those tests under Failed, and lists
them again in a "Quarantined failures" section that says whether each one's
step was forgiven or failed anyway because another test failed too.

```bash theme={null}
ankra pipeline tests <run> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--slowest` | `10` | How many of the slowest tests to list (0 to 50) |

## ankra pipeline tests history

Show one test's outcomes in the newest runs of a branch (the repository's
default branch unless `--branch` names another) and its flaky and failure rates
over them. Only the branch's own runs count (push, schedule, manual): a pull
request ran code the branch does not have.

```bash theme={null}
ankra pipeline tests history <test key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--branch` | | Branch to read (default: the repository's default branch) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--runs` | `0` | How many of the newest runs to look back over (1 to 100; default 30) |

## ankra pipeline tests quarantine

The flaky test quarantine lets a repository keep a known-flaky test from
failing its pipeline runs while someone fixes it.

It is off until you turn it on ('ankra pipeline tests quarantine settings
`--enable`', pipelines.manage). A test may be quarantined when, over the default
branch's own runs (never a pull request check) in the last 30 days, it ran in
at least `--min-samples` runs (default 20) and was flaky - failed, then passed
on a retry - in at least `--min-flaky-rate` of them (default 0.1, 10%).
'candidates' lists exactly the tests that qualify; 'add' quarantines one.

A quarantined test still runs and is still reported. What changes: a failing
'run' step whose ONLY failed tests are quarantined, read from test reports
the step uploaded whole, succeeds instead, and the steps after it run. A step
that also failed another test, failed on a timeout or infrastructure error,
or whose reports could not be read fails exactly as before.

A quarantine releases itself after `--release-after` passes in a row on the
default branch (default 10); a failed or flaky run starts the count again.
'release' ends one by hand.

Nothing is hidden: 'ankra pipeline tests \<run>' still lists every failed
test, and lists the quarantined failures in a section of their own whether or
not they rescued their step. 'ankra pipeline get \<run>' says which steps the
quarantine forgave.

With no subcommand, shows the settings, the quarantined tests and the ones
released in the last 30 days (the same as 'quarantine list').

```bash theme={null}
ankra pipeline tests quarantine [flags]
```

**Examples**

```bash theme={null}
ankra pipeline tests quarantine
ankra pipeline tests quarantine candidates
ankra pipeline tests quarantine add <test key> --reason "times out on the shared runner"
ankra pipeline tests quarantine release <quarantine id or test key> --reason "fixed in #123"
ankra pipeline tests quarantine settings --enable --min-flaky-rate 0.2
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline tests quarantine add

Quarantine one test, by the key 'quarantine candidates', 'tests \<run> -o json'
and 'tests history' print for it. `--reason` is required (1 to 500 characters)
and is shown beside the quarantine.

The platform refuses while the quarantine is off for the repository, for a
test that is not flaky enough on the default branch (it says the test's rate
and the thresholds), for a test already quarantined, and for a test with no
default-branch result in the last 30 days. Needs pipelines.manage.

```bash theme={null}
ankra pipeline tests quarantine add <test key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the test is quarantined (required, 1 to 500 characters) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline tests quarantine candidates

List the tests that qualify for quarantine, most flaky first: tests that, over
the default branch's own runs in the last 30 days, ran in at least the
repository's minimum number of runs and were flaky in at least its minimum
share of them, and are not quarantined already. Quarantine one with
'ankra pipeline tests quarantine add \<test key> `--reason "..."`'.

```bash theme={null}
ankra pipeline tests quarantine candidates [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--limit` | `0` | How many candidates to list (1 to 100; default 50) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline tests quarantine list

Show the repository's quarantine settings, every quarantined test (how
flaky it was when quarantined, its default-branch passes in a row towards its
release, and who quarantined it), and the tests released in the last 30 days
with why. -o json/yaml prints every field the server carries.

```bash theme={null}
ankra pipeline tests quarantine list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline tests quarantine release

Release a quarantined test: from the next run on, a step that fails it fails.

Name the quarantine by its id ('quarantine list' prints it) or by the test's
key, which is looked up among the repository's live quarantines. `--reason` is
optional (at most 500 characters). A quarantine also releases itself after
enough default-branch passes in a row. Needs pipelines.manage.

```bash theme={null}
ankra pipeline tests quarantine release <quarantine id or test key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the quarantine is released (optional, at most 500 characters) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline tests quarantine settings

Turn the repository's test quarantine on or off and set when a test may be
quarantined and when one releases itself. Only the flags you pass are sent;
the others keep their stored values. With no flag, prints the settings.

```text theme={null}
--enable / --disable     whether a step whose only failed tests are
                         quarantined succeeds (off by default)
--min-flaky-rate 0.1     the share of default-branch runs a test must have
                         been flaky in (greater than 0, at most 1)
--min-samples 20         over at least this many observed runs (3 to 1000)
--release-after 10       release after this many passes in a row (1 to 100)
```

Turning it off keeps the quarantined tests: their failures fail their steps
again until it is turned back on. Needs pipelines.manage to change.

```bash theme={null}
ankra pipeline tests quarantine settings [flags]
```

**Examples**

```bash theme={null}
ankra pipeline tests quarantine settings
ankra pipeline tests quarantine settings --enable
ankra pipeline tests quarantine settings --min-flaky-rate 0.2 --min-samples 30 --release-after 15
ankra pipeline tests quarantine settings --disable
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--disable` | `false` | Turn the quarantine off (the quarantined tests are kept) |
| `--enable` | `false` | Turn the quarantine on |
| `--min-flaky-rate` | `0` | Share of default-branch runs a test must have been flaky in to be quarantined (greater than 0, at most 1) |
| `--min-samples` | `0` | Observed default-branch runs that rate must rest on (3 to 1000) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--release-after` | `0` | Default-branch passes in a row that release a quarantine (1 to 100) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline tests timings

Show each file's (or, with `--group-by` test, each test's) mean recorded
duration for one stage across the newest runs of a branch, slowest first: the
input a sharding script balances its shards by. When nothing has been
recorded for the stage on the branch yet the command says so; fall back to an
even split rather than reading that as every test taking no time.

```bash theme={null}
ankra pipeline tests timings --stage <stage> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--branch` | | Branch to read (default: the repository's default branch) |
| `--group-by` | `file` | Group by "file" or "test" |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--runs` | `0` | How many of the newest runs to sample (1 to 100; default 30) |
| `--stage` | | Stage whose tests to time (required) |

## ankra pipeline time-saved

Show how much CI time path filters and promoted publishes saved over the
last 7 or 30 days: for one pipeline with `--application` or `--repository`, or
for the whole organisation with neither.

Each figure is an estimate the platform made when a run was planned or
skipped, from the stage's own recent history in the repository: the median of
its newest 20 successful runs. A stage with no history is counted as unknown
and is never added to a total. The time is runner time (step-seconds), not
wall-clock time. Only runs planned after the platform started recording this
are counted.

'ankra pipeline get \<run>' shows what one run saved.

```bash theme={null}
ankra pipeline time-saved [flags]
```

**Examples**

```bash theme={null}
# The organisation over the last 30 days
ankra pipeline time-saved

# One application's pipeline over the last 7 days, as JSON
ankra pipeline time-saved --application my-app --window 7d -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--window` | `30d` | How far back to count: 7d or 30d |

## ankra pipeline train

Manage a repository's Ankra merge train.

The merge train tests each pull request squashed onto the base branch and the
pull requests ahead of it, exactly as its merge will land, and merges it
through the repository host's own merge when that run passes. Every merge is
then a tree a pipeline run already passed, so a definition whose publish stage
declares promote\_from: pull\_request publishes the tested image instead of
rebuilding it.

The train is off by default: 'ankra pipeline train enable' switches it on
(pipelines.manage). 'ankra pipeline train add \<pull request>' puts a pull
request at the end of it, 'list' shows it in order and 'remove' takes one out.
An organisation administrator can move a pull request to the front with
'front'. GitHub repositories only.

'ankra pipeline train enable `--auto-admit` on' lets the train add green pull
requests by itself; 'shadow' only records which ones it would add, and 'list'
shows its latest decisions. A pull request based on another pull request's
branch rides on that pull request's entry, shown as "(on #N)".

'`--auto-admit-criterion`' says what auto-admit waits for: green, the default,
waits for a pull request's own run to pass, and ready adds it when it is marked
ready, before that run has passed. 'ankra pipeline train enable `--help`' has the
details and the protected paths that keep the green rule at ready.

The train merges under the Ankra GitHub App's identity, so adding or removing
a pull request needs pipelines.operate and, on top of it, one of: you are an
organisation administrator, you opened the pull request, or you have write
access to the repository on GitHub. Ankra reads the last two through the
GitHub identity you linked with OAuth from the Ankra portal. One exception:
with pipelines.operate you can always remove an entry you added yourself,
with or without a linked identity. Otherwise, without a linked identity only
an administrator can add or remove. If GitHub cannot be asked, the request is
refused and nothing changes.

## ankra pipeline train add

Put a pull request at the end of the merge train.

The train tests the pull request's head as it is now: pass `--head-sha` to pin
the commit you reviewed. A push to the pull request after it entered takes it
out of the train again. A pull request already in the train is answered with
its entry.

You must be an organisation administrator, the pull request's author, or have
write access to the repository on GitHub (through the GitHub identity you
linked from the Ankra portal), as well as pipelines.operate.

```bash theme={null}
ankra pipeline train add <pull request number> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--head-sha` | | Full commit sha to pin as the head the train tests and merges |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline train disable

Switch the merge train off and empty it

```bash theme={null}
ankra pipeline train disable [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline train enable

Switch the merge train on and set how it runs. A flag you leave out keeps its
current value.

`--auto-admit` off|shadow|on decides whether the train adds pull requests by
itself. shadow only records which ones it would add.

`--auto-admit-criterion` green|ready\_shadow|ready says what auto-admit waits for
once it is on. Every other auto-admit rule applies under all three: a draft, an
ankra:hold label or a blocked review keeps a pull request out.

```text theme={null}
green         A pull request enters once its own run has passed. Every
              repository's default.
ready_shadow  Still enters at green, and records which pull requests ready
              would have added while their own run was going, as
              ready_shadow_admit in 'ankra pipeline train list'. Use it to
              read what ready would do first.
ready         A pull request enters when it is marked ready, before its own
              run has passed, unless a step of that run already failed or
              GitHub says it does not merge cleanly. If its own run fails
              before its car has passed, it leaves the train. A pull request
              that changes a protected path, or whose list of changes could
              not be read in full, keeps the green rule and waits for its own
              run to pass.
```

At ready the car's run is the only run that has to pass before the merge, so
use it only once this repository's cars run everything its pull request runs
do. Going back to green leaves the entries already in the train where they are.

`--auto-admit-protected-paths` \<glob,...> sets the paths that keep the green rule
at ready: at most 50 GitHub-style patterns of at most 256 characters, where the
last matching pattern wins and a leading ! excludes.
`--auto-admit-protected-paths-default` restores the default list, alembic/\*\*,
deploy/charts/*/values.yaml and deploy/charts/*/values.schema.json.
`--auto-admit-protected-paths-none` protects nothing, so migrations and deploy
values enter at ready too. An empty `--auto-admit-protected-paths` is refused.

A service account token may set green or ready\_shadow. It may not set ready or
change the protected paths: those need a human member, and the platform refuses
the token with its reason.

```bash theme={null}
ankra pipeline train enable [flags]
```

**Examples**

```bash theme={null}
ankra pipeline train enable --max-cars 4
ankra pipeline train enable --auto-admit on --auto-admit-criterion ready_shadow
ankra pipeline train enable --auto-admit-criterion ready
ankra pipeline train enable --auto-admit-protected-paths 'alembic/**,deploy/**'
ankra pipeline train enable --auto-admit-protected-paths-default
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--auto-admit` | | Whether the train puts pull requests in by itself: off, shadow (only records what it would admit) or on; omitted keeps the current mode |
| `--auto-admit-criterion` | | What auto-admit waits for: green (its own run passed), ready\_shadow (green, and records what ready would add) or ready (marked ready, before its own run passed); omitted keeps the current one |
| `--auto-admit-protected-paths` | `[]` | Glob patterns, comma-separated, that keep the green rule at ready; omitted keeps the current list |
| `--auto-admit-protected-paths-default` | `false` | Restore the default protected paths |
| `--auto-admit-protected-paths-none` | `false` | Protect no path, so migrations and deploy values enter at ready too |
| `--max-cars` | `1` | How many pull requests are tested at once (1-8), each stacked on the ones ahead of it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline train front

Move a pull request to the front of the merge train.

The pull request goes ahead of every car that is still queued, building or
testing. Cars that already passed or are being merged stay ahead of it. Every
car it passes is built again on top of it and its running test is stopped, so
those pull requests wait longer.

Name the pull request by its number, as 'ankra pipeline train list' shows it,
or by its entry id. Only a pull request that is queued, building or testing
can move.

You must be an organisation administrator, as well as hold pipelines.operate.
Being the pull request's author or having write access is not enough, because
moving it delays pull requests other people added.

```bash theme={null}
ankra pipeline train front <pull request number | entry id> [flags]
```

**Examples**

```bash theme={null}
ankra pipeline train front 776
ankra pipeline train front 59a73935-a162-4c30-8a17-616a1cfcedee
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline train list

Show the merge train in order, and what recently left it

```bash theme={null}
ankra pipeline train list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline train remove

Take a pull request out of the merge train.

You can always remove an entry you added yourself. Removing anyone else's needs
the authority adding it would: organisation administrator, the pull request's
author, or write access to the repository on GitHub, as well as
pipelines.operate.

```bash theme={null}
ankra pipeline train remove <entry id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |

## ankra pipeline validate

Dry-run a pipeline definition: parse it, validate it, and plan it for a
synthetic push and a synthetic pull request, without writing anything.

Defaults to .ankra/pipeline.yaml when no file is given; with neither that file nor a
`--application`/`--repository` definition already stored, there is nothing to
validate. Passing a file validates its content directly, which is what a
'is my pipeline.yaml correct before I commit it' check wants. `--spec-file` is
the flag spelling of that argument, matching 'pipeline run `--spec-file`'.

After the per-event detail, a table shows every stage against every event
probed (push, pull\_request, and tag when the pipeline declares on.tag):
"run", or "skip" with the planner's reason. Path filters - flat when.paths or
an event block's when.pull\_request.paths / when.push.paths - cannot decide
without a diff, so they pass with a diagnostic; `--changed-file` (repeatable)
names a dry-run diff so they decide for real:

```bash theme={null}
ankra pipeline validate --repository <id> --changed-file frontend/app.ts
```

A stage that declares affected: (Go packages or pnpm workspace packages) is
decided at run time by the run's checkout, from the dependency graph of the
commit it checks out. With `--changed-file`, inside a git checkout, the CLI runs
the same analysis against the working tree and shows which of those stages
the change reaches ("graph: affected") and which it does not ("graph: not
affected", skipped and satisfied for the stages that need it).
`--no-local-graph` skips that and shows them as decided at run time.

`--ref` reads the definition from a git reference in the current checkout
instead of the working tree, so a candidate on a branch can be checked
before it is merged:

```bash theme={null}
ankra pipeline validate --ref origin/my-branch --application my-app
```

The reference is resolved locally, so a branch someone else pushed needs a
'git fetch' first, and the path is read from the repository root.

```bash theme={null}
ankra pipeline validate [file] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Application name or id whose pipeline to act on |
| `--changed-file` | `[]` | Plan as if this repository-relative path changed (repeatable), so path filters decide instead of passing |
| `--no-local-graph` | `false` | Do not read the dependency graph of the local checkout for affected: stages |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ref` | | Read the definition from this git reference in the current checkout (for example origin/my-branch) instead of the working tree |
| `--repository` | | Pipeline repository id to act on (mutually exclusive with `--application`) |
| `--spec-file` | | Validate this definition file, the same as passing it as the argument |


# ankra plugins
Source: https://docs.ankra.ai/reference/cli/plugins

List the external plugins that extend this CLI

## ankra plugins

List every executable the CLI would dispatch an unknown command to.

A plugin is an executable named ankra-\<command> in \~/.ankra/plugins or on
PATH. Running 'ankra \<command>' with a command the CLI does not know runs
the plugin with the remaining arguments, this terminal's streams, and
ANKRA\_CLI\_VERSION in its environment; its exit code is the CLI's. Built-in
commands always win, and multi-word names resolve longest first, so
'ankra foo bar' prefers ankra-foo-bar over ankra-foo.

Plugins run with your permissions; install only ones you trust. Executables
named ankra-module-\<name> are migrate modules, a separate mechanism listed
by 'ankra migrate modules', and ankra-cli - the CLI's own release binary -
is never a plugin.

```bash theme={null}
ankra plugins [flags]
```

**Examples**

```bash theme={null}
ankra plugins
ankra plugins -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra profile
Source: https://docs.ankra.ai/reference/cli/profile

Manage your Ankra profile

## ankra profile

Manage your Ankra profile

## ankra profile auth

Manage profile authentication and two-factor settings

## ankra profile auth open

Open Profile Authentication in your browser, where two-factor
authentication, authenticator apps, recovery codes, passkeys, and security
keys are managed.

```bash theme={null}
ankra profile auth open
```


# ankra project
Source: https://docs.ankra.ai/reference/cli/project

Manage the organisation's projects: a team-sized scope for clusters, applications and cost

## ankra project

Manage the organisation's projects.

A project is a scope inside an organisation. Clusters, applications,
environments, stack profiles, pipeline repositories and AI automations each
belong to exactly one project; credentials, registries, backup vaults,
buckets, organisation variables, notification routes and DNS zones belong to
one project or are organisation-wide (visible in every project). Members,
roles, billing and settings stay organisation-wide. Every organisation has a
default project, and until an administrator creates another one nothing
changes.

Which project a command acts in: the global `--project` \<id|slug> flag (or
ANKRA\_PROJECT) for one invocation, else the selection 'ankra project switch'
saves on this machine, else the current project the platform remembers for
you (the one the portal shows). 'ankra project current' says which applies.

Not to be confused with 'ankra registry projects', which are the projects of
the organisation's container registry (a Harbor concept).

Projects are turned on per organisation. While they are off, every project
command exits 3 saying so.

## ankra project create

Create a project. The slug is derived from the name unless `--slug` names one:
lowercase letters, digits and hyphens, at most 63 characters. It never
changes afterwards - it ends up in kubeconfig entries, CLI selections and
deep links - so pick it deliberately.

```bash theme={null}
ankra project create <name> [flags]
```

**Examples**

```bash theme={null}
ankra project create "Platform team"
ankra project create "Platform team" --slug platform --description "Shared infrastructure clusters"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--description` | | What the project is for |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--slug` | | The project's slug (default: derived from the name); lowercase letters, digits and hyphens, immutable |

## ankra project current

Show the project this CLI acts in, and why (flag, saved selection or the platform's current project)

```bash theme={null}
ankra project current [flags]
```

**Examples**

```bash theme={null}
ankra project current
ankra project current -o json
ankra --project platform-team project current
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra project delete

Delete a project. The default project cannot be deleted, and a project that
still holds resources is refused: move them with 'ankra project move' (or make
the shared ones organisation-wide) first. Members whose current project it was
are pointed back at the default project; tokens pinned to it stop working.

```bash theme={null}
ankra project delete <project> [flags]
```

**Examples**

```bash theme={null}
ankra project delete old-team
ankra project delete old-team --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra project get

Show one project by slug, name or id

```bash theme={null}
ankra project get <project> [flags]
```

**Examples**

```bash theme={null}
ankra project get platform-team
ankra project get platform-team -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra project list

List the organisation's projects, the current one marked

```bash theme={null}
ankra project list [flags]
```

**Examples**

```bash theme={null}
ankra project list
ankra project list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra project members

List who reaches a project, and how (organisation role or project-scoped assignment)

```bash theme={null}
ankra project members <project> [flags]
```

**Examples**

```bash theme={null}
ankra project members platform-team
ankra project members platform-team -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra project move

Move one resource to another project of the organisation (needs
projects.manage).

`--kind` names what moves: cluster, application, environment, stack\_profile, pipeline\_repository, ai\_automation, ai\_workspace
(each belongs to exactly one project), or credential, registry, backup\_vault, object\_storage\_bucket, organisation\_variable, notification\_route, dns\_zone
(which may also be organisation-wide). `--id` is the resource's id; for a
cluster or an application its name works too. `--to` is the destination
project by slug, name or id, or 'org-wide' to make a shared resource
visible in every project.

A cluster carries its DNS zones, incidents and tickets along; an application
carries its connected repositories; a stack profile carries its drafts. A
cluster with operations still running is refused until they finish, and a DNS
zone bound to a cluster follows that cluster instead of moving on its own.
Role assignments scoped to a project keep their project: a cluster that
leaves it is no longer reached by them.

```bash theme={null}
ankra project move --kind <kind> --id <id> --to <project|org-wide> [flags]
```

**Examples**

```bash theme={null}
ankra project move --kind cluster --id prod-eu --to platform-team
ankra project move --kind application --id 7d2a1c6e-... --to default
ankra project move --kind credential --id 0b7c4d1e-... --to org-wide
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--id` | | The resource's id (a cluster or application name works too) |
| `--kind` | | What moves: cluster, application, environment, stack\_profile, pipeline\_repository, ai\_automation, ai\_workspace, credential, registry, backup\_vault, object\_storage\_bucket, organisation\_variable, notification\_route, dns\_zone |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--to` | | Destination project (slug, name or id), or org-wide for a shared resource |

## ankra project rename

Rename a project. The slug never changes; pass `--description` to change the
description in the same call.

```bash theme={null}
ankra project rename <project> <new-name> [flags]
```

**Examples**

```bash theme={null}
ankra project rename platform-team "Platform engineering"
ankra project rename platform-team "Platform engineering" --description "Shared clusters"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--description` | | Replace the description as well |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra project switch

Switch to another project of the organisation. The platform's current project
moves with you (the portal follows), and the choice is saved on this machine
beside the organisation selection, so later commands act in it until you
switch again or run 'ankra org switch'. A token pinned to a project cannot
switch; pass `--project` for a single command instead.

```bash theme={null}
ankra project switch <project> [flags]
```

**Examples**

```bash theme={null}
ankra project switch platform-team
ankra project switch 071d45b1-f8fe-4f47-b13a-4f13a01689f1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra registry
Source: https://docs.ankra.ai/reference/cli/registry

Manage the organisation's Ankra registry

## ankra registry

Manage the organisation's Ankra registry.

Every organisation publishes to a private project on the Ankra registry. Ankra
mints the logins its own lanes use - the organisation's ci and pull robots, and
one push robot per application - and these commands cover the robot accounts
you need on top of that: a login for CI you run outside Ankra, a laptop
pushing an image by hand, or a cluster Ankra does not manage pulling from the
project. 'ankra registry robots list' shows both: yours, and the ones Ankra
manages.

A robot account is bound to one registry project. 'ankra registry projects'
creates extra projects beside the organisation's own, so a robot can be given
access to only what is kept in one of them.

Every project has a storage limit; a full one refuses every push. 'ankra
registry storage' shows how full it is, what fills it, the image retention
policy that frees it, and asks Ankra for more.

## ankra registry projects

Create, list and delete the organisation's registry projects.

These are projects of the organisation's container registry (a Harbor
concept), not the Ankra projects that scope clusters and applications - those
are 'ankra project'.

Every organisation has one project on the Ankra registry, named default here,
and everything it publishes lands there. A robot account is bound to one
project, so a robot on the default project reaches all of it. An extra project
is how you give a login less: push what should be kept apart into the extra
project and bind a robot to it with 'ankra registry robots create \<name>
`--registry-project` \<project>'.

An extra project is private and has the same scan policy, retention policy and
storage quota as the default one. Deleting one never deletes anything else on
the way: a project that still holds repositories, or that robot accounts are
still bound to, is refused.

## ankra registry projects create

Create an extra registry project for the organisation.

The name is 2 to 30 lower-case letters, digits and single hyphens; 'default' is the
organisation's own project and is reserved. The project is private and has the
same scan policy, retention policy and storage quota as the default one. Bind
a robot account to it with 'ankra registry robots create \<name> `--registry-project`
\<project>'.

```bash theme={null}
ankra registry projects create <name> [flags]
```

**Examples**

```bash theme={null}
ankra registry projects create staging
ankra registry robots create staging-ci --registry-project staging
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry projects delete

Delete an extra registry project.

Nothing else is deleted on the way. A project that still holds repositories is
refused until they are deleted from the registry, and one that robot accounts
are still bound to is refused until they are revoked. The organisation's own
project (default) cannot be deleted.

```bash theme={null}
ankra registry projects delete <name> [flags]
```

**Examples**

```bash theme={null}
ankra registry projects delete staging --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra registry projects list

List the organisation's registry projects: its own (default) first, then the
extra ones, each with the path images are pushed under, how many repositories
it holds and how many of your robot accounts are bound to it.

With `--registry` and `--admin-credential` it lists the projects of a Harbor your
organisation runs itself instead, as that credential sees them - the names to
bind a robot to with 'ankra registry robots create \<name> `--registry` ...
`--registry-project` \<project>'. That listing acts as the admin credential, so it needs
credentials.reveal.

```bash theme={null}
ankra registry projects list [flags]
```

**Examples**

```bash theme={null}
ankra registry projects list
ankra registry projects list -o json
ankra registry projects list --registry smartoptics-harbor --admin-credential smartoptics-harbor-robot-admin
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--admin-credential` | | With `--registry`: the organisation's registry credential that may manage robot accounts on that registry |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--registry` | | An integrated OCI registry entry - a Harbor your organisation runs - instead of the Ankra registry ('ankra helm registries list' shows them) |

## ankra registry robots

Create, list, rotate and revoke robot accounts on the organisation's registry
project.

A robot is a named login bound to one registry project: it reaches the
organisation's project and nothing else on the registry. It holds a preset -
push (push and pull) or pull - or its own list of permissions, and can be set
to expire. Its secret is shown once, when it is created or rotated; the login
is also stored as the managed registry credential ankra-harbor-robot-\<name>,
so it can be referenced from clusters and applications like any other registry
credential. Revoking a robot deletes it from the registry and drops that
credential in one step.

The robots Ankra mints for its own lanes (ci, pull, one per application) are
listed too. They are managed: Ankra rotates them and hands the new secret to
the builds and clusters that use it, so 'rotate' and 'delete' refuse them.

## ankra registry robots create

Create a robot account on the organisation's registry project and show its
secret once.

The name is 2 to 32 lower-case letters, digits and hyphens. The registry login
becomes robot\$\<project>+user-\<name>. `--scope` push (the default) grants push and
pull; `--scope` pull grants pull only. For anything else - a cleanup job that
deletes artifacts, a release job that moves tags, a scanner - grant exactly
what it needs with `--permission`, repeated or comma-separated, instead of a
scope; 'ankra registry robots permissions' lists what can be granted. Whatever
it holds, the robot reaches the organisation's project and no other.
`--expires-in-days` makes the registry stop honouring the robot after that many
days; without it the robot never expires. `--registry-project` binds the robot to one of
the organisation's extra registry projects instead of its own ('ankra registry
projects list' shows them); it then reaches that project and nothing else.

`--registry` creates the robot on a Harbor your organisation runs itself instead:
name the OCI registry entry it is integrated as ('ankra helm registries list'
shows them) and, with `--admin-credential`, a registry credential of the organisation
that may manage robot accounts there (project administrator on the project).
Ankra acts on that registry only with that credential, never its own; a robot
login Ankra manages cannot be used. `--registry-project` is required there: the one
project of that registry the robot is bound to, such as collectorcharts, and
the only one it reaches ('ankra registry projects list `--registry` ...
`--admin-credential` ...' shows them). Rotate, delete, get and list work the
same afterwards.

The secret is printed exactly once, with
a docker login command that reads it from stdin - copy it now, it is not stored
anywhere you can read it back from. The secret is never put on a command line,
where the shell history and 'ps' would keep it. Rotate it with 'ankra registry robots rotate' if it
is lost or leaked.

Creating a robot needs the credentials.write permission. A `--permission` list
that reaches past repository:pull and repository:push (deleting artifacts,
moving tags, and the like) also needs credentials.reveal, and so does a robot on
an integrated registry (`--registry`), which is minted by acting as the admin
credential. With `--permission` or
`--expires-in-days` the CLI first checks that the platform offers them by
reading the robot listing, and with `--registry-project` that the organisation has the
project; a token without credentials.read skips those checks, and if the
robot then comes back broader, longer-lived or on another project than asked
it is deleted again before its secret is shown.

```bash theme={null}
ankra registry robots create <name> [flags]
```

**Examples**

```bash theme={null}
ankra registry robots create jenkins --description "Jenkins on the office server"
ankra registry robots create edge-cluster --scope pull
ankra registry robots create contractor --scope pull --expires-in-days 30
ankra registry robots create cleanup --permission repository:pull,artifact:list,artifact:delete
ankra registry robots create staging-ci --registry-project staging
ankra registry robots create jenkins --registry smartoptics-harbor \
  --admin-credential smartoptics-harbor-robot-admin --registry-project smart-hub-images
ankra registry robots create jenkins -o json | jq -r .secret
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--admin-credential` | | With `--registry`: the organisation's registry credential that may manage robot accounts on that registry |
| `--description` | | What this robot is for (shown in the listing) |
| `--expires-in-days` | `0` | Days until the registry stops honouring the robot (default: it never expires) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--permission` | `[]` | A permission to grant instead of a preset scope, written resource:action; repeat the flag or separate with commas ('ankra registry robots permissions' lists them) |
| `--registry` | | An integrated OCI registry entry - a Harbor your organisation runs - instead of the Ankra registry ('ankra helm registries list' shows them) |
| `--registry-project` | | The registry project to bind the robot to (default: the organisation's own; 'ankra registry projects list' shows the others) |
| `--scope` | `push` | Rights on the project: push (push and pull) or pull |

## ankra registry robots delete

Revoke a robot account: delete it from the registry and drop the managed
credential holding its login.

Everything still logging in with the robot stops working, which is the point
of a revoke. Prefer 'rotate' when the robot should keep working under a new
secret. A robot Ankra manages is refused: it is not yours to revoke.

```bash theme={null}
ankra registry robots delete <name> [flags]
```

**Examples**

```bash theme={null}
ankra registry robots delete jenkins --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra registry robots get

Show one robot account: its registry login, what it may do, the project it is
bound to, the managed credential holding its login, and when it was created,
last rotated and expires. One of your own robots is read by its name; one
Ankra manages by the name the listing gives it (ci, pull, app-\<application id>).
The secret is never shown here; rotate the robot to get a new one.

```bash theme={null}
ankra registry robots get <name> [flags]
```

**Examples**

```bash theme={null}
ankra registry robots get jenkins
ankra registry robots get ci
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry robots list

List every robot account the organisation holds on its registry project.

Your own robots come first, then the ones Ankra manages: the organisation's ci
and pull robots and one push robot per application. Each row shows the robot's
kind, registry login, what it may do, the project it is bound to, when it
expires, and when it was created and last rotated. Secrets are never listed.

`--kind` narrows the listing: user (the ones you created), managed (everything
Ankra minted), organisation (ci and pull) or application. Managed robots are
shown so you can see every login that reaches the organisation's images; they
are rotated by the lane that owns them, not from here.

```bash theme={null}
ankra registry robots list [flags]
```

**Examples**

```bash theme={null}
ankra registry robots list
ankra registry robots list --kind user
ankra registry robots list --kind managed -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--kind` | `all` | Which robots to list: all, user (yours), managed (Ankra's), organisation or application |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry robots permissions

List the permissions a robot account can be created with.

Each one is a value for 'ankra registry robots create `--permission`'. They are
all rights on the content of the organisation's own registry project - pulling,
pushing, listing and deleting repositories and artifacts, managing tags,
scanning - never on the project's settings or on any other project.

```bash theme={null}
ankra registry robots permissions [flags]
```

**Examples**

```bash theme={null}
ankra registry robots permissions
ankra registry robots permissions -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry robots rotate

Mint a new secret for a robot account and show it once.

The previous secret stops working the moment the registry answers, which makes
this the response to a leaked or lost secret. Update every place that logs in
with the robot afterwards. A robot the registry no longer has is minted again
under the same name, with the same permissions and the rest of its lifetime. A
rotation never extends a robot: one that has expired is refused, and so is a
robot Ankra manages. Asks first, because a mistyped name would take another
robot's consumers down; `--yes` skips the prompt for scripts.

```bash theme={null}
ankra registry robots rotate <name> [flags]
```

**Examples**

```bash theme={null}
ankra registry robots rotate jenkins
ankra registry robots rotate jenkins --yes -o json | jq -r .secret
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra registry storage

See how full the organisation's registry is, free space, or ask for more.

Every registry project has a storage limit (50 GiB by default). Once a project
is full the registry refuses every image push to it, so builds stop
publishing. Run on its own, this shows the usage against the limit for each
project.

```bash theme={null}
ankra registry storage                      usage against the limit
ankra registry storage repositories         what takes the space, largest first
ankra registry storage retention            the image retention policy
ankra registry storage retention set ...    keep fewer or more images
ankra registry storage retention run        clean up now instead of at the daily run
ankra registry storage buy --blocks <n>     buy more storage, billed monthly
ankra registry storage request ...          ask Ankra for a bigger limit
```

```bash theme={null}
ankra registry storage [flags]
```

**Examples**

```bash theme={null}
ankra registry storage
ankra registry storage -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry storage buy

Set how many paid storage blocks the organisation holds on top of its included
registry storage. Each block adds its size to the limit of every registry
project and is billed monthly for the days it is held. `--blocks` is the number
to hold, not the number to add; 0 stops paying for extra storage.

It shows the limit and the monthly price before and after, and asks first;
`--yes` skips the prompt. Lowering it below what the registry already holds is
refused: free space first. For more than the self-serve maximum, ask Ankra
with 'ankra registry storage request'.

```bash theme={null}
ankra registry storage buy [flags]
```

**Examples**

```bash theme={null}
ankra registry storage buy --blocks 2
ankra registry storage buy --blocks 0 --yes
ankra registry storage buy --blocks 4 --yes -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--blocks` | `0` | How many paid storage blocks to hold (0 stops paying for extra storage) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra registry storage repositories

Show which repositories take the registry space, largest first.

Repositories under ankra-ci/ hold the images Ankra builds and scans in CI, one
per pipeline run and pull request; they are usually what fills the registry.
The others hold the images your applications publish. The Retention column
names the rule that governs each repository, or the organisation policy.

Sizes are approximate: a layer shared by several images is counted for each of
them, so use the sizes to rank repositories, not to add up to the usage. This
reads every image in the registry and can take a while.

```bash theme={null}
ankra registry storage repositories [flags]
```

**Examples**

```bash theme={null}
ankra registry storage repositories
ankra registry storage repositories --limit 0 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `20` | How many repositories to show, largest first (0 shows all) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry storage request

Ask Ankra for a bigger registry storage limit. `--size` is the limit you need
for each registry project, in GiB (more than today's, at most 10240); `--reason`
says why. The Ankra team reviews the request and you are notified when it is
decided; once approved the registry applies the new limit within about 5
minutes. 'ankra org limits list' shows the request's state.

```bash theme={null}
ankra registry storage request [flags]
```

**Examples**

```bash theme={null}
ankra registry storage request --size 100 --reason "Three services now publish nightly images"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the organisation needs it (required) |
| `--size` | `0` | The storage limit you need for each registry project, in GiB |

## ankra registry storage retention

Show or change the image retention policy: which images the registry keeps.

An image is kept when it was pushed within the policy's days, or is among the
newest images of its repository; everything else is deleted when retention
runs (daily). The newest image of every repository is never deleted. Deleted
images free their space at the registry's next garbage collection (weekly).

The organisation policy governs every repository. A rule replaces it for the
repositories its pattern matches - for example a shorter one for CI images:

```bash theme={null}
ankra registry storage retention rule add 'ankra-ci/**' --keep-days 7 --keep-latest 2
```

Patterns are lower-case letters, digits and . \_ / - with \* matching within
one path segment and \*\* across segments; braces and commas are not accepted,
so write one rule per pattern.

```bash theme={null}
ankra registry storage retention [flags]
```

**Examples**

```bash theme={null}
ankra registry storage retention
ankra registry storage retention -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry storage retention rule

Add, remove and list retention rules. A rule replaces the organisation policy
for the repositories its pattern matches. Patterns are lower-case letters,
digits and . \_ / - with \* matching within one path segment and \*\* across
segments; braces and commas are not accepted, so write one rule per pattern.
'\*\*' alone is the organisation policy itself ('retention set').

A rule needs an organisation policy that keeps something: when the policy in
force keeps nothing, the platform refuses rules until one is set with
'ankra registry storage retention set'.

## ankra registry storage retention rule add

Add a retention rule for the repositories a pattern matches, or change the rule
already stored for that pattern.

`--keep-days` and `--keep-latest` work as in 'retention set'; a flag not passed
takes the existing rule's value, or the organisation policy's for a new rule.
`--application` ties the rule to an application, so it shows with it.

A rule that keeps fewer images than what governs those repositories now asks
first; `--yes` skips the prompt. Quote the pattern so the shell does not expand
it.

```bash theme={null}
ankra registry storage retention rule add <pattern> [flags]
```

**Examples**

```bash theme={null}
ankra registry storage retention rule add 'ankra-ci/**' --keep-days 7 --keep-latest 2
ankra registry storage retention rule add 'investor-update/*' --keep-latest 10 --application <id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | The application the rule belongs to (its id) |
| `--keep-days` | `0` | Keep every image pushed in this many days (0 turns it off) |
| `--keep-latest` | `0` | Always keep this many newest images of each matching repository (at least 1) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt when the rule keeps fewer images |

## ankra registry storage retention rule list

List the retention rules

```bash theme={null}
ankra registry storage retention rule list [flags]
```

**Examples**

```bash theme={null}
ankra registry storage retention rule list
ankra registry storage retention rule list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry storage retention rule remove

Remove the retention rule for a pattern; the repositories it matched follow the
organisation policy again. When that policy keeps fewer images than the rule
did, it asks first; `--yes` skips the prompt.

```bash theme={null}
ankra registry storage retention rule remove <pattern> [flags]
```

**Examples**

```bash theme={null}
ankra registry storage retention rule remove 'ankra-ci/**'
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt when the organisation policy keeps fewer images |

## ankra registry storage retention run

Start the retention cleanup now instead of at its daily time: images the policy
does not keep are deleted. The space they held is freed at the registry's next
garbage collection (weekly), not at once.

```bash theme={null}
ankra registry storage retention run [flags]
```

**Examples**

```bash theme={null}
ankra registry storage retention run
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry storage retention set

Change the organisation retention policy: the one every repository without a
rule follows.

`--keep-days` keeps every image pushed in that many days (0 turns it off, so
only the newest are kept); `--keep-latest` always keeps that many newest images
of each repository (at least 1). A flag not passed keeps its current value.
`--reset` goes back to the platform default. Rules are not touched.

A change that keeps fewer images asks first, because what it no longer keeps
is deleted at the next retention run; `--yes` skips the prompt.

The change is made to the retention as it is stored when it is written: if
someone else changes it between the read and the write, the platform refuses
the write and the change is applied again to the new retention, once.

```bash theme={null}
ankra registry storage retention set [flags]
```

**Examples**

```bash theme={null}
ankra registry storage retention set --keep-days 14
ankra registry storage retention set --keep-days 7 --keep-latest 2 --yes
ankra registry storage retention set --reset
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--keep-days` | `0` | Keep every image pushed in this many days (0 turns it off) |
| `--keep-latest` | `0` | Always keep this many newest images of each repository (at least 1) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reset` | `false` | Go back to the platform default policy |
| `-y`, `--yes` | `false` | Skip the confirmation prompt when the change keeps fewer images |

## ankra registry storage retention show

Show the image retention policy

```bash theme={null}
ankra registry storage retention show [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra registry storage show

Show the registry storage usage against the limit

```bash theme={null}
ankra registry storage show [flags]
```

**Examples**

```bash theme={null}
ankra registry storage show
ankra registry storage show -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra runs
Source: https://docs.ankra.ai/reference/cli/runs

Inspect and act on the organisation's runs

## ankra runs

Read the organisation's run history and act on the runs that move data. A backup, restore or clone run also carries the plan it was given and every attempt of every step, which is what explains a restore that took an hour.

## ankra runs cancel

Stop a run that is still going. A run that has already finished is refused rather than reported as cancelled.

```bash theme={null}
ankra runs cancel <run-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra runs get

Describe one run. A backup, restore or clone also shows the plan it was given and every attempt of every step, with the status, the agent job and the failure excerpt of each.

```bash theme={null}
ankra runs get <run-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra runs list

List the organisation's runs, newest first.

Naming a cluster or a stack asks the backup lane's own listing, which carries
each run's data-movement payload; without one, the listing covers every kind
of run the organisation has.

Examples:

```bash theme={null}
ankra runs list --kind backup
ankra runs list --cluster production --status failed
ankra runs list --kind restore --stack shop
```

```bash theme={null}
ankra runs list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only runs touching this cluster (name or id); asks the backup lane's listing |
| `--cursor` | | Continue from a previous page's cursor |
| `--kind` | | Only runs of this kind: backup, restore, clone, pipeline, promotion, dr\_drill, environment\_hydrate |
| `--limit` | `0` | Page size (server default 50, maximum 100) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stack` | | Only runs touching this stack; asks the backup lane's listing |
| `--status` | | Only runs in this status (pending, running, blocked, succeeded, failed, cancelled) |

## ankra runs retry

Open a fresh run that resumes a failed backup, restore or clone from the
step that failed.

The answer is the new run, not the old one: the failed row will never move
again, so anything watching it would wait forever.

```bash theme={null}
ankra runs retry <run-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra secrets
Source: https://docs.ankra.ai/reference/cli/secrets

Manage organisation secrets that manifests and addon values reference by sentinel

## ankra secrets

Manage the organisation's secrets (secret slots).

A secret holds one value in Ankra's vault. Manifests, addon values and MCP
server env reference it by its sentinel, \$\{SECRET\_SLOT:\<id>}, instead of
carrying the value, so the value never lives in Git, in a stack definition or
in a chat transcript. Ankra substitutes the value only when it seals the file
with the organisation's SOPS key for delivery: put the sentinel at a key that
the manifest's or addon's encrypted\_paths declares.

Values only go in, never come out: list shows names, ids, who uses each
secret and when it was last read, never a value. A value is read from stdin,
a masked prompt or `--from-file`, or generated by Ankra with `--generate`; it is
never accepted as a command-line argument.

```bash theme={null}
ankra secrets create db-password --generate
ankra secrets create stripe-key --from-file ./stripe.key
printf '%s' "$TOKEN" | ankra secrets create ci-token
ankra secrets list
ankra secrets set stripe-key --from-file ./stripe-new.key
ankra secrets rotate db-password --generate
ankra secrets delete ci-token
```

## ankra secrets create

Create a secret and print its sentinel, \$\{SECRET\_SLOT:\<id>}, on stdout.
Put the sentinel where the value belongs.

The value comes from exactly one of:

```text theme={null}
--generate          Ankra creates a random value nobody sees
--from-file <path>  the file's bytes, exactly as stored
stdin               piped input, without the one line ending the pipe adds;
                    on a terminal, a masked prompt (surrounding spaces are
                    dropped there, since a typed one is a typo)
```

It is never accepted as a command-line argument. `--generate` ignores stdin:
pipe a value without `--generate` to store it.

A secret does not expire, whether Ankra generated it or you supplied the
value, unless `--ttl` is given (at most a week for a generated secret). A
secret with a `--ttl` is kept past it for as long as a deployed resource
references its sentinel.

The sentinel alone goes to stdout, so it can be captured:

```bash theme={null}
SENTINEL="$(ankra secrets create db-password --generate)"
```

```bash theme={null}
ankra secrets create <name> [flags]
```

**Examples**

```bash theme={null}
ankra secrets create db-password --generate --length 48
ankra secrets create stripe-key --from-file ./stripe.key --hint "Stripe live key"
printf '%s' "$TOKEN" | ankra secrets create ci-token
ankra secrets create ci-token -o json < token.txt
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from-file` | | Read the value from this file, byte for byte |
| `--generate` | `false` | Have Ankra create a random value nobody sees |
| `--hint` | | A note about what the secret is for (at most 240 characters) |
| `--length` | `32` | With `--generate`: how many random characters (16-96) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--prefix` | | With `--generate`: text in front of the random characters (at most 16, no whitespace) |
| `--ttl` | `0s` | Expire the secret after this long, e.g. 72h (no expiry when unset; at most 168h for a generated secret) |

## ankra secrets delete

Delete a secret and its stored value. This cannot be undone.

A secret that deployed resources still reference is refused, and the
resources are named: remove the sentinel from them (or remove the resources)
first. There is no `--force`: the platform refuses to delete a referenced
secret, because the next delivery of those resources would fail.

```bash theme={null}
ankra secrets delete <name|id> [flags]
```

**Examples**

```bash theme={null}
ankra secrets delete ci-token
ankra secrets delete 0b6f2c1e-3c44-4b9e-9a51-2f1f6f0f9a10 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra secrets list

List the organisation's secrets, newest first: name, id, whether a person
or Ankra supplied the value, the deployed resources that reference it, when
the value was last read and when the secret expires. Values are never shown.

-o json includes each secret's sentinel and every reference.

```bash theme={null}
ankra secrets list [flags]
```

**Examples**

```bash theme={null}
ankra secrets list
ankra secrets list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra secrets rotate

Rotate a secret's value in place. The secret keeps its id, so its sentinel
and every reference to it stay valid; the resources that reference it receive
the new value when Ankra next delivers them.

With `--generate` Ankra creates the new random value and nobody sees it.
Without it the new value comes from `--from-file` or stdin, as for 'set';
with it, stdin is ignored. The value is never accepted as a command-line
argument.

```bash theme={null}
ankra secrets rotate <name|id> [flags]
```

**Examples**

```bash theme={null}
ankra secrets rotate db-password --generate
ankra secrets rotate db-password --generate --length 64 --prefix pw_
ankra secrets rotate stripe-key --from-file ./stripe-new.key
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from-file` | | Read the new value from this file, byte for byte |
| `--generate` | `false` | Have Ankra create the new random value |
| `--length` | `32` | With `--generate`: how many random characters (16-96) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--prefix` | | With `--generate`: text in front of the random characters (at most 16, no whitespace) |

## ankra secrets set

Replace a secret's value in place with one you supply. The secret keeps its
id, so its sentinel and every reference to it stay valid; the resources that
reference it receive the new value when Ankra next delivers them.

The value comes from `--from-file` (the file's bytes, exactly as stored) or
stdin (without the one line ending the pipe adds; on a terminal, a masked
prompt that drops surrounding spaces). It is never accepted as a command-line argument. To have Ankra
generate the new value, use 'ankra secrets rotate `--generate`'.

```bash theme={null}
ankra secrets set <name|id> [flags]
```

**Examples**

```bash theme={null}
ankra secrets set stripe-key --from-file ./stripe-new.key
printf '%s' "$NEW_TOKEN" | ankra secrets set ci-token
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from-file` | | Read the new value from this file, byte for byte |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra security
Source: https://docs.ankra.ai/reference/cli/security

Read the Security Center: exploited-in-the-wild findings, fleet posture and scanner coverage

## ankra security

Read the organisation's Security Center - the same data the portal shows,
for your own reporting and automation.

Every finding carries its exploitation intelligence: whether CISA lists the
CVE in its Known Exploited Vulnerabilities (KEV) catalog, with CISA's
remediation deadline and required action, and the FIRST EPSS probability
that it is exploited in the next 30 days. Findings sort by exploitability by
default - CISA listing first, then EPSS, then severity - so the top of the
list is what is actually being exploited, not what merely has the highest
CVSS score.

Pass -o json (or yaml) for the full API document.

## ankra security access

Evaluate one cluster's kube gateway grants and print every failed check,
most severe first: a grant whose identity the cluster verified can
impersonate, a standing cluster-wide admin or cluster-admin grant, a grant
the organisation's access policy would refuse today, and the creator's grant
left unchanged for 90 days on a GitOps cluster. Each finding names the grant,
the grantee, its role and scope, and the commands that fix it.

Checks that could not be evaluated are listed after the findings, so a short
list is never read as a clean one. A grant absent from both lists passed
every check. Grantee emails appear only when you hold kube\_access.manage;
otherwise the grantee is shown by its Ankra user id. A service account,
which has no email, is shown as "service account \<name>".

If the platform leaves the summary (or one of its always-sent counts), the
findings or the unknowns out of its answer, that part reads "not reported", whatever was reported is still
printed, and the command exits 1: an incomplete answer is never a pass.
-o json prints the document as sent, nulls included, and exits 0.

The same summary line is the Access column of 'ankra security clusters'.

```bash theme={null}
ankra security access [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security addon

One add-on's security posture on a cluster: the findings attributed to its images

```bash theme={null}
ankra security addon <addon-name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security advisory

Show the platform's advisory for one CVE: the parsed NVD/OSV record, CISA's guidance and your exposure

```bash theme={null}
ankra security advisory <cve-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security benchmarks

Read one cluster's benchmark compliance through its agent: each
ClusterComplianceReport (CIS, NSA/CISA, ...) with pass and fail totals and
the failing controls, plus the config-audit rollup by namespace and check.

A cluster whose agent is offline answers with the reason and a retry hint
rather than an empty report. Drill into one failing control with
'ankra security benchmarks resources'.

```bash theme={null}
ankra security benchmarks [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security benchmarks resources

List the Kubernetes objects failing one control on a cluster and, when the
platform could match them, the stack and resource that owns each. `--check`
is the control id from 'ankra security benchmarks'; `--source` is benchmark
(pass `--benchmark` with the spec id) or config\_audit.

Example:

```bash theme={null}
ankra security benchmarks resources --cluster production --check 5.1.1 --benchmark cis-1.23
```

```bash theme={null}
ankra security benchmarks resources [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--benchmark` | | Benchmark spec id, required with `--source` benchmark |
| `--check` | | Control id, required |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--source` | `benchmark` | Where the control comes from: benchmark or config\_audit |

## ankra security clusters

List every cluster's security posture: scanner freshness, actionable and
known-exploited findings, and the Access line counting its kube gateway grants
(live grants, standing grants above view, grants over the organisation's
access policy, and grants whose identity the cluster verified can
impersonate).

A count the platform could not establish reads "unknown", never 0: over
policy when the access policy could not be read, impersonate until every live
grant has a verified probe answer. A platform that predates the access
posture reads "not reported". Open one cluster's grant findings and their
fixes with 'ankra security access `--cluster` \<cluster>'.

```bash theme={null}
ankra security clusters [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Clusters per page (max 100) |
| `--search` | | Match cluster name |
| `--sort` | `actionable` | Sort key: actionable, known\_exploited, severity, observed, accepted\_risk, latest\_report\_at, status, name |
| `--status` | | Scanner or posture status filter: fresh, stale, unscanned, clean, critical, high, degraded |

## ankra security compliance

Show every cluster's benchmark compliance (CIS, NSA/CISA and the other
specs the scanner evaluates) with pass and fail totals and the config-audit
posture. A cluster the scanner does not run on, or whose agent could not be
reached, reads not\_available with the reason rather than as compliant.

Subcommands cover the compliance frameworks (GDPR, ISO 27001, SOC 2, NIST
CSF): the catalogue, switching one on or off, its control-by-control report,
and the evidence export.

```bash theme={null}
ankra security compliance [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security compliance export

Download the organisation's compliance evidence report: cluster posture,
findings, dispositions, the audit summary and the attestation, for a window
that defaults to the last 90 days. CSV by default; `--format` json for the
full document. Needs the security.read and audit.read permissions.

The file goes to the name the platform suggests in the current directory,
to `--output-file`, or to standard output with `--output-file` -.

Example:

```bash theme={null}
ankra security compliance export --format json --start-date 2026-07-01 --end-date 2026-09-30 --output-file q3.json
```

```bash theme={null}
ankra security compliance export [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--end-date` | | Window end (YYYY-MM-DD or RFC3339); the platform defaults to now |
| `--force` | `false` | Overwrite an existing file |
| `--format` | `csv` | Report format: csv or json |
| `--output-file` | | Where to write the report; - for standard output (default: the name the platform suggests) |
| `--start-date` | | Window start (YYYY-MM-DD or RFC3339); the platform defaults to 90 days ago |

## ankra security compliance frameworks

The compliance framework catalogue with each framework's switch and live score

```bash theme={null}
ankra security compliance frameworks [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security compliance frameworks disable

Disable one framework by its key (see 'ankra security compliance frameworks').
Needs the security.manage permission; asks for confirmation unless `--yes`.

```bash theme={null}
ankra security compliance frameworks disable <framework-key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security compliance frameworks enable

Enable one framework by its key (see 'ankra security compliance frameworks').
Needs the security.manage permission; asks for confirmation unless `--yes`.

```bash theme={null}
ankra security compliance frameworks enable <framework-key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security compliance frameworks report

Print a framework's report: the score, every category with its controls
and the automated checks behind each, the recorded monthly trend and the
months a snapshot exists for. `--month` YYYY-MM reads a recorded month; the
default is the live evaluation.

```bash theme={null}
ankra security compliance frameworks report <framework-key> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--month` | | Recorded month to read (YYYY-MM); the default is the live evaluation |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security dispositions

List the organisation's vulnerability-disposition policies. A disposition
acknowledges a finding (it stays visible but leaves the actionable set) or
accepts its risk, for every occurrence its selector matches - one CVE and
package inside one add-on across the organisation, or pinned to one workload
or one image digest when no add-on owns the image.

Each policy has a lifecycle status: active, expiring (the review deadline
is near), fix\_available (a fixed version exists, so the acceptance should be
revisited), mitigated (nothing matches any more), unmatched (nothing ever
matched), expired or revoked.

Examples:

```bash theme={null}
ankra security dispositions --status expiring --status fix_available
ankra security dispositions --disposition accepted_risk --sort expires_at --order asc
```

```bash theme={null}
ankra security dispositions [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--disposition` | `[]` | Disposition filter, repeatable: acknowledged, accepted\_risk |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Dispositions per page (max 100) |
| `--search` | | Match CVE id, package name, add-on or reason |
| `--sort` | `updated_at` | Sort key: updated\_at, created\_at, expires\_at, matched\_occurrence\_count, status, disposition |
| `--status` | `[]` | Lifecycle filter, repeatable: active, expiring, fix\_available, mitigated, unmatched, expired, revoked |

## ankra security dispositions create

Write a disposition anchored on one occurrence: acknowledged keeps the
finding visible but out of the actionable set; accepted\_risk records a
decision to live with it, which needs the security.manage permission.

The preview prints first and the write asks for confirmation; `--yes` skips
the prompt. Give a `--reason`: it is what an auditor reads. `--expires-at` sets
a review deadline; `--expire-when-fix-available` ends the disposition the
moment a fixed version appears. `--allow-unmatched` stores a policy whose
anchor no longer matches anything.

`--scope` chooses what the policy is pinned to: organisation\_addon (the
default) for the add-on that owns the occurrence, or workload or image when
no add-on owns the image.

Examples:

```bash theme={null}
ankra security dispositions create --occurrence 4f1c... --disposition acknowledged --reason "tracked in PLA-812" --expires-at 2026-10-31
ankra security dispositions create --occurrence 4f1c... --scope workload --disposition accepted_risk --reason "operator-managed, not reachable from outside the cluster"
```

```bash theme={null}
ankra security dispositions create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allow-unmatched` | `false` | Store the policy even when its anchor no longer matches any occurrence |
| `--disposition` | | acknowledged or accepted\_risk |
| `--expire-when-fix-available` | `false` | End the disposition the moment a fixed version appears |
| `--expires-at` | | Review deadline as a date (2026-12-31) or RFC3339 timestamp |
| `--occurrence` | | Occurrence id to anchor the disposition on (from 'ankra security finding \<id>') |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the finding is acknowledged or its risk accepted (kept for audit) |
| `--scope` | `organisation_addon` | Selector scope: organisation\_addon, workload or image; use workload or image when no add-on owns the occurrence's image |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security dispositions preview

Compute a disposition's blast radius without writing anything: how many
occurrences, findings, clusters and add-ons the selector would cover, what
it deliberately excludes (ambiguous or unattributed occurrences, ones with a
fix available when the policy expires on fix), the policies it overlaps, and
the actionable total before and after.

Anchor a new policy on one occurrence with `--occurrence` (an id from
'ankra security finding \<id>'), or re-preview an existing policy with
`--policy`.

`--scope` chooses what the policy is pinned to. organisation\_addon (the
default) covers the add-on that owns the occurrence, on every cluster.
workload covers one workload on one cluster and image covers one image
digest wherever it runs; use either when no add-on owns the image, such as
operator-managed pods, plain manifests or control-plane pods.

Examples:

```bash theme={null}
ankra security dispositions preview --occurrence 4f1c... --disposition accepted_risk --expires-at 2026-12-31
ankra security dispositions preview --occurrence 4f1c... --scope workload --disposition acknowledged
```

```bash theme={null}
ankra security dispositions preview [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--disposition` | | acknowledged or accepted\_risk |
| `--expire-when-fix-available` | `false` | End the disposition the moment a fixed version appears |
| `--expires-at` | | Review deadline as a date (2026-12-31) or RFC3339 timestamp |
| `--occurrence` | | Occurrence id to anchor the disposition on (from 'ankra security finding \<id>') |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--policy` | | Existing policy id to re-preview instead of an occurrence |
| `--scope` | `organisation_addon` | Selector scope: organisation\_addon, workload or image; use workload or image when no add-on owns the occurrence's image |

## ankra security dispositions revoke

Revoke one policy. Every occurrence it covered returns to the actionable
set immediately. `--reason` is required and is what the audit trail keeps.
Needs the security.manage permission; asks for confirmation unless `--yes`.

```bash theme={null}
ankra security dispositions revoke <policy-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the disposition is withdrawn (required, kept for audit) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security dispositions update

Edit one policy's reason, review deadline (`--expires-at`) or fix trigger
(`--expire-when-fix-available`). Members left unset stay as they are. Needs
the security.manage permission; the write asks for confirmation unless
`--yes` is passed.

```bash theme={null}
ankra security dispositions update <policy-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--expire-when-fix-available` | `false` | Whether a fixed version ends the disposition |
| `--expires-at` | | New review deadline as a date (2026-12-31) or RFC3339 timestamp; a deadline cannot be cleared once set |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | New reason |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security enable-baseline

Install the platform's security baseline on one cluster: Trivy Operator for
vulnerability, SBOM and compliance reports, plus the pod-security policy
add-ons in audit mode. The stack is committed to the cluster's GitOps
repository and rolled out by the platform; findings appear once the first
scan completes. Asks for confirmation unless `--yes`.

```bash theme={null}
ankra security enable-baseline [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security finding

Show one finding: its CISA KEV listing and deadline, EPSS probability,
occurrence counts by disposition, and every active occurrence.

The detail lists active occurrences only. Pass `--status` resolved to see
where the finding was fixed, `--cluster` to narrow to one cluster, and
`--page`/`--page-size` to walk a large set; any of these switches the table to
the paged occurrence listing.

```bash theme={null}
ankra security finding <finding-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | List only the occurrences on one cluster (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Occurrence page number |
| `--page-size` | `50` | Occurrences per page (max 100) |
| `--status` | | List occurrences in one scan state: active or resolved (the detail alone shows active ones) |

## ankra security findings

List the organisation's logical findings (one row per CVE and package,
deduplicated across clusters and workloads).

By default the list is the actionable set (open and acknowledged findings)
sorted by exploitability. Narrow it with `--known-exploited` to the CVEs CISA
lists as exploited in the wild, or with `--severity`, `--status`, `--fixable`,
`--cluster`, `--addon` and `--namespace`.

Examples:

```bash theme={null}
ankra security findings --known-exploited
ankra security findings --severity critical --fixable true --sort epss
ankra security findings --cluster production --status any -o json
```

```bash theme={null}
ankra security findings [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--addon` | | Only findings attributed to one add-on (slug) |
| `--cluster` | | Only findings observed on one cluster (name or id) |
| `--fixable` | `any` | Fix availability: true, false or any |
| `--known-exploited` | `false` | Only CVEs CISA lists as exploited in the wild (KEV) |
| `--namespace` | | Only findings observed in one namespace |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `25` | Findings per page (max 100) |
| `--search` | | Match CVE id, package name or title |
| `--severity` | `[]` | Severity filter, repeatable: critical, high, medium, low, unknown |
| `--sort` | `exploitability` | Sort key: exploitability, epss, known\_exploited, severity, first\_seen\_at, last\_seen\_at, affected\_clusters, occurrences, package\_name, cve\_id |
| `--status` | `[open,acknowledged]` | Status filter, repeatable: open, acknowledged, accepted\_risk, resolved, or any |

## ankra security history

List a cluster's daily security snapshots for the last `--days` days (default
90, the platform clamps to 1..365): findings by severity, what is actionable
once dispositions are applied, the workloads and namespaces covered and the
risk score, oldest first, with a one-line trend between the first and last
snapshot. A day the scanner recorded no snapshot for is simply absent - it
never reads as zero findings.

```bash theme={null}
ankra security history [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `--days` | `90` | Window in days (1..365) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security namespaces

Break the fleet's findings down the way a platform team owns it: cluster,
then namespace. Each row carries the scanned workloads and images in the
namespace, the pods the cluster runs there right now, the actionable
findings by severity and the known-exploited count. Cluster-scoped reports
(node and control-plane images) keep a row of their own so the rows still
add up to the cluster.

Drill further with 'ankra security pods `--cluster` \<cluster> `--namespace` \<ns>'.

```bash theme={null}
ankra security namespaces [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only namespaces on one cluster (name or id) |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Namespaces per page (max 100) |
| `--search` | | Match namespace or cluster name |
| `--sort` | `actionable` | Sort key: actionable, severity, known\_exploited, fixable\_severe, workloads, images, pods, observed, namespace, cluster\_name, last\_scan |

## ankra security network-exposure

Score one cluster's NetworkPolicies per direction, 0-100 with higher being
tighter: the share of admitting rules that admit a broader peer set than a
named identity, and the workloads no policy protects at all. A cluster
with no workloads has nothing to score and reads n/a, not 100.

```bash theme={null}
ankra security network-exposure [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security overview

Fleet security summary: totals, CISA KEV exposure, scanner coverage and remediation candidates

```bash theme={null}
ankra security overview [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--addon` | | Scope the overview to one add-on (slug) |
| `--cluster` | | Scope the overview to one cluster (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security pod

Show one running pod with the findings of the scanned workload container
behind each of its containers, the CISA KEV exposure, and whether each
container's image has a bill of materials.

A container the scanner has no report for is marked "not scanned", which is
not the same as clean. Open the image behind a container with
'ankra security sbom image \<digest>' and its CVEs with
'ankra security sbom findings \<digest>'.

```bash theme={null}
ankra security pod <namespace> <pod-name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster (name or id); required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security pods

List the pods a namespace runs right now with the findings of the scanned
workload container behind each of their containers. The owner chain is
resolved one level up (Pod -> ReplicaSet -> Deployment, Pod -> Job -> CronJob),
so narrow to one workload with `--workload-uid` or `--workload-kind`/`--workload-name`.

A container the scanner has no report for is marked "not scanned", which is
not the same as clean.

```bash theme={null}
ankra security pods [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster (name or id); required |
| `--namespace` | | The namespace; required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Pods per page (max 100) |
| `--workload-kind` | | With `--workload-name`: only pods owned by this workload kind |
| `--workload-name` | | Only pods owned by the workload with this name |
| `--workload-uid` | | Only pods owned by the workload with this uid |

## ankra security policy-mode

Set the cluster's pod-security policy mode. audit records violations
without blocking; enforce rejects non-compliant workloads at admission; off
uninstalls the Kyverno policy engine from the cluster (its admission
webhook and reports controller are what load a small control plane) while
native pod security keeps observing in audit - audit or enforce afterwards
do not reinstall it. Every mode asks for confirmation; `--yes` skips the
prompt. The change is committed to the cluster's GitOps repository and
rolled out by the platform.

```bash theme={null}
ankra security policy-mode <audit|enforce|off> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security report-schedule

Show one cluster's scheduled security report - weekly or monthly, who
receives it, whether it is enabled, and when it was last sent and is next
due. A cluster without a schedule reads "not configured". Use
"report-schedule set" to create or change it and "report-schedule send" to
queue one now.

```bash theme={null}
ankra security report-schedule [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security report-schedule send

Queue the cluster's security report for immediate delivery to the
schedule's recipients. Asks for confirmation unless `--yes`.

```bash theme={null}
ankra security report-schedule send [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security report-schedule set

Create or replace the cluster's scheduled security report. `--frequency` is
weekly or monthly; `--recipient` is repeatable, at most 20 addresses, and at
least one is required while the schedule is enabled. `--disabled` keeps the
schedule but pauses sending. Asks for confirmation unless `--yes`.

```bash theme={null}
ankra security report-schedule set [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `--disabled` | `false` | Store the schedule paused instead of enabled |
| `--frequency` | | weekly or monthly, required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--recipient` | `[]` | Recipient email address (repeatable, at most 20) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra security sbom

List every package the scanner found in the fleet's container images,
grouped by name, version and ecosystem, with how many images, workloads and
clusters carry it and the findings that name that exact package and version.
Search a package to answer "where do we run this" without a rescan.

The bill of materials is opt-in per cluster: set the security baseline input
trivy\_sbom\_generation\_enabled to true on a cluster with control-plane
headroom. The coverage line says how many scanned clusters publish one.

Subcommands list the images ('ankra security sbom images') and open one
image's full component list ('ankra security sbom image \<digest or reference>').

```bash theme={null}
ankra security sbom [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only packages in images running on one cluster (name or id) |
| `--image` | | Only packages in one image (digest or reference) |
| `--license-risk` | `[]` | Licence tier filter, repeatable: network\_copyleft (AGPL, SSPL, EUPL, OSL), source\_available (BUSL, Elastic, Commons Clause), copyleft (GPL), weak\_copyleft (LGPL, MPL, EPL), permissive, unknown |
| `--namespace` | | Only packages in images running in one namespace |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Components per page (max 100) |
| `--search` | | Match package name or package URL |
| `--sort` | `images` | Sort key: images, workloads, clusters, vulnerable, actionable, license\_risk, name, version, package\_type |
| `--type` | `[]` | Ecosystem filter, repeatable: deb, apk, rpm, npm, pypi, golang, maven, ... |
| `--vulnerable` | `any` | Findings filter: true (a finding names the package), false or any |
| `--workload-kind` | | Only packages in images run by workloads of this kind (Deployment, StatefulSet, DaemonSet, CronJob, ...) |
| `--workload-name` | | Only packages in images run by the workload with this name; combine with `--workload-kind` to pin one workload |

## ankra security sbom component

Follow one exact package - the name, `--version` and `--type` a `security sbom` row shows - to the images whose bill of materials names it, every workload container currently running those images, and the clusters they run on.

```bash theme={null}
ankra security sbom component <name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only the images, workload containers and clusters on one cluster (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--type` | | The ecosystem the component list shows (deb, apk, rpm, npm, pypi, golang, maven, ...); required |
| `--version` | | The exact installed version the component list shows; omit when the list shows none |

## ankra security sbom containers

List every container the resource cache says is running on the scoped
clusters, init containers included, each joined to the bill of materials of
the image it runs - or marked ABSENT when the scanner has none for it.

An absent bill of materials is a state to act on, not an empty image: the
cluster may have SBOM generation switched off, the scanner may not be able
to pull from the image's registry, or the tag rolled since the last scan.
Absent rows sort first by default; `--status` absent lists only them.

The inventory line counts the scope (cluster, namespace, workload) before
`--status` and `--search` narrow the rows, so it holds while you drill.

```bash theme={null}
ankra security sbom containers [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | One cluster (name or id); omit for every live cluster |
| `--namespace` | | Only containers in one namespace |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Containers per page (max 100) |
| `--search` | | Match image, container, pod, workload or namespace |
| `--sort` | `status` | Sort key: status (absent first), image, container, pod, namespace, workload, cluster\_name, components, last\_seen\_at |
| `--status` | `any` | Bill of materials filter: present, absent or any |
| `--workload-kind` | | Match the resolved workload, its direct owner, or 'pod' for bare pods |
| `--workload-name` | | Match the resolved workload, its direct owner, or the pod name |

## ankra security sbom export

Download one image's bill of materials, rebuilt from the components the
platform stores: a CycloneDX 1.5 JSON document by default (what
Dependency-Track, Grype and licence scanners ingest) or a flat CSV with
`--format` csv. Every component is included, unpaged.

The document goes to the file the platform names (repository\_tag.cdx.json)
in the current directory, to `--output-file`, or to standard output with
`--output-file` -.

Example:

```bash theme={null}
ankra security sbom export sha256:18ed3a...  --format csv --output-file backend.csv
```

```bash theme={null}
ankra security sbom export <digest or reference> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--force` | `false` | Overwrite the target file if it already exists |
| `--format` | `cyclonedx` | Document format: cyclonedx or csv |
| `--output-file` | | Where to write the document; the platform's file name in the current directory by default, - for standard output |

## ankra security sbom findings

List every CVE the scanner names on one image: one row per CVE and
installed package version, aggregated across the containers running the
image, with the fixed version when one exists, the CISA KEV listing and EPSS
probability, and the worst disposition across its occurrences.

The image is identified the way the inventories list it: a sha256 digest, or
the repository:tag reference when the scanner knew no digest. An image
without a bill of materials still answers - the CVEs come from the
vulnerability reports - and the header says ABSENT so the gap is visible.

The summary line totals the image before `--search` and `--severity` narrow the
rows. Read one CVE in full with ankra security finding \<finding id>.

```bash theme={null}
ankra security sbom findings <digest or reference> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Vulnerabilities per page (max 100) |
| `--search` | | Match CVE id, package name or title |
| `--severity` | `[]` | Severity filter, repeatable: critical, high, medium, low, unknown |
| `--sort` | `exploitability` | Sort key: exploitability, severity, epss, cve\_id, package\_name, last\_seen\_at, occurrences |

## ankra security sbom image

One image's bill of materials: its identity, the workloads running it and every component

```bash theme={null}
ankra security sbom image <digest or reference> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--license-risk` | `[]` | Licence tier filter, repeatable: network\_copyleft, source\_available, copyleft, weak\_copyleft, permissive, unknown |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `100` | Components per page (max 100) |
| `--search` | | Match package name or package URL |
| `--sort` | `vulnerable` | Sort key: vulnerable, actionable, license\_risk, name, version, package\_type |
| `--type` | `[]` | Ecosystem filter, repeatable |

## ankra security sbom images

Images with a bill of materials: OS, component count, where they run and their findings

```bash theme={null}
ankra security sbom images [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Only images running on one cluster (name or id) |
| `--namespace` | | Only images running in one namespace |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `50` | Images per page (max 100) |
| `--search` | | Match image reference, digest or OS |
| `--sort` | `actionable` | Sort key: actionable, known\_exploited, workloads, clusters, components, image\_ref, generated\_at, last\_seen\_at |
| `--workload-kind` | | Only images run by workloads of this kind (Deployment, StatefulSet, DaemonSet, CronJob, ...) |
| `--workload-name` | | Only images run by the workload with this name; combine with `--workload-kind` to pin one workload |

## ankra security stack

Show one stack the way its Security tab does: attribution scope, the findings
attributed to it, the CVEs CISA lists as exploited, the bill of materials of
its containers, and every member (add-on or manifest) with the posture of the
workloads it resolved to.

Below the members come the Kubernetes workloads each member deploys, with
their pods, scan state, severe actionable findings and SBOM coverage, so the
path from an Ankra resource to a pod is one read. Open a pod with
'ankra security pod \<namespace> \<pod-name>'.

```bash theme={null}
ankra security stack <stack-name> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster (name or id); required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security stacks

List every stack on a cluster with the posture its own Security tab shows:
attribution status, scope, actionable and known-exploited findings and the
bill-of-materials coverage of its containers, riskiest first, plus a closing
"outside any stack" row for everything no stack owns, so the rows add up to
the cluster.

A stack whose members matched no workload is reported unmatched, which is not
the same as clean. Open one stack with 'ankra security stack \<name>'.

```bash theme={null}
ankra security stacks [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster (name or id); required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security violations

Read one cluster's pod-security policy results: the stored policy mode
(audit or enforce; none when the policy add-on is not installed), the
pass/fail/warn totals and each policy with its worst namespaces, plus the
platform's own evaluation of the cluster's workloads from the resource
cache, which is present whether or not the policy engine runs.

```bash theme={null}
ankra security violations [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster (name or id), required |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra security workloads

List the fleet's scanned workload containers, riskiest first. Each row
carries the observed and actionable severity counts, what is acknowledged
or accepted, the fixable severe count and how many of its CVEs CISA lists
as exploited.

The filters are the findings list's. `--sort` defaults to risk\_score.

Examples:

```bash theme={null}
ankra security workloads --known-exploited
ankra security workloads --cluster production --namespace payments
ankra security workloads --addon ingress-nginx --sort last_scan --order asc
```

```bash theme={null}
ankra security workloads [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--addon` | | Only workloads attributed to one add-on (slug) |
| `--cluster` | | Only workloads observed on one cluster (name or id) |
| `--fixable` | `any` | Fix availability: true, false or any |
| `--known-exploited` | `false` | Only CVEs CISA lists as exploited in the wild (KEV) |
| `--namespace` | | Only workloads observed in one namespace |
| `--order` | `desc` | Sort order: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `25` | workloads per page (max 100) |
| `--search` | | Match CVE id, package name or title |
| `--severity` | `[]` | Severity filter, repeatable: critical, high, medium, low, unknown |
| `--sort` | `risk_score` | Sort key: risk\_score, priority, severity, known\_exploited, observed, actionable, fixable\_severe, last\_scan, workload\_name, image\_ref, cluster\_name, addon\_attribution |
| `--status` | `[open,acknowledged]` | Status filter, repeatable: open, acknowledged, accepted\_risk, resolved, or any |


# ankra services
Source: https://docs.ankra.ai/reference/cli/services

Set up, inspect, disconnect and retire managed services (PostgreSQL, Valkey, OpenSearch, ...)

## ankra services

Set up, inspect and retire managed services: PostgreSQL, Valkey, OpenSearch,
VictoriaMetrics, VictoriaLogs and the other engines in the service catalogue,
run on your own cluster as reviewed, health-checked platform services.

A service is set up in three steps:

1. Pick a package from the catalogue:   ankra services packages list
2. Bind the application namespace that
   will use the service:                 ankra services consumers bind `--application` \<a> `--cluster` \<c> `--namespace` \<ns>
3. Review and confirm the setup:         ankra services setup \<name> `--package` postgresql `--cluster` \<c> `--consumer` \<id>

Declaring where a cluster is ('ankra services policy set') is optional: do it
when services must keep data within a data boundary.

Setup, retirement and disconnecting an application are two-step on the
platform. A review is prepared first: the platform resolves a plan, stores it
with a digest for ten minutes, and changes nothing. The plan is shown, and
only confirming it by its digest sets the service up, removes it or
disconnects the application. Every confirmation asks first; `--yes` skips the
question for scripts. Retiring a service deletes its data, so delete also
needs `--acknowledge-data-loss`. 'ankra services disconnect' takes one
application off a service that keeps running for the others, and deletes
nothing.

An application namespace on the service's own cluster receives the connection
once the service is running: a \<service>-connection Secret in its namespace,
copied inside the cluster, which its workloads read as environment variables
(DATABASE\_URL, REDIS\_URL, NATS\_URL, ...). While none of the application's
running pods reads the Secret, Ankra writes it without a redeploy; otherwise
Ankra leaves it to the application's next deploy, which rolls the pods that
read it together. Workloads deployed before the service was connected usually read
it after their next deploy; 'ankra services get' says when they do not. An
application on another cluster is not connected for you.

'ankra services list' and 'ankra services get \<name>' show each service's
deployment state, health, readiness (a consumer-path canary connects with the
generated credentials, for every engine) and connection: its endpoints, the
Secret holding its credentials, and how each consumer receives them.
Credential values are never shown; they stay in the cluster.

**Examples**

```bash theme={null}
ankra services packages list
ankra services setup orders-db --package postgresql --cluster prod --consumer 5b1f0c7e-...
ankra services list
ankra services get orders-db
ankra services disconnect orders-db --application storefront
ankra services delete orders-db --acknowledge-data-loss
```

## ankra services consumers

Bind, list and unbind consumers: the application namespaces a service is set up for.

A consumer is one application's namespace on one cluster, with a stable id.
Setup takes one or more consumer ids (`--consumer`), and the plan records each
with the cluster policy it was resolved against. A binding normally resolves
to the application's installation on that cluster; `--allow-planned` binds a
namespace the application is not installed in yet. A binding a service still
uses cannot be unbound: disconnect the application from the service first
('ankra services disconnect \<service> `--consumer` \<id>'), or retire the service.

## ankra services consumers bind

Bind an application's namespace on a cluster as a service consumer and print
its consumer id, which 'ankra services setup `--consumer`' takes.

The application must be installed in that namespace unless `--allow-planned`
is given. A binding is created once per application, cluster and namespace;
changing an existing one needs `--revision` with its current revision
('ankra services consumers list `--application` \<app>' shows it); a setting
not given on the command line keeps the binding's current value. Binding
deploys nothing. Once a service set up for this consumer is running on the
same cluster, Ankra delivers its connection: without a redeploy while none of
the application's running pods reads it, otherwise it is left to the
application's next deploy. 'ankra services get \<service>' shows its pickup.

```bash theme={null}
ankra services consumers bind [flags]
```

**Examples**

```bash theme={null}
ankra services consumers bind --application orders --cluster prod --namespace orders
ankra services consumers bind --application orders --cluster prod --namespace orders --allow-planned
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allow-planned` | `false` | Bind even though the application is not installed in the namespace yet |
| `--application` | | The application that will consume the service (name or id) |
| `--cluster` | | The cluster the application runs on (name or id; default: the selected cluster) |
| `--local-only` | `false` | The consumer may only use a service on its own cluster |
| `--namespace` | | The application's namespace on that cluster |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--revision` | `0` | The current revision of the binding being changed (omit to create one) |

## ankra services consumers get

Show a consumer binding resolved as setup would resolve it: the cluster's
declared region and data boundary, the policy and binding revisions, and the
application installation it binds (none for a planned binding).

```bash theme={null}
ankra services consumers get <consumer-id> [flags]
```

**Examples**

```bash theme={null}
ankra services consumers get 5b1f0c7e-0d7a-4c55-a6f4-2f1f4a9b1c11
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services consumers list

List an application's consumer bindings as last saved: each binding's id (what
setup's `--consumer` takes), cluster, namespace and revision. Bindings on
clusters you cannot read are not listed.

```bash theme={null}
ankra services consumers list [flags]
```

**Examples**

```bash theme={null}
ankra services consumers list --application orders
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | The application (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services consumers unbind

Remove a consumer binding: the application namespace stops being a consumer
services can be set up for. Nothing is deployed or removed on any cluster.

A binding a service still uses is kept. Disconnect the application from the
service first ('ankra services disconnect \<service> `--consumer` \<id>'), or
retire the service ('ankra services delete'); then unbind it. A setup review
still pending that names the binding can no longer be confirmed.

The platform removes a binding only at the revision you last read. Without
`--revision` the current one is read from the binding. A binding whose
application or cluster has since been removed can still be unbound, but it can
no longer be read by id: pass `--revision` with the revision 'ankra services
consumers list `--application` \<application>' shows. Asks first; `--yes` skips the
question.

```bash theme={null}
ankra services consumers unbind <consumer-id> [flags]
```

**Examples**

```bash theme={null}
ankra services consumers unbind 5b1f0c7e-0d7a-4c55-a6f4-2f1f4a9b1c11
ankra services consumers unbind 5b1f0c7e-0d7a-4c55-a6f4-2f1f4a9b1c11 --revision 3 --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--revision` | `0` | The binding's current revision (default: read from the binding) |
| `-y`, `--yes` | `false` | Remove without asking |

## ankra services delete

Retire a managed service, in two steps, deleting its data.

First a retirement review is prepared: the platform resolves what retiring
removes and keeps - the service's stack and its members, its namespace with
everything in it (objects it did not create are listed), every volume claim
with the reclaim policy that decides its data, the consumers it is
disconnected from and the shared operators it keeps - and stores that plan
with a digest for ten minutes. Preparing changes nothing on the cluster. The
plan is shown, and the service is retired only when you confirm it: at the
prompt, or with `--yes`.

Retiring deletes the namespace, its volume claims and its Secrets, generated
credentials included, and no export is offered; restore points stay in their
backup vault under its retention. A volume whose reclaim policy is Retain
keeps its data until someone removes it, and the settled retirement names it.
So delete always needs `--acknowledge-data-loss`, before anything is prepared.

A retirement review you prepared earlier that is still open (for example one
whose answer was lost) is resumed instead of preparing another; `--new-review`
prepares a fresh one. `--review-only` stops after the review and prints the
command that confirms it. `--wait` follows the retirement until it settles.

```bash theme={null}
ankra services delete <service> [flags]
```

**Examples**

```bash theme={null}
ankra services delete orders-db --acknowledge-data-loss
ankra services delete orders-db --acknowledge-data-loss --review-only
ankra services delete orders-db --cluster prod --acknowledge-data-loss --yes --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--acknowledge-data-loss` | `false` | Acknowledge that retiring deletes the service's data (required) |
| `--cluster` | | The cluster the service runs on, when its name is not unique (name or id) |
| `--new-review` | `false` | Prepare a new retirement review even if one of yours is still open |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--review-only` | `false` | Prepare and show the retirement review, but do not confirm it |
| `--timeout` | `30m0s` | How long `--wait` follows the retirement |
| `--wait` | `false` | Follow the retirement until it settles; exit non-zero unless it settled retired |
| `-y`, `--yes` | `false` | Confirm the reviewed retirement without asking |

## ankra services disconnect

Disconnect one application environment from a managed service. The service
keeps running for its other applications, and nothing is deleted: the service,
its data and its credentials stay.

It is two steps on the platform. First a disconnection review is prepared: the
platform works out what disconnecting does and stores that plan with a digest
for ten minutes. Preparing changes nothing. The review is shown in the
platform's own words:

```text theme={null}
Variables         the variables the application stops receiving (DATABASE_URL,
                  ...) and, when another service of the same kind is
                  connected, who gives the conventional names from now on
Credential        every application of a service shares one credential
                  today, so it is not revoked: the application keeps the
                  password it has. What that cannot guarantee, and how to
                  make sure the application can no longer authenticate
                  (rotate the password, for every application)
Secret            the connection Secret in the application's namespace,
                  which Ankra keeps until no pod reads it
Workloads         the deployed workloads that read it: those Ankra attached
                  it to roll on the next deploy, those that refer to it by
                  hand must be changed by a person
Network           whether the namespace loses access to the service's port
                  (--keep-network-access keeps it)
Timing            the application keeps working until it is deployed again
What stays        what is left in place afterwards
```

The application is disconnected only when you confirm the review: at the
prompt, or with `--yes`. Without a terminal to ask on, `--yes` is required.
`--review-only` shows the review and confirms nothing.

`--application` names the application, and `--environment` the environment when
the application uses the service from more than one. `--consumer` names one
consumer by its id instead ('ankra services get \<service>' lists them), for
example a namespace no environment is deployed to.

When the service gives the application its conventional connection names
(DATABASE\_URL, REDIS\_URL, ...) and another service of the same kind is
connected too, the review asks who gives them from now on. `--names-from`
\<service> chooses that service and `--names-from` none chooses nobody; without it
the review is shown and nothing is confirmed.

'ankra services get \<service>' shows the disconnection until it has finished.

```bash theme={null}
ankra services disconnect <service> [flags]
```

**Examples**

```bash theme={null}
ankra services disconnect orders-db --application storefront
ankra services disconnect orders-db --application storefront --environment staging --review-only
ankra services disconnect orders-db --application storefront --names-from orders-db-v2 --yes
ankra services disconnect orders-db --consumer 5b1f0c7e-0d7a-4c55-a6f4-2f1f4a9b1c11 --keep-network-access -o json --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | The application to disconnect (name or id) |
| `--cluster` | | The cluster the service runs on, when its name is not unique (name or id) |
| `--consumer` | | The consumer to disconnect, by id ('ankra services get' lists them), instead of `--application` |
| `--environment` | | The application's environment, when it uses the service from more than one (name or id) |
| `--keep-network-access` | `false` | Keep the application's namespace allowed on the service's port |
| `--names-from` | | When the review asks: the connected service (name or id) that gives the conventional connection names (DATABASE\_URL, ...) from now on, or none |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--review-only` | `false` | Prepare and show the disconnection review, but do not confirm it |
| `-y`, `--yes` | `false` | Confirm the reviewed disconnection without asking |

## ankra services get

Show one managed service by name or id: its package, cluster and location, its
deployment state, health and readiness with the evidence behind each, how it
is reached (endpoints and the Secret holding its credentials), the consumers
it was set up for with how each receives the connection, the applications
being disconnected from it, and the latest retirement if one was confirmed.

A consumer on the service's cluster receives the connection as a
\<service>-connection Secret in its namespace, read as environment variables,
whose names are listed. Its delivery reads delivered, pending (not delivered
yet; Pickup says what it waits for), unsupported (for example a consumer on
another cluster, which needs the values set by hand) or unknown.

Pickup says how far the application is from running with the connection:

```text theme={null}
waiting_for_service  the service has no credentials yet; Ankra delivers the
                     connection once it has
delivering           no running pod reads it, so Ankra is writing it without
                     a redeploy or restart
holder_gone          waits for you to choose which service provides the
                     standard names (DATABASE_URL, ...)
redeploy_needed      Ankra leaves it to a deploy; a deploy usually writes
                     it and connects the workloads to it, but not always
                     (the delivery reason says what is needed)
restart_needed       running pods started before it arrived; restart them
                     to pick it up (Ankra does not restart them)
in_use               every running pod that reads it has it
```

A value not listed here comes from a newer platform and is shown as sent.
"Defined twice" lists the connection's variables that the application's
workloads also get from another source. Ankra holds back a connection that
is not delivered yet until that is resolved; the delivery reason says how.

An application being disconnected ('ankra services disconnect') is no longer
one of the consumers; until the disconnection finishes it is listed under
Disconnecting, with its phase:

```text theme={null}
draining   Ankra keeps the connection Secret until no pod and no deployed
           workload reads it; a deploy of the application rolls the
           workloads Ankra attached it to
removing   the connection Secret is being removed
revoking   the namespace's access to the service's port is being removed,
           where the review said it would be
```

A phase not listed here comes from a newer platform and is shown as sent.

The connection names the Secret and its keys only. Credential values are never
shown here; they stay in the cluster.

A name that runs on more than one cluster needs `--cluster`.

```bash theme={null}
ankra services get <service> [flags]
```

**Examples**

```bash theme={null}
ankra services get orders-db
ankra services get orders-db --cluster prod -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster the service runs on, when its name is not unique (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services list

List the organisation's managed services: each with its cluster, package,
deployment state, health and readiness.

Deployment state is the recorded operation progress (accepted, deploying,
verification\_pending, deployment\_failed, ...), not current health. Health is
what the platform last observed from the cluster (serving, progressing,
degraded, unknown). Readiness says whether a consumer can use the service: a
canary connects with the generated credentials (ready, verifying, degraded,
stale); a service no canary covers, or whose cluster's agent is too old to
run one, reads unverified.

`--application` keeps the services an application uses: those whose reviewed
plan names one of the application's namespaces as a consumer. The
application is given by name or id, and a Used by column says which of its
environments each service serves (or the namespace, where the application is
not deployed yet).

Retired services keep their record; `--include-released` lists them too.

```bash theme={null}
ankra services list [flags]
```

**Examples**

```bash theme={null}
ankra services list
ankra services list --cluster prod
ankra services list --application storefront
ankra services list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--application` | | Only services this application uses (name or id) |
| `--cluster` | | Only services on this cluster (name or id) |
| `--include-released` | `false` | Also list retired services |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services packages

Browse the service catalogue: the immutable package versions this organisation
may set up, Ankra's own (PostgreSQL, Valkey, OpenSearch, ...), any shared
with it, and its own. 'init' and 'publish' turn one of your stack profiles
into a package that connects to applications like Ankra's own.

Being listed is not being deployable: setup re-checks access and the pinned
profile when the review is prepared.

## ankra services packages collisions

Read a running demo of a stack profile and check whether two services set up
from a package built on it could run on the same cluster: a cluster-scoped
object (a ClusterRole, a CRD, a webhook, a StorageClass) whose name does not
change with the service's namespace would be claimed by both. It also lists
the Services and Secrets whose names do change with it, which a package's
connection cannot name as fixed values.

Exits 0 only when every kind was read and nothing collides; collisions exit 1
with the objects named, and a check that could not read everything (the
verdict unknown) exits 1 with the reason, so it never reads as no collision.

```bash theme={null}
ankra services packages collisions [flags]
```

**Examples**

```bash theme={null}
ankra services packages collisions --profile <profile-id> --demo <workspace-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--demo` | | id of the running demo (its workspace id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--profile` | | id of the stack profile the demo runs |

## ankra services packages get

Show a package version's contract: the modes it can run in, the parameters a
setup may choose (with their bounds and defaults), the secret inputs it needs
and the outputs it publishes. The package is a name, name\@version or id.

```bash theme={null}
ankra services packages get <package> [flags]
```

**Examples**

```bash theme={null}
ankra services packages get postgresql
ankra services packages get postgresql@1.0.0 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services packages init

Write a service package (contract schema 2) for one version of a stack profile
this organisation owns, so the services it deploys can be set up from the
catalogue and connected to applications like Ankra's own.

The skeleton pins the profile version and names the protocol consumers speak
(nats, opensearch, postgres, redis, s3, victorialogs, victoriametrics). Before publishing, fill in
what only you know about the engine the profile deploys:

```text theme={null}
connection.endpoints[0].service  the Service consumers connect to
connection.endpoints[0].port     its port
connection.secret_name           the Secret holding its credentials
connection.fields                which key of that Secret holds each field
```

Publication refuses the package until these are filled in.

To make a service from one Helm chart rather than a stack profile, pass
`--addon` with `--registry` and `--chart-version` instead of `--profile` and
`--profile-version`: init first creates a stack profile holding that chart
alone (installed into a namespace named after each service), then writes the
package pinned to it.

With `--generate-secret`, that profile also generates the service's
credentials: a Secret of that name in each service's namespace, created on
the first install and kept unchanged across upgrades. Name its keys with
`--generate-key`: "password" for a random value, "password:48" for a random
value of 48 characters. Random values are generated in the cluster and Ankra
never sees them. "username=app" sets a fixed value, which is stored in the
profile and visible on the command line, so use it only for names (a user or
database name), never for a password. Point the chart at the Secret in
`--values` (most charts take an existing-secret setting); the package's
connection names it already.

```bash theme={null}
ankra services packages init [flags]
```

**Examples**

```bash theme={null}
ankra services packages init --profile <profile-id> --profile-version <version-id> \
  --name dragonfly-cache --protocol redis -f dragonfly-cache.json
ankra services packages init --addon dragonfly --registry dragonfly --chart-version 1.2.0 \
  --values dragonfly-values.yaml --name dragonfly-cache --protocol redis -f dragonfly-cache.json
ankra services packages init --addon postgresql --registry bitnami --chart-version 16.4.2 \
  --generate-secret orders-db-auth --generate-key username=app --generate-key password \
  --values orders-db-values.yaml --name orders-db --protocol postgres -f orders-db.json
ankra services packages publish -f dragonfly-cache.json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--addon` | | make the service from this Helm chart instead of a stack profile |
| `--capability` | | what the package provides (defaults to the protocol's usual one) |
| `--chart-version` | | the chart version `--addon` pins |
| `-f`, `--file` | | write the skeleton to this file instead of standard output |
| `--generate-key` | `[]` | a key of `--generate-secret`: key (random), key:length (random of that length) or key=value (a fixed, non-secret name such as a user); repeatable |
| `--generate-secret` | | with `--addon`, a Secret of this name the profile generates in each service's namespace |
| `--name` | | package name (a DNS label, for example dragonfly-cache) |
| `--profile` | | id of the stack profile the package deploys |
| `--profile-version` | | id of the profile version to pin |
| `--protocol` | | wire protocol consumers speak: nats, opensearch, postgres, redis, s3, victorialogs, victoriametrics |
| `--registry` | | the Helm registry `--addon` comes from (as named in Ankra) |
| `--values` | | a values file for the `--addon` chart |
| `--version` | `1.0.0` | package version (semantic version) |

## ankra services packages list

List the service packages this organisation can set up: each version's name,
capability (database, cache, search, metrics, logs, ...), publisher and id.
Pass the name, name\@version or id to 'ankra services setup `--package`'.

```bash theme={null}
ankra services packages list [flags]
```

**Examples**

```bash theme={null}
ankra services packages list
ankra services packages list -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services packages probe

Probe the connection a package file declares against a running demo of its
stack profile, before publishing: Ankra runs the protocol's readiness canary
in the demo's namespace, the same one that verifies a published package.

Without `--wait` the probe is only queued. With `--wait` the command follows it
and exits 0 only when the verdict is passed; failed and unknown (the canary
could not run, or the demo stopped) exit 1 with the reason, and a probe still
running when `--timeout` ends exits 5.

```bash theme={null}
ankra services packages probe [flags]
```

**Examples**

```bash theme={null}
ankra services packages probe --profile <profile-id> --demo <workspace-id> -f dragonfly-cache.json --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--demo` | | id of the running demo (its workspace id) |
| `-f`, `--file` | | package file whose connection is probed (- for standard input) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--profile` | | id of the stack profile the demo runs |
| `--timeout` | `10m0s` | how long `--wait` follows the probe |
| `--wait` | `false` | follow the probe to its verdict; exit 0 only if it passed |

## ankra services packages propose

Read a running demo of a stack profile on the organisation's staging cluster
and propose the connection blocks a service package made from that profile
could declare: one per Service port speaking a protocol Ankra connects
applications to, each field mapped to a key of the Secret that holds the most
of the credentials. Only Service ports and Secret key names are read, never
Secret values, and nothing is tried: probe a proposal with
'ankra services packages probe' before publishing.

With -f, the best complete proposal is written into that package file (made
by 'ankra services packages init'), replacing its connection.

A demo whose namespace could not be observed exits 1 with the reason, so an
unobserved namespace is never read as one with nothing to propose.

```bash theme={null}
ankra services packages propose [flags]
```

**Examples**

```bash theme={null}
ankra services packages propose --profile <profile-id> --demo <workspace-id>
ankra services packages propose --profile <profile-id> --demo <workspace-id> -f dragonfly-cache.json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--demo` | | id of the running demo (its workspace id) |
| `-f`, `--file` | | write the best complete proposal into this package file |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--profile` | | id of the stack profile the demo runs |

## ankra services packages publish

Publish a service package version from its contract document. The document is
sent as written; the platform validates it and refuses it with the path that
failed. A published version is immutable: publishing the same name and version
again with identical content returns it, and different content is refused, so
a change needs a new version.

Publishing makes the package available to set up in this organisation; it does
not make Ankra operate it or qualify it.

```bash theme={null}
ankra services packages publish [flags]
```

**Examples**

```bash theme={null}
ankra services packages publish -f dragonfly-cache.json
ankra services packages init ... | ankra services packages publish -f -
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-f`, `--file` | | package document to publish, or - for standard input |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services policy

Read or declare a cluster's service placement policy: the physical region it
runs in, the data boundary its data may stay within, and whether services on
it are local-only.

This is the organisation's declaration, not verified location evidence. It is
optional: a cluster without one is set up under the platform's default
location (unspecified). Once declared, a setup's region and data boundary
default to it and every setup on the cluster is held to it.

## ankra services policy get

Show a cluster's service placement policy

```bash theme={null}
ankra services policy get [flags]
```

**Examples**

```bash theme={null}
ankra services policy get --cluster prod
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster (name or id; default: the selected cluster) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services policy set

Declare a cluster's service placement policy: the physical region it runs in
(for example eu-north-1), the data boundary its data may stay within (for
example eu) and whether services on it are local-only.

The first declaration creates the policy. Replacing one needs `--revision` with
the revision you reviewed ('ankra services policy get' shows it), so two
people cannot overwrite each other's declaration unseen. Nothing is deployed.

```bash theme={null}
ankra services policy set [flags]
```

**Examples**

```bash theme={null}
ankra services policy set --cluster prod --region eu-north-1 --data-boundary eu
ankra services policy set --cluster prod --region eu-north-1 --data-boundary eu --local-only --revision 1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster (name or id; default: the selected cluster) |
| `--data-boundary` | | Boundary the data may stay within, for example eu |
| `--local-only` | `false` | Services on this cluster serve only consumers on this cluster |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--region` | | Physical region the cluster runs in, for example eu-north-1 |
| `--revision` | `0` | The current revision of the policy being replaced (omit to create one) |

## ankra services retirements

List, read and confirm your own retirements of a service.

'ankra services delete' prepares a retirement review and confirms it. A
review that was prepared with `--review-only`, declined at the prompt or whose
answer was lost stays pending for ten minutes: 'list `--state` pending' finds it
and 'confirm' confirms it instead of preparing another (each person may hold
10 open retirements). 'get' follows a confirmed retirement and, once it
settled, shows what became of every volume.

## ankra services retirements confirm

Confirm one of your pending retirement reviews by its digest. This is the step
that retires the service and deletes its data, so it needs
`--acknowledge-data-loss` as well as a yes at the prompt (or `--yes`).

`--digest` names the digest you reviewed ('delete `--review-only`' prints it); a
review whose digest differs is refused, because it is not the plan you saw.
Without `--digest` the digest of the review shown is the one confirmed.

```bash theme={null}
ankra services retirements confirm <service> <retirement-id> [flags]
```

**Examples**

```bash theme={null}
ankra services retirements confirm orders-db 7d3c1f0a-5b2e-4c9d-8e1f-0a2b3c4d5e6f --digest sha256:9f2c... --acknowledge-data-loss
ankra services retirements confirm orders-db 7d3c1f0a-5b2e-4c9d-8e1f-0a2b3c4d5e6f --acknowledge-data-loss --yes --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--acknowledge-data-loss` | `false` | Acknowledge that retiring deletes the service's data (required) |
| `--cluster` | | The cluster the service runs on, when its name is not unique (name or id) |
| `--digest` | | The digest you reviewed (sha256:...); refused if the review's differs |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `30m0s` | How long `--wait` follows the retirement |
| `--wait` | `false` | Follow the retirement until it settles; exit non-zero unless it settled retired |
| `-y`, `--yes` | `false` | Confirm the reviewed retirement without asking |

## ankra services retirements get

Show one of your retirements: the plan, its progress and what became of the volumes

```bash theme={null}
ankra services retirements get <service> <retirement-id> [flags]
```

**Examples**

```bash theme={null}
ankra services retirements get orders-db 7d3c1f0a-5b2e-4c9d-8e1f-0a2b3c4d5e6f
ankra services retirements get orders-db 7d3c1f0a-5b2e-4c9d-8e1f-0a2b3c4d5e6f -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster the service runs on, when its name is not unique (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services retirements list

List your retirements of a service, newest first

```bash theme={null}
ankra services retirements list <service> [flags]
```

**Examples**

```bash theme={null}
ankra services retirements list orders-db
ankra services retirements list orders-db --state pending
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster the service runs on, when its name is not unique (name or id) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--state` | | Only retirements in this state: pending, expired, in\_progress or settled |

## ankra services reviews

List, read and confirm your own setup reviews.

'ankra services setup' prepares a review and confirms it. A review that was
prepared with `--review-only`, declined at the prompt, or whose answer was lost
stays pending for ten minutes: find it here and confirm it instead of preparing
another (each person may hold 20 open reviews). An expired review needs a new
setup. Reviews are personal: nobody else sees or confirms yours.

## ankra services reviews confirm

Confirm one of your pending setup reviews by its digest. This is the step that
sets the service up.

The review is shown and confirmed after a yes at the prompt, or with `--yes`.
`--digest` names the digest you reviewed (setup `--review-only` prints it); a
review whose digest differs is refused, because it is not the plan you saw.
Without `--digest` the digest of the review shown is the one confirmed. A
review that already expired needs a new 'ankra services setup'.

```bash theme={null}
ankra services reviews confirm <review-id> [flags]
```

**Examples**

```bash theme={null}
ankra services reviews confirm 0b6f2a8e-3a1c-4b8e-9a51-2c7d4f1e9a20 --digest sha256:4e86...
ankra services reviews confirm 0b6f2a8e-3a1c-4b8e-9a51-2c7d4f1e9a20 --digest sha256:4e86... --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--digest` | | The digest you reviewed (sha256:...); refused if the review's differs |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Confirm without asking |

## ankra services reviews get

Show one of your setup reviews

```bash theme={null}
ankra services reviews get <review-id> [flags]
```

**Examples**

```bash theme={null}
ankra services reviews get 0b6f2a8e-3a1c-4b8e-9a51-2c7d4f1e9a20
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra services reviews list

List your setup reviews, newest first

```bash theme={null}
ankra services reviews list [flags]
```

**Examples**

```bash theme={null}
ankra services reviews list
ankra services reviews list --state pending
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--state` | | Only reviews in this state: pending, expired or confirmed |

## ankra services setup

Set up a managed service on a cluster, in two steps.

First a review is prepared: the platform resolves the package, the cluster's
placement policy and every consumer, and stores the plan with a digest for ten
minutes. Preparing changes nothing. The plan is shown, and the service is set
up only when you confirm it: at the prompt, or with `--yes`. The confirmation
carries the digest of the plan you saw, so a plan that changed in between is
refused rather than deployed.

`--review-only` stops after the review and prints the command that confirms it
('ankra services reviews confirm \<id> `--digest` \<digest>'), for a person or a
pipeline that approves separately.

The name becomes the service's namespace on the cluster: lower-case letters,
digits and single hyphens, starting with a letter. Ankra's engines also need
it to be at most 36 characters and not a system namespace (default, kube-*,
ankra*, cert-manager, ...); the platform refuses any other name when the
review is prepared, before anything is stored.

Every setup needs at least one consumer (`--consumer`, from 'ankra services
consumers bind'). The region and data boundary default to the cluster's
placement policy. Parameters (`--param`) default to the package's defaults;
'ankra services packages get \<package>' lists them with their bounds.

Confirming starts the deployment; it is not proof that the service is ready.
Follow it with 'ankra services get \<name>'.

```bash theme={null}
ankra services setup <name> [flags]
```

**Examples**

```bash theme={null}
ankra services setup orders-db --package postgresql --cluster prod --consumer 5b1f0c7e-0d7a-4c55-a6f4-2f1f4a9b1c11
ankra services setup orders-db --package postgresql@1.0.0 --consumer <id> --param storage_gib=20 --param instances=3
ankra services setup orders-db --package postgresql --consumer <id> --review-only
ankra services setup orders-db --package postgresql --consumer <id> --yes -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | The cluster to run the service on (name or id; default: the selected cluster) |
| `--consumer` | `[]` | Consumer binding id the service is for (repeatable; 'ankra services consumers bind') |
| `--data-boundary` | | Data boundary (default: the cluster's placement policy) |
| `--mode` | `customer` | Operating mode: customer (runs on your cluster) or existing |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--package` | | The package to set up: name, name\@version or id ('ankra services packages list') |
| `--param` | `[]` | Package parameter as name=value (repeatable) |
| `--region` | | Physical region (default: the cluster's placement policy) |
| `--review-only` | `false` | Prepare and show the review, but do not confirm it |
| `--secret-reference` | `[]` | Secret input as name=\<credential grant id> (repeatable); values are never accepted |
| `-y`, `--yes` | `false` | Confirm the reviewed plan without asking |


# ankra skills
Source: https://docs.ankra.ai/reference/cli/skills

Install Ankra Agent Skills into your AI coding assistants

## ankra skills

Install the curated Ankra Agent Skills into the AI assistants you use.

The skills teach an agent to follow Ankra's practices for the CLI, getting
started, building and importing clusters (provider, region, instance family),
domains/DNS/TLS, ImportCluster YAML, stacks and addons, applications and their
CI/CD, shipping code end to end through Ankra Pipelines, stack profiles, GitOps, SOPS secrets, Helm registries, observability,
troubleshooting, security, and the AI agent surface.

Claude Code, the Claude app, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI,
OpenCode, Cline, Zed and OpenClaw are supported, plus any assistant that reads
AGENTS.md. With no `--client`, install picks the assistants configured on this
machine; 'ankra skills clients' shows what was detected.

Three things are installed per client:

```text theme={null}
skills     the SKILL.md files themselves
rule       an always-applied instruction making Ankra the default route for
           Kubernetes work, plus an index of the skills for clients that do
           not discover them on their own (skip with --no-rules)
workflows  named multi-step entry points (/ankra-new-cluster,
           /ankra-ship-service, /ankra-triage, ...) for clients with
           slash commands (skip with --no-workflows)
```

Add `--with-hooks` to also install an agent hook that pauses direct kubectl/helm
cluster mutations for confirmation.

```bash theme={null}
ankra skills clients
ankra skills list
ankra skills install
ankra skills install --client all
ankra skills install --client claude-code --client cursor
ankra skills install --client copilot --dir .
ankra skills install --client claude-app
ankra skills install --with-hooks
ankra skills install ankra-cli ankra-gitops
```

## ankra skills clients

List every supported assistant, whether it is configured here, and where
skills would be installed for it. Detection is what `--client` auto (the default)
selects; pass `--dir` \<DIR> to see the repository-scoped locations instead.

```bash theme={null}
ankra skills clients [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--client` | `[]` | assistant to target, repeatable or comma-separated: claude-code, claude-app, cursor, codex, copilot, windsurf, gemini, opencode, cline, zed, openclaw, agents, plus "all" and "auto" (default: the assistants configured here) |
| `--dir` | | install into \<DIR> instead of your home directory (use "." for the current directory) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra skills guard

Read an agent hook event (JSON) from stdin and print a permission decision.

Wired by 'ankra skills install `--with-hooks`' into Cursor's
beforeShellExecution hook and Claude Code's PreToolUse hook. Shell commands
that would mutate a Kubernetes cluster out-of-band (kubectl apply, helm
upgrade, ...) return an "ask" decision explaining the Ankra GitOps workflow;
read-only commands and anything unparseable pass through unchanged.

```bash theme={null}
ankra skills guard [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--format` | `cursor` | hook event format: cursor or claude |

## ankra skills install

Install all skills (default) or only the named ones.

Without `--client`, install targets every assistant configured on this machine
(see 'ankra skills clients'), falling back to Claude Code and Cursor when none
is detected. `--client` all installs everywhere; `--client` \<id> (repeatable, or
comma-separated) picks specific ones.

By default skills install for your user, available in every project. Use
`--dir` \<DIR> to install into a repository instead (`--dir` . for the
current directory) - the right scope for GitHub Copilot, whose instructions
file is per repository.

The Claude app cannot read your filesystem, so `--client` claude-app writes one
uploadable .zip bundle per skill and prints where to upload them.

Install also writes an always-applied rule so the agent treats Ankra as the
default route for Kubernetes work, and - for clients that do not discover
skills on their own - an index naming each skill and its path (skip both with
`--no-rules`). Clients with slash commands additionally get the Ankra workflow
commands (skip with `--no-workflows`). With `--with-hooks` it installs the agent
hook ('ankra skills guard') that intercepts direct kubectl/helm cluster
mutations and asks for confirmation.

```bash theme={null}
ankra skills install [skill ...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--client` | `[]` | assistant to target, repeatable or comma-separated: claude-code, claude-app, cursor, codex, copilot, windsurf, gemini, opencode, cline, zed, openclaw, agents, plus "all" and "auto" (default: the assistants configured here) |
| `--dir` | | install into \<DIR> instead of your home directory (use "." for the current directory) |
| `--force` | `false` | overwrite existing skills without prompting |
| `--no-rules` | `false` | skip the always-applied agent rule and skill index |
| `--no-workflows` | `false` | skip the Ankra workflow commands |
| `--source` | | read skills from a local directory instead of the embedded copy |
| `--with-hooks` | `false` | also install the agent hook that gates direct kubectl/helm cluster mutations |

## ankra skills list

List the available Ankra skills

```bash theme={null}
ankra skills list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--client` | `[]` | assistant to target, repeatable or comma-separated: claude-code, claude-app, cursor, codex, copilot, windsurf, gemini, opencode, cline, zed, openclaw, agents, plus "all" and "auto" (default: the assistants configured here) |
| `--dir` | | install into \<DIR> instead of your home directory (use "." for the current directory) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--source` | | read skills from a local directory instead of the embedded copy |

## ankra skills uninstall

Remove the named skills, or all Ankra skills when none are given.

The client selection works as it does for install, except that `--client` auto
(the default) resolves to the assistants that actually have Ankra skills
installed, so a plain 'ankra skills uninstall' undoes a plain install.

A full uninstall (no skill names) also removes the always-applied rule, the
workflow commands, and the 'ankra skills guard' hook that install added for
each client and scope; uninstalling named skills leaves them in place.

```bash theme={null}
ankra skills uninstall [skill ...] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--client` | `[]` | assistant to target, repeatable or comma-separated: claude-code, claude-app, cursor, codex, copilot, windsurf, gemini, opencode, cline, zed, openclaw, agents, plus "all" and "auto" (default: the assistants configured here) |
| `--dir` | | install into \<DIR> instead of your home directory (use "." for the current directory) |
| `--source` | | read skills from a local directory instead of the embedded copy |


# ankra stack-profiles
Source: https://docs.ankra.ai/reference/cli/stack-profiles

Manage reusable stack profiles

## ankra stack-profiles

Manage organisation-level stack profiles: create them from deployed stacks, list and describe them, apply them to clusters, version and share them, and export or import them as infrastructure-as-code.

## ankra stack-profiles adopt

Record an already-deployed stack as a tracked deployment of a stack profile.

Capturing a profile from a live stack ('create `--stack`', 'save-version
`--stack`') snapshots the contents but does not register the source stack as a
deployment, so the profile reports no deployments and 'rollout' cannot reach
it. Adopt writes that missing record.

Nothing is written to the cluster: no draft, no deploy, no change to the
stack or its members. Only the deployment record appears, after which
'deployments' lists the stack and 'rollout' can update it in place.

Adopt reports how the live stack differs from the version it is adopted at
rather than refusing a stack that has drifted - a stack patched per cluster
since capture has drifted by definition, and that is the case adopt exists
for. Read the report before rolling out: a rollout replaces the stack with
what the version lists, so any member listed under "only on the cluster" is
removed by it once you confirm it with `--confirm-removal` (the platform refuses
the rollout until you do). Pick the version that matches with `--version`, or publish a
version that carries those members first.

```bash theme={null}
ankra stack-profiles adopt [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles adopt so-cilium --stack so-cilium --cluster so-upcloud-production
ankra stack-profiles adopt so-networking --stack so-networking --cluster so-development --version 2
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | | Cluster name or ID the stack runs on |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--set` | `[]` | Bind a parameter recorded on the deployment: name=value (repeatable; not for secrets) |
| `--set-env` | `[]` | Bind a recorded parameter from an environment variable: name=ENV\_VAR (repeatable; secret-safe) |
| `--set-file` | `[]` | Bind a recorded parameter from a file: name=path (repeatable; secret-safe) |
| `--stack` | | Name of the stack already deployed on the cluster |
| `--version` | | Profile version to record the deployment at, as 1 or v1 (defaults to the profile's current version) |

## ankra stack-profiles apply

Apply (instantiate) a stack profile onto a cluster.

By default this creates a reviewable stack DRAFT on the target cluster - nothing is
deployed until you review it in the Ankra dashboard or pass `--deploy`.

Repeat `--cluster` to apply the same version and bindings to several clusters in
one command; a summary table reports each cluster at the end.

Bind profile parameters with `--set` name=value. For secret parameters prefer
`--set-file` name=path or `--set-env` name=ENV\_VAR so the value never appears in your
shell history or process list. Use 'ankra stack-profiles get \<profile-id>' to see
which parameters a profile expects.

```bash theme={null}
ankra stack-profiles apply [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--cluster` | `[]` | Target cluster name or ID (repeatable: apply the same profile to several clusters in one go; defaults to the selected cluster) |
| `--deploy` | `false` | Deploy the stack immediately instead of leaving a draft for review |
| `--dry-run` | `false` | Show the value every input would deploy with (your `--set`, the selected choice, or the default) without creating anything |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--set` | `[]` | Bind a parameter: name=value (repeatable; not for secrets) |
| `--set-env` | `[]` | Bind a parameter from an environment variable: name=ENV\_VAR (repeatable; secret-safe) |
| `--set-file` | `[]` | Bind a parameter from a file: name=path (repeatable; secret-safe) |
| `--stack-name` | | Name for the new stack (defaults to the profile's stack name) |
| `--version` | | Profile version to apply, as 1 or v1 (defaults to the profile's current version) |

## ankra stack-profiles contents

Show what a published profile version actually contains.

Manifests and add-on values are stored base64-encoded, so `export-iac` and
`version` cannot be read or grepped directly. This command decodes them.

With no `--resource`, it lists the add-ons and manifests, reading each
manifest's kind and namespace out of the decoded YAML:

```bash theme={null}
ankra stack-profiles contents opensearch 2
```

`--resource` prints one resource's decoded content, the same way
`ankra cluster manifests get` prints a live manifest:

```bash theme={null}
ankra stack-profiles contents opensearch 2 --resource opensearch-cluster
ankra stack-profiles contents opensearch 2 --resource fluent-bit -o raw
```

`--all` prints every resource as one multi-document YAML stream, which is the
form to audit a whole profile in one pass:

```bash theme={null}
ankra stack-profiles contents opensearch 1 --all | grep -A2 secretKeyRef
```

```bash theme={null}
ankra stack-profiles contents [profile-id|profile-name] <version> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Print every resource as one multi-document YAML stream |
| `-o`, `--output` | | Content format for `--resource`: yaml (decoded, default) or raw (base64) |
| `--resource` | | Print one resource's decoded content by name (manifest or add-on) |

## ankra stack-profiles create

Create a stack profile by snapshotting a deployed cluster stack as
version 1. The source stack's add-ons and manifests become the profile
contents; detected inputs become the profile's parameters.

```bash theme={null}
ankra stack-profiles create [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles create --name postgres-ha --stack postgres --cluster staging \
  --category database --tag postgresql --tag ha --description "Production PostgreSQL"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--category` | `general` | Profile category (e.g. 'database') |
| `--changelog` | | Changelog note for version 1 |
| `--cluster` | | Source cluster name or ID (defaults to the selected cluster) |
| `--description` | | Profile description shown in the catalogue |
| `--include-addon-configurations` | `true` | Carry the source add-ons' values into the profile |
| `--logo-url` | | Logo image URL shown in the catalogue |
| `--name` | | Profile name (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stack` | | Source stack name to snapshot (required) |
| `--tag` | `[]` | Catalogue tag (repeatable) |
| `--visibility` | | Profile visibility: organisation (default) or public |

## ankra stack-profiles delete

Delete a stack profile. Stacks already deployed from it keep running;
the profile stops appearing in the catalogue and can no longer be applied.

```bash theme={null}
ankra stack-profiles delete [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra stack-profiles demo

Launch a demo of a profile on the staging cluster to see what it actually
installs - no cluster of your own required. A demo installs the profile's
add-ons and manifests into one throwaway namespace, quota-bounded so it
cannot crowd the staging cluster, and cleans itself up automatically.

## ankra stack-profiles demo detail

Show a demo's workloads and readiness

```bash theme={null}
ankra stack-profiles demo detail [profile-id|profile-name] <workspace-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles demo launch

Launch a demo of a profile on the staging cluster

```bash theme={null}
ankra stack-profiles demo launch [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles demo launch postgres-ha
ankra stack-profiles demo launch postgres-ha --version v2 --ttl-hours 4 --set replicas=1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--set` | `[]` | Bind a parameter: name=value (repeatable; not for secrets) |
| `--set-env` | `[]` | Bind a parameter from an environment variable: name=ENV\_VAR (repeatable; secret-safe) |
| `--set-file` | `[]` | Bind a parameter from a file: name=path (repeatable; secret-safe) |
| `--ttl-hours` | `0` | Hours before the demo stops itself (defaults server-side) |
| `--version` | | Profile version to demo, as 1 or v1 (defaults to the current version) |

## ankra stack-profiles demo list

List the live demos of a profile

```bash theme={null}
ankra stack-profiles demo list [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles demo logs

Read a demo's pod logs

```bash theme={null}
ankra stack-profiles demo logs [profile-id|profile-name] <workspace-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles demo stop

Stop a demo and clean up its namespace

```bash theme={null}
ankra stack-profiles demo stop [profile-id|profile-name] <workspace-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles deployments

List every stack your organisation deployed from this profile: the target
cluster, the stack, the profile version it runs, and whether a newer
version is available. `--outdated` keeps only the ones behind the current
version; -o json returns the raw records.

```bash theme={null}
ankra stack-profiles deployments [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles deployments hello-fleet
ankra stack-profiles deployments hello-fleet --outdated
ankra stack-profiles deployments hello-fleet -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--outdated` | `false` | Only the deployments behind the current version |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles deprecate

Withdraw a published version so nobody deploys it again. A deprecated
version cannot be made current and cannot be applied to a cluster; stacks
already running it keep running, and 'ankra stack-profiles deployments'
reports which ones are on it.

The reason is one of incompatibility, critical-bug or cve. Use `--note` for
the sentence the platform shows when it refuses the version, such as which
version carries the fix, and repeat `--reference` for the advisories, CVE ids
or issues behind it. Deprecating an already-deprecated version replaces its
reason, note and references.

```bash theme={null}
ankra stack-profiles deprecate [profile-id|profile-name] <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles deprecate postgres-ha v3 --reason cve \
  --note "Fixed in v11; see the advisory." --reference CVE-2026-12345
ankra stack-profiles deprecate postgres-ha 3 --reason critical-bug -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | Sentence shown when the platform refuses the version, e.g. which version fixes it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | Why the version is withdrawn: incompatibility, critical-bug or cve (required) |
| `--reference` | `[]` | Advisory, CVE id or issue URL behind the deprecation (repeatable) |

## ankra stack-profiles diff

Compare two published versions of a profile

```bash theme={null}
ankra stack-profiles diff [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles diff postgres-ha --from v1 --to v2
ankra stack-profiles diff postgres-ha --from 1 --to 3 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--from` | | Version to compare from, as 1 or v1 (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--to` | | Version to compare to, as 1 or v1 (required) |

## ankra stack-profiles drafts

Work with stack profile builder drafts from the terminal.

A draft is the editable working copy behind a profile version: open one from
an existing profile (or from a deployed stack), annotate its parameters with
the titles and descriptions the launch form shows as guidance, and publish it
as the next version.

## ankra stack-profiles drafts annotate

Set a parameter's title and description on a draft. The description is
the guidance the launch form shows under the field, so this is how a profile
author instructs the person filling it in. Publishing the draft makes the
annotations live.

```bash theme={null}
ankra stack-profiles drafts annotate <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--add` | `false` | Declare the input if the draft does not have it, e.g. a choice that sets other inputs and is referenced by no manifest |
| `--default` | | Default value (pass an empty string to clear it) |
| `--description` | | Guidance shown under the field in the launch form |
| `--enum` | | Allowed values, comma separated (implies `--type` enum) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--parameter` | | Parameter name to annotate |
| `--required` | `false` | Whether the input must be set when the profile is used (`--required=false` to relax) |
| `--title` | | Display title for the field (optional) |
| `--type` | | Input type: string, number, boolean or enum |

## ankra stack-profiles drafts create

Open a builder draft: `--profile` edits an existing profile (publishing
creates its next version), `--name` starts a brand-new profile, and
`--source-cluster` with `--source-stack` seeds the draft from a deployed stack.

```bash theme={null}
ankra stack-profiles drafts create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--name` | | Name for a brand-new profile draft |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--profile` | | Existing profile (name or ID) to open a draft on |
| `--source-cluster` | | Cluster (name or ID) to seed the draft from a deployed stack |
| `--source-stack` | | Deployed stack name to seed the draft from (with `--source-cluster`) |

## ankra stack-profiles drafts delete

Discard a builder draft

```bash theme={null}
ankra stack-profiles drafts delete <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles drafts get

Show a draft's parameters and their annotations

```bash theme={null}
ankra stack-profiles drafts get <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles drafts list

List the organisation's open builder drafts

```bash theme={null}
ankra stack-profiles drafts list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles drafts options

Give a draft's input choices, where each choice also answers other inputs.

One "Model size" input with a choice of 8b or 32b can then move the model id,
the context length and the volume size together, so whoever applies the
profile picks one thing instead of keeping four consistent. At apply time the
platform resolves a choice in a fixed order: a value passed with `--set`, then
what the selected choice sets, then the input's own default.

A choice can set any non-secret input that does not offer choices of its own.
Declare a choice input that no manifest references with
'drafts annotate \<draft-id> `--parameter` \<name> `--add` `--type` enum'.

## ankra stack-profiles drafts options remove

Remove one choice from an input

```bash theme={null}
ankra stack-profiles drafts options remove <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--parameter` | | Input the choice belongs to |
| `--value` | | Value of the choice to remove |

## ankra stack-profiles drafts options set

Add or update one choice on an input

```bash theme={null}
ankra stack-profiles drafts options set <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--description` | | Why someone would pick this choice (optional) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--parameter` | | Input the choice belongs to |
| `--set` | `[]` | Input this choice answers: name=value (repeatable) |
| `--title` | | Label shown for the choice (optional) |
| `--unset` | `[]` | Stop this choice answering an input: name (repeatable) |
| `--value` | | Value the input takes when this choice is picked |

## ankra stack-profiles drafts publish

Publish a draft as a profile version

```bash theme={null}
ankra stack-profiles drafts publish <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--changelog` | | Changelog entry for the version |
| `--channel` | `stable` | Release channel for the version |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--visibility` | | Profile visibility applied at publish (organisation or public) |

## ankra stack-profiles drafts rebase

Move a draft's base to the profile's latest published version. A draft
opened before someone else published cannot be published until it is
rebased; the draft's contents are kept and the upstream changes reported.

```bash theme={null}
ankra stack-profiles drafts rebase <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles drafts submit-suggestion

Submit a draft that edits another organisation's public profile as a
suggestion. The owning organisation reviews it with
'ankra stack-profiles suggestions'; submitting retires the draft.

```bash theme={null}
ankra stack-profiles drafts submit-suggestion <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--title` | | One line describing the change (required) |

## ankra stack-profiles drafts validate

Run the publish validations on a draft without publishing

```bash theme={null}
ankra stack-profiles drafts validate <draft-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles export-iac

Export a profile version as ClusterInfrastructureAsCode YAML

```bash theme={null}
ankra stack-profiles export-iac [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Write YAML to this file instead of stdout |
| `--version` | | Profile version to export, as 1 or v1 (defaults to the profile's current version) |

## ankra stack-profiles get

Describe a stack profile: its metadata, published versions, and the parameters you can bind when applying it.

```bash theme={null}
ankra stack-profiles get [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--version` | | Profile version to describe, as 1 or v1 (defaults to the current version) |

## ankra stack-profiles import

Import a ClusterInfrastructureAsCode YAML file as a stack profile, publishing its first version immediately.

With `--as-draft` the document opens as a builder draft instead, so a file-authored candidate can be reviewed before anything is published: when your organisation already has a profile with the document's name (or the `--name` override) the draft attaches to it as the next-version candidate, and otherwise it opens as a new-profile draft. Review it with 'ankra stack-profiles drafts validate' and ship it with 'ankra stack-profiles drafts publish'.

```bash theme={null}
ankra stack-profiles import [file] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--as-draft` | `false` | Open the document as a builder draft for review instead of publishing (attaches to your existing profile of the same name when one exists) |
| `--category` | `general` | Profile category |
| `--name` | | Profile name (defaults to metadata.name in the file) |

## ankra stack-profiles list

List stack profiles in the active organisation

```bash theme={null}
ankra stack-profiles list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--category` | | Filter profiles by category (e.g. 'monitoring') |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `25` | Page size |
| `--search` | | Filter profiles by name |

## ankra stack-profiles logo

Manage the uploaded logo a profile shows in the catalogue. Uploading
stores the image bytes with Ankra and clears any logo URL; to reference an
image by URL instead, use 'ankra stack-profiles update `--logo-url`'.

## ankra stack-profiles logo clear

Remove a profile's uploaded logo

```bash theme={null}
ankra stack-profiles logo clear [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles logo get

Download the uploaded logo's image bytes. Without `--output` the file is
named after the profile reference with the served image type's extension.

```bash theme={null}
ankra stack-profiles logo get [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--output` | | Write the image to this file (defaults to \<profile>\<ext>) |

## ankra stack-profiles logo set

Upload a logo image for a profile you own. PNG, JPEG, and WebP are
accepted, at most 512 KiB; large images are resized automatically and
square images look best. The upload clears any stored logo URL.

```bash theme={null}
ankra stack-profiles logo set [profile-id|profile-name] <image-file> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles logo set postgres-ha ./logo.png
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles rollout

Update the stacks deployed from a profile to a published version, in place.

For every target the platform replaces the contents of the stack that
deployment already runs with the chosen version - the same stack, so
Kubernetes performs a rolling update of the workloads and nothing is created
twice - and records the deployment at the new version, so 'deployments' and
the profile's fleet view read up to date. The non-secret inputs each
deployment was last applied with are carried forward; bind new values or
secret inputs with `--set`, `--set-file` and `--set-env`, exactly as for apply.

Pick targets with `--cluster` (repeatable) or `--all` for every deployment of the
profile; add `--outdated` to touch only the ones behind the chosen version.
Without `--version` the profile's current version is rolled out.

A member of a target stack that the version does not list is removed. The
platform does that without asking only for a member it can show this profile
put there; any other removal (an add-on, manifest or application someone added
to the stack) is refused, with nothing changed, unless you name it with
`--confirm-removal` cluster:kind/name (a confirmation is for that cluster's
stack only; with a single target the cluster may be left out). `--dry-run` lists, per stack, the members the
version would remove, and writes nothing. A rollout to more than one stack
asks first (`--yes` skips the question), and it stops at the first stack that
fails (`--continue-on-error` keeps going).

`--via-apply` uses the older path instead: the version is exported as
ClusterInfrastructureAsCode and applied with the cluster apply lane. It
updates the stack the same way but leaves the fleet view at the previous
version; use it only against a platform that predates in-place upgrades. That
lane cannot tell whose a member is, so it refuses every removal you do not
name with `--confirm-removal`.

The write returns as soon as the platform has accepted it; the manifest and
add-on deploys run in the background. Watch them with
'ankra cluster operations list `--cluster` \<name>'.

```bash theme={null}
ankra stack-profiles rollout [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles rollout hello-fleet --all --outdated
ankra stack-profiles rollout hello-fleet --cluster prod-eu --cluster prod-us --version 2
ankra stack-profiles rollout hello-fleet --all --dry-run
ankra stack-profiles rollout hello-fleet --cluster prod-eu --confirm-removal prod-eu:addon/legacy-exporter
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--all` | `false` | Every cluster that runs a stack deployed from this profile |
| `--cluster` | `[]` | Target cluster name or ID (repeatable) |
| `--confirm-removal` | `[]` | Allow the rollout to remove this member from one stack although the platform cannot show the profile put it there, as cluster:kind/name (kind addon, manifest or application; the cluster may be left out when the rollout has one target; repeatable) |
| `--continue-on-error` | `false` | Keep rolling out to the remaining stacks after one fails (by default the rollout stops at the first failure) |
| `--dry-run` | `false` | List the stacks that would be updated without writing anything |
| `--outdated` | `false` | Only the deployments behind the version being rolled out |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--set` | `[]` | Bind a parameter: name=value (repeatable; not for secrets) |
| `--set-env` | `[]` | Bind a parameter from an environment variable: name=ENV\_VAR (repeatable; secret-safe) |
| `--set-file` | `[]` | Bind a parameter from a file: name=path (repeatable; secret-safe) |
| `--timeout` | `10m0s` | Maximum time to wait when `--wait` is set |
| `--version` | | Profile version to roll out, as 2 or v2 (defaults to the profile's current version) |
| `--via-apply` | `false` | Export the version as ClusterInfrastructureAsCode and apply it with the cluster apply lane instead of the platform's in-place upgrade (older platforms; the fleet view then keeps the previous version) |
| `--wait` | `false` | Wait for each configuration write to be applied before moving to the next cluster. Manifest and add-on deploys are dispatched afterwards and are NOT covered by this flag |
| `--yes` | `false` | Skip the confirmation asked before a rollout to more than one stack |

## ankra stack-profiles save-version

Save a new profile version by re-snapshotting a deployed stack. The new
version becomes the profile's current version.

```bash theme={null}
ankra stack-profiles save-version [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles save-version postgres-ha --stack postgres --cluster staging \
  --changelog "Bump CloudNativePG to 1.30"
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--changelog` | | Changelog note for the new version |
| `--channel` | `stable` | Release channel for the new version |
| `--cluster` | | Source cluster name or ID (defaults to the selected cluster) |
| `--include-addon-configurations` | `true` | Carry the source add-ons' values into the version |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--stack` | | Source stack name to snapshot (required) |

## ankra stack-profiles set-current-version

Set which published version new deployments of this profile resolve to.
Rolling back is setting the pointer to an earlier version.

```bash theme={null}
ankra stack-profiles set-current-version [profile-id|profile-name] <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles set-current-version postgres-ha v3
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles share

Share a profile with specific organisations. Shared organisations can view
and deploy every version but cannot change the profile. Ask the other
organisation for their slug - admins find it under organisation settings.

## ankra stack-profiles share add

Share a profile with another organisation

```bash theme={null}
ankra stack-profiles share add [profile-id|profile-name] <organisation-slug> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles share add postgres-ha acme-corp
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles share list

List the organisations a profile is shared with

```bash theme={null}
ankra stack-profiles share list [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles share remove

Revoke one share grant by its id (from 'share list'). The organisation
loses access to the profile; stacks it already deployed keep running.

```bash theme={null}
ankra stack-profiles share remove [profile-id|profile-name] <share-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles suggestions

Review the cross-organisation suggestions submitted against a profile.
Approving one publishes its frozen contents as the profile's next version.
Withdraw is the proposer's verb for a suggestion their organisation submitted.

## ankra stack-profiles suggestions approve

Approve a suggestion, publishing it as the profile's next version

```bash theme={null}
ankra stack-profiles suggestions approve [profile-id|profile-name] <suggestion-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--changelog` | | Changelog note (defaults to one composed from the suggestion) |
| `--channel` | `stable` | Release channel for the published version |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles suggestions get

Show one suggestion's contents and upstream drift

```bash theme={null}
ankra stack-profiles suggestions get [profile-id|profile-name] <suggestion-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles suggestions list

List the suggestions visible to your organisation on a profile

```bash theme={null}
ankra stack-profiles suggestions list [profile-id|profile-name] [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles suggestions reject

Reject a suggestion, optionally with a note the proposer can read

```bash theme={null}
ankra stack-profiles suggestions reject [profile-id|profile-name] <suggestion-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | Resolution note the proposer can read |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles suggestions withdraw

Withdraw a suggestion your organisation submitted

```bash theme={null}
ankra stack-profiles suggestions withdraw [profile-id|profile-name] <suggestion-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary

Read the reviewed summary of an exact profile version, inspect its selected evidence,
review an existing candidate, or withdraw an approval. Use status, generate and
policy for explicit generation controls. No operation changes a workload version.
The platform checks current
permissions and source visibility on every request.

Read the candidate and its source\_revision, candidate\_revision and summary\_revision
before deciding. Supply those exact counters; do not fetch newer counters and retry
a stale decision automatically. After an uncertain write, read back before retrying.
Output is JSON by default; use -o yaml for YAML.

## ankra stack-profiles summary cancel

Cancel one generation without withdrawing an approval

```bash theme={null}
ankra stack-profiles summary cancel <generation-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary cancel <generation-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Confirm cancelling this generation |

## ankra stack-profiles summary draft-status

Read generation and approval state for the draft revision you inspected

```bash theme={null}
ankra stack-profiles summary draft-status <draft-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary draft-status <draft-id> --source-revision 3
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--source-revision` | `0` | Draft revision you inspected (required) |

## ankra stack-profiles summary edit

Select existing facts for an unapproved candidate

```bash theme={null}
ankra stack-profiles summary edit <generation-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary edit <generation-id> --candidate-revision 2 --outcome logging=f0,f1
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--candidate-revision` | `0` | Candidate revision you inspected (required) |
| `--clear` | `false` | Explicitly clear the candidate's selections; does not withdraw an existing approval |
| `--outcome` | `[]` | Select KIND=FACT\_ID,FACT\_ID; repeat for up to five groups |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary evidence

Inspect evidence selected by the current approval

```bash theme={null}
ankra stack-profiles summary evidence <profile-id|profile-name> <version> <fact-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary evidence opensearch 3 f0
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary generate

Request one private candidate. The platform must have generation enabled, a configured
model, current organisation consent and sufficient budget. This command grants none
of those prerequisites and does not publish a summary or change a workload.

First read status (or draft-status). Create and save a request-key before admission.
Supply the exact source and summary revisions you inspected, including summary
revision zero. After an uncertain response, retry with the SAME key, source and
revisions. Do not create a new key or refresh expectations for that retry. The server
rejects conflicting reuse. Inspect generation \<id> for progress and review separately.

```bash theme={null}
ankra stack-profiles summary generate <profile-id|profile-name> <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary generate opensearch 3 --source-revision 3 --summary-revision 0 --request-key <saved-uuidv7>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--request-key` | | Saved canonical UUIDv7 identifying this request; reuse unchanged for retries (required) |
| `--source-revision` | `0` | Exact published version you inspected; must match the version argument (required) |
| `--summary-revision` | `0` | Approval pointer revision you inspected, including zero (required) |

## ankra stack-profiles summary generate-draft

Request one private candidate. The platform must have generation enabled, a configured
model, current organisation consent and sufficient budget. This command grants none
of those prerequisites and does not publish a summary or change a workload.

First read status (or draft-status). Create and save a request-key before admission.
Supply the exact source and summary revisions you inspected, including summary
revision zero. After an uncertain response, retry with the SAME key, source and
revisions. Do not create a new key or refresh expectations for that retry. The server
rejects conflicting reuse. Inspect generation \<id> for progress and review separately.

```bash theme={null}
ankra stack-profiles summary generate-draft <draft-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary generate-draft <draft-id> --source-revision 3 --summary-revision 0 --request-key <saved-uuidv7>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--request-key` | | Saved canonical UUIDv7 identifying this request; reuse unchanged for retries (required) |
| `--source-revision` | `0` | Exact draft revision you inspected (required) |
| `--summary-revision` | `0` | Approval pointer revision you inspected, including zero (required) |

## ankra stack-profiles summary generation

Inspect a private candidate and its revision counters

```bash theme={null}
ankra stack-profiles summary generation <generation-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary generation <generation-id>
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary get

Read one version's approved summary

```bash theme={null}
ankra stack-profiles summary get <profile-id|profile-name> <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary get opensearch 3
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary policy

Read policy get first: inspect the data-use notice, provider destination, provider
terms, consent digest and current policy revision. Approval requires a human identity with ai.manage and
explicit limits and acknowledgements. It does not enable generation or select a model.
After an uncertain policy write, read back before deciding what to do next.

## ankra stack-profiles summary policy approve

Read policy get first: inspect the data-use notice, provider destination, provider
terms, consent digest and current policy revision. Approval requires a human identity with ai.manage and
explicit limits and acknowledgements. It does not enable generation or select a model.
After an uncertain policy write, read back before deciding what to do next.

To change OpenRouter routing, preview with policy get `--openrouter-ingress` europe
`--openrouter-upstream` google-vertex/europe. Review the returned destination and
consent\_digest, then supply the SAME routing flags and that digest to approve.
The preview makes no changes. Omit both flags to retain saved routing.
Europe requires regional access under your OpenRouter agreement; the option alone
does not establish data residency. Requests require zero retention, no data
collection and no provider fallback. These commands do not verify your contract.

```bash theme={null}
ankra stack-profiles summary policy approve [flags]
```

**Examples**

```bash theme={null}
# Example limits only: choose ceilings and retention for your organisation.
ankra stack-profiles summary policy approve --policy-revision 0 --consent-digest <inspected-digest> --accept-data-use --confirm-provider-terms --content-retention-days 7 --metadata-retention-days 30 --daily-tokens 100000 --request-tokens 1000 --daily-usd 1 --request-usd 0.01
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--accept-data-use` | `false` | Acknowledge the data-use notice you inspected (required) |
| `--confirm-provider-terms` | `false` | Confirm you reviewed the provider terms (required) |
| `--consent-digest` | | Exact route consent\_digest from policy get (required) |
| `--content-retention-days` | `0` | Content retention, 1 to 90 days (required) |
| `--daily-tokens` | `0` | Daily token ceiling, 1 to 1000000000 (required) |
| `--daily-usd` | | Daily USD ceiling, positive and at most 1000000; up to six decimal places (required) |
| `--metadata-retention-days` | `0` | History retention, at least content retention and at most 3650 days (required) |
| `--openrouter-ingress` | | Proposed OpenRouter connection: global or europe; requires `--openrouter-upstream` |
| `--openrouter-upstream` | | Exact allowed provider identifier; explicitly use an empty value for any privacy-eligible provider |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--policy-revision` | `0` | Exact policy revision you inspected; zero only for first approval (required) |
| `--request-tokens` | `0` | Per-request token ceiling, at most daily ceiling and 1000000 (required) |
| `--request-usd` | | Per-request USD ceiling, positive and at most daily ceiling and 1000; up to six decimal places (required) |

## ankra stack-profiles summary policy get

Read policy get first: inspect the data-use notice, provider destination, provider
terms, consent digest and current policy revision. Approval requires a human identity with ai.manage and
explicit limits and acknowledgements. It does not enable generation or select a model.
After an uncertain policy write, read back before deciding what to do next.

To change OpenRouter routing, preview with policy get `--openrouter-ingress` europe
`--openrouter-upstream` google-vertex/europe. Review the returned destination and
consent\_digest, then supply the SAME routing flags and that digest to approve.
The preview makes no changes. Omit both flags to retain saved routing.
Europe requires regional access under your OpenRouter agreement; the option alone
does not establish data residency. Requests require zero retention, no data
collection and no provider fallback. These commands do not verify your contract.

```bash theme={null}
ankra stack-profiles summary policy get [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary policy get
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--openrouter-ingress` | | Proposed OpenRouter connection: global or europe; requires `--openrouter-upstream` |
| `--openrouter-upstream` | | Exact allowed provider identifier; explicitly use an empty value for any privacy-eligible provider |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary policy revoke

Revoke the exact consent revision you inspected

```bash theme={null}
ankra stack-profiles summary policy revoke [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary policy revoke --policy-revision 2
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--policy-revision` | `0` | Exact positive policy revision you inspected (required) |
| `--yes` | `false` | Confirm revoking summary generation consent |

## ankra stack-profiles summary request-key

Create a request key locally. Save it before submitting generation. This command does not contact the platform. Never create a new key to retry an uncertain request.

```bash theme={null}
ankra stack-profiles summary request-key [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary request-key -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary review

Approve or reject the exact candidate you inspected. Approval requires a human identity; service and board principals are refused. For a version, approval publishes its summary. Draft approvals remain private. Workload versions do not change.

```bash theme={null}
ankra stack-profiles summary review <generation-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary review <generation-id> --decision approve --source-revision 3 --candidate-revision 2 --summary-revision 0
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--candidate-revision` | `0` | Candidate revision you inspected (required) |
| `--decision` | | approve or reject (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--source-revision` | `0` | Exact source revision you inspected (required) |
| `--summary-revision` | `0` | Approval pointer revision you inspected, including zero (required) |

## ankra stack-profiles summary runtime-qualification

Run fixed synthetic checks on the organisation's configured staging cluster and
approved candidate image. Requires ai.manage and cluster read access; start and
cancel also require clusters.operate. No profile content or model request is sent.
A completed report can contain violated and unverified checks. These operations
do not issue an admission receipt, enable generation or change consent.

## ankra stack-profiles summary runtime-qualification cancel

Run fixed synthetic checks on the organisation's configured staging cluster and
approved candidate image. Requires ai.manage and cluster read access; start and
cancel also require clusters.operate. No profile content or model request is sent.
A completed report can contain violated and unverified checks. These operations
do not issue an admission receipt, enable generation or change consent.

```bash theme={null}
ankra stack-profiles summary runtime-qualification cancel <operation-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary runtime-qualification cancel <operation-id> --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Confirm cancelling this qualification |

## ankra stack-profiles summary runtime-qualification get

Run fixed synthetic checks on the organisation's configured staging cluster and
approved candidate image. Requires ai.manage and cluster read access; start and
cancel also require clusters.operate. No profile content or model request is sent.
A completed report can contain violated and unverified checks. These operations
do not issue an admission receipt, enable generation or change consent.

`--wait` exits 0 when a report is collected, even if observations are violated or
unverified; inspect report.checks before deciding what it proves. Failed, cancelled
or interrupted operations exit 1. Timeout exits 5. Interrupting the wait does not
cancel the remote operation; use cancel explicitly. Without `--wait`, exit 0 means
the operation was read or accepted. JSON/YAML stdout contains one response only.

```bash theme={null}
ankra stack-profiles summary runtime-qualification get <operation-id> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary runtime-qualification get <operation-id> --wait -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `10m0s` | Bound `--wait`, including requests (positive duration; expiry exits 5) |
| `--wait` | `false` | Wait for a terminal operation; completion does not mean all checks passed |

## ankra stack-profiles summary runtime-qualification start

Run fixed synthetic checks on the organisation's configured staging cluster and
approved candidate image. Requires ai.manage and cluster read access; start and
cancel also require clusters.operate. No profile content or model request is sent.
A completed report can contain violated and unverified checks. These operations
do not issue an admission receipt, enable generation or change consent.

The request ID is printed to stderr before sending. Save it. If the response is
uncertain, repeat start with the SAME `--request-id` and organisation; never use a
new ID to recover an existing request. A replay returns the recorded operation.

`--wait` exits 0 when a report is collected, even if observations are violated or
unverified; inspect report.checks before deciding what it proves. Failed, cancelled
or interrupted operations exit 1. Timeout exits 5. Interrupting the wait does not
cancel the remote operation; use cancel explicitly. Without `--wait`, exit 0 means
the operation was read or accepted. JSON/YAML stdout contains one response only.

```bash theme={null}
ankra stack-profiles summary runtime-qualification start [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary runtime-qualification start --request-id <saved-uuid> --wait -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--request-id` | | Saved nonzero UUID; reuse after an uncertain start (default: generate and print before sending) |
| `--timeout` | `10m0s` | Bound `--wait`, including requests (positive duration; expiry exits 5) |
| `--wait` | `false` | Wait for a terminal operation; completion does not mean all checks passed |

## ankra stack-profiles summary status

Read generation and approval state for an exact version

```bash theme={null}
ankra stack-profiles summary status <profile-id|profile-name> <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary status opensearch 3
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles summary withdraw

Hide a summary approval while preserving its history

```bash theme={null}
ankra stack-profiles summary withdraw <profile-id|profile-name> <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles summary withdraw opensearch 3 --summary-revision 1 --reason incorrect_claim
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--reason` | | incorrect\_claim, sensitive\_content, outdated\_policy or author\_request (required) |
| `--summary-revision` | `0` | Approval pointer revision you inspected (required) |
| `--yes` | `false` | Confirm hiding the approved summary |

## ankra stack-profiles undeprecate

Remove the deprecation from a published version: it becomes deployable
again and eligible to be made current. Undeprecating a version that was
never deprecated changes nothing and still succeeds.

```bash theme={null}
ankra stack-profiles undeprecate [profile-id|profile-name] <version> [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles undeprecate postgres-ha v3
ankra stack-profiles undeprecate postgres-ha 3 -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra stack-profiles update

Update how a stack profile appears in the catalogue: its name,
description, category, tags, logo URL, and visibility. Only the flags you
set change; pass an empty value to clear a field.

```bash theme={null}
ankra stack-profiles update [profile-id|profile-name] [flags]
```

**Examples**

```bash theme={null}
ankra stack-profiles update postgres-ha --description "Production PostgreSQL 17" --tag postgresql --tag cnpg
ankra stack-profiles update postgres-ha --visibility public
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--category` | | New category |
| `--description` | | New description (empty clears) |
| `--logo-url` | | New logo image URL (empty clears) |
| `--name` | | New profile name |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--tag` | `[]` | New tag set (repeatable; replaces the stored tags) |
| `--visibility` | | Profile visibility: organisation or public |

## ankra stack-profiles version

Print the stored record of one published version: its spec, parameters and
channel, as JSON (default) or YAML.

Manifests and add-on values inside the record are base64-encoded. To read
them decoded, list them, or grep across them, use:

```bash theme={null}
ankra stack-profiles contents <profile> <version>
```

```bash theme={null}
ankra stack-profiles version [profile-id|profile-name] <version> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |


# ankra support
Source: https://docs.ankra.ai/reference/cli/support

Create and track Ankra support requests

## ankra support

Create and track support requests for your organisation.

Every request is reviewed by Ankra AI before it reaches the team, which may
enrich it or flag low-quality submissions. Use `--force` on create to submit a
flagged request anyway.

```bash theme={null}
ankra support create --subject "Nodes NotReady" --description "..." --cluster prod
ankra support list
ankra support get <ticket-id>
ankra support comment <ticket-id> --message "Any update?"
ankra support close <ticket-id>
```

## ankra support attach

Attach screenshots or images to a support request

```bash theme={null}
ankra support attach <ticket-id> <file>... [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra support close

Close a support request

```bash theme={null}
ankra support close <ticket-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--yes` | `false` | Skip the confirmation prompt |

## ankra support comment

Add a reply to a support request

```bash theme={null}
ankra support comment <ticket-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-m`, `--message` | | Reply message (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra support create

Create a support request

```bash theme={null}
ankra support create [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--category` | `technical` | Category: technical, account, billing, bug, feature\_request, other |
| `--cluster` | | Optional related cluster (name or ID) |
| `--description` | | Detailed description of the issue (required) |
| `--force` | `false` | Skip the review prompt and submit even if flagged or a possible duplicate |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--severity` | | Optional severity: low, medium, high, critical |
| `--source` | `cli` | Origin of the request: cli or agent |
| `--subject` | | Short summary of the issue (required) |

## ankra support get

Show a support request and its replies

```bash theme={null}
ankra support get <ticket-id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra support list

List support requests

```bash theme={null}
ankra support list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--page` | `1` | Page number |
| `--page-size` | `25` | Page size |
| `-q`, `--query` | | Filter by subject text |
| `--status` | `[]` | Filter by status (repeatable) |


# ankra targets
Source: https://docs.ankra.ai/reference/cli/targets

Manage host deploy targets

## ankra targets

Manage host deploy targets: machines outside Kubernetes that run the
ankra-host-agent and receive releases from 'kind: deploy' pipeline stages.

A host joins an environment with a single-use join token:

```bash theme={null}
# as an organisation admin
ankra targets join-token create --environment production -o json

# as root on the host
ankra targets register --environment production --name web-1 --token-stdin
```

The agent only ever connects outbound over HTTPS; the host needs no inbound
port.

## ankra targets get

Show a host deploy target

```bash theme={null}
ankra targets get <name|id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Environment to look the name up in, when several environments use it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra targets join-token

Mint join tokens that let a host register into an environment

## ankra targets join-token create

Mint a single-use join token a host registers into the environment with.
The environment is created when it does not exist yet.

The token is shown exactly once: the platform keeps only its hash. Without -o
it is the only thing written to stdout (the expiry and the next step go to
stderr), so it can be piped straight into 'ankra targets register
`--token-stdin`' on the host.

```bash theme={null}
ankra targets join-token create [flags]
```

**Examples**

```bash theme={null}
ankra targets join-token create --environment production
ankra targets join-token create --environment production --ttl 4h -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Environment the host registers into (required) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--ttl` | `1h0m0s` | How long the token stays valid (at most 24h) |

## ankra targets list

List host deploy targets

```bash theme={null}
ankra targets list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Only list targets in this environment |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra targets register

Register this machine as a host deploy target and start its agent. Run it
as root on the host itself, with a join token from 'ankra targets join-token
create' on stdin.

The command:

1. downloads ankra-host-agent for this machine's OS and architecture and its
   systemd unit from the agent release, and refuses them unless their
   SHA-256 matches the release's SHA256SUMS;
2. installs the binary as /usr/local/bin/ankra-host-agent;
3. runs 'ankra-host-agent register', passing the join token on stdin - the
   agent does the registration and stores its own identity token;
4. installs ankra-host-agent.service, enables it and (re)starts it, so
   running it again on a registered host moves the service onto the new
   binary.

The CLI never sends the join token anywhere itself and needs no 'ankra login'
on the host. `--no-install` prints these steps without doing any of them.

The agent reaches the platform at `--base-url` (or the configured base URL),
over outbound HTTPS only. Releases are fetched over HTTPS too: `--release-url`
takes http\:// only for a loopback address, or with ANKRA\_ALLOW\_INSECURE\_HTTP=1.

```bash theme={null}
ankra targets register [flags]
```

**Examples**

```bash theme={null}
ankra targets join-token create --environment production | \
  ssh root@web-1 ankra targets register --environment production --name web-1 --label role=web --token-stdin

ankra targets register --environment production --name web-1 --token-stdin --no-install
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--agent-version` | `latest` | Agent release to install, e.g. v2.1.1177 (default: the latest release) |
| `--environment` | | Environment to register into (required) |
| `--label` | `[]` | Label as key=value; repeat for more (deploy stages select targets by label) |
| `--name` | | Name of this host target, unique in the environment (required) |
| `--no-install` | `false` | Print what would be downloaded, run and installed, and do nothing |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--release-url` | | Base URL of the agent releases (default [https://github.com/ankraio/ankra-host-agent/releases](https://github.com/ankraio/ankra-host-agent/releases), or \$ANKRA\_HOST\_AGENT\_RELEASE\_URL) |
| `--token-stdin` | `false` | Read the join token from stdin (required; the token is never taken as a flag) |

## ankra targets revoke

Revoke a host deploy target. Its identity token and every session stop
working at once and it receives no further deploy jobs; the releases already
on the host keep running. A revoked host registers again only with a new
join token.

```bash theme={null}
ankra targets revoke <name|id> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--environment` | | Environment to look the name up in, when several environments use it |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--yes` | `false` | Revoke without asking for confirmation |


# ankra tickets
Source: https://docs.ankra.ai/reference/cli/tickets

Work the AI board: list tickets, read one, comment, move it, answer a decision

## ankra tickets

Work the organisation's AI board from the terminal.

The AI board is where Ankra's agents track incidents, insights and requests
as tickets. These commands list the board, show one ticket with its
timeline, comment on it, move it through its lifecycle, and answer the
decision a blocked ticket is waiting on - the same choice the ticket page
renders as options plus "something else".

A ticket is referenced by its number (8, T-8 or #8) or its UUID.

## ankra tickets comment

Post a comment on a ticket as yourself. A comment on a blocked ticket
hands it back to its agent; to answer a choice the agent offered, use
"ankra tickets decide" instead so the answer is recorded as the decision.

```bash theme={null}
ankra tickets comment <ticket> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--body` | | The comment (markdown) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra tickets decide

Answer the decision a blocked ticket is waiting on. Pick one of the
options the agent offered with `--option` \<key> (see "ankra tickets get"),
or give the decision in your own words with `--answer`. Both together record
the option with your note beside it. The answer lands on the timeline as a
"Decision:" comment and the agent resumes from it.

```bash theme={null}
ankra tickets decide <ticket> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--answer` | | The decision in your own words, or a note beside `--option` |
| `--option` | | Key of the offered option to choose |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra tickets events

Show a ticket's timeline, oldest first

```bash theme={null}
ankra tickets events <ticket> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--limit` | `200` | Maximum events to show |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra tickets get

Show one ticket, including the decision it is waiting on

```bash theme={null}
ankra tickets get <ticket> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra tickets list

List the board's tickets, newest first

```bash theme={null}
ankra tickets list [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--include-closed` | `false` | Include done and cancelled tickets |
| `--limit` | `50` | Maximum tickets to list (up to 200) |
| `--needs-human` | `false` | Only tickets waiting on a person |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--search` | | Match on the title |
| `--status` | `[]` | Only these statuses (comma-separated: triage, investigating, planning, awaiting\_review, awaiting\_approval, executing, verifying, blocked, done, cancelled) |

## ankra tickets transition

Move a ticket to another status

```bash theme={null}
ankra tickets transition <ticket> [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--note` | | Why the ticket is moving |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--status` | | The status to move to |


# ankra tokens
Source: https://docs.ankra.ai/reference/cli/tokens

Manage API tokens

## ankra tokens

Commands to list, create, rotate, revoke, and delete API tokens.

By default they act on your personal tokens. `--service` on list, create and
rotate acts on the organisation's service tokens instead: tokens that belong
to a service account rather than a person, for pipelines and other
automation. Listing and creating them needs the members.manage permission.

## ankra tokens create

Create a personal API token named \<name>.

With `--service`, \<name> is a service account of the organisation instead, and
the token belongs to that account rather than to you: it keeps working when
you leave the organisation, and acts with the account's role, not yours.
The account is created with `--role` when the organisation has none of that
name; for an existing account `--role` must be the role it already holds.
`--label` names the token itself (default: a timestamp). The role may not
carry permissions you lack, and creating one needs members.manage.

The global `--project` \<slug|name|id> pins the token to that project: it then
acts only there and cannot be pointed elsewhere. A token with MCP scopes is
always pinned - to the project you pass, else to the project you are acting
in; a REST token created without `--project` follows its owner's current
project and honours `--project` / ANKRA\_PROJECT per command.

The token value is shown once.

```bash theme={null}
ankra tokens create <name> [flags]
```

**Examples**

```bash theme={null}
ankra tokens create laptop --expires 2026-12-31T00:00:00Z
ankra tokens create ci-deployer --service --role member --label github-actions
ankra tokens create ci-deployer --service --role member --expires 2027-01-31T00:00:00Z -o json
ankra tokens create agent-mcp --scopes mcp:read --project platform-team
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--expires` | | Token expiration date (ISO 8601 format; RFC 3339 with `--service`) |
| `--label` | | Name of the service token itself (with `--service`; default: a timestamp) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--role` | | Role the service account acts with (required with `--service`) |
| `--scopes` | `[]` | MCP access scopes: mcp:read or mcp:read,mcp:write; omitted creates a REST-only token |
| `--service` | `false` | Create an organisation service token for the service account \<name> instead of a personal token |

## ankra tokens delete

Delete an API token. The token must be revoked first.

```bash theme={null}
ankra tokens delete <token_id>
```

## ankra tokens list

List your API tokens with when each one expires.

A live token that expires within 7 days reads "Expiring" in the Status
column and an expired one "Expired"; the Expires column shows the date and
how many days are left. Renew an expiring token before it stops working with
"ankra tokens rotate \<id>".

`--service` lists the organisation's service tokens instead, with the service
account each belongs to and the role it holds; renew one with
"ankra tokens rotate \<id> `--service`". It needs members.manage (exit 7
without it).

```bash theme={null}
ankra tokens list [flags]
```

**Examples**

```bash theme={null}
ankra tokens list
ankra tokens list --service
ankra tokens list --service -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--order` | `asc` | Sort direction with `--sort`: asc or desc |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--service` | `false` | List the organisation's service tokens instead of your personal tokens |
| `--sort` | | Sort by column: id, name, status, created, expires, last-used (default: server order) |

## ankra tokens revoke

Revoke an API token (can be deleted after)

```bash theme={null}
ankra tokens revoke <token_id>
```

## ankra tokens rotate

Issue a new token to replace one that is about to expire, with the same
name and scopes. The old token keeps working for an overlap window so you can
update every place it is used, then it stops by itself.

The new token value is shown once. When stdout is not a terminal the command
prints only the value on stdout, so this works in scripts:

```bash theme={null}
TOKEN=$(ankra tokens rotate <token_id>)
```

All other text goes to stderr. With -o json the whole response is printed.

Use `--service` to rotate an organisation service token instead of a personal
one. `--overlap-hours` sets how long the old token keeps working, from 0 (stops
at once) to 168; the platform default is 24 hours.

```bash theme={null}
ankra tokens rotate <token_id> [flags]
```

**Examples**

```bash theme={null}
ankra tokens rotate 5b1c0d52-0000-0000-0000-000000000000
ankra tokens rotate <token_id> --overlap-hours 72
ankra tokens rotate <token_id> --service -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--overlap-hours` | `24` | Hours the old token keeps working (0-168) |
| `--service` | `false` | Rotate an organisation service token instead of a personal token |


# ankra upgrade
Source: https://docs.ankra.ai/reference/cli/upgrade

Upgrade the Ankra CLI to the latest release

## ankra upgrade

Download and install a specific Ankra CLI release, replacing the
currently running binary in place.

By default the command upgrades to the latest stable release. Install an
exact release with `--version` (for example `--version` v0.2.5, or `--version`
0.2.5). When a version is pinned the command installs it whether it is
newer, older or the same as the running binary, so `--version` doubles as a
downgrade: 'ankra upgrade `--version` v0.1.9' rolls back to that release.
Use `--check` to report whether a newer release is available without
installing anything.

When the beta channel is enabled (see 'ankra config beta enable') the
newest release including pre-releases (release candidates such as
v0.3.0-rc.1) is installed instead. Use `--beta` or `--beta=false` to override
the saved channel for a single run.

The downloaded binary is verified against its published SHA-256 checksum
before it replaces the existing executable.

The Ankra agent skills ('ankra skills install') ship inside the binary, so
an upgrade also offers to refresh the copies already installed for your
assistants; the new binary reinstalls them once it is in place, with the
same `--no-rules`, `--no-workflows` and `--with-hooks` choices each install was
made with. `--skills` takes the offer without asking and `--skills=false`
declines it. `--yes` skips only the upgrade confirmation: a scripted
'ankra upgrade `--yes`' leaves the installed skills as they are and says how
to refresh them; pass `--yes` `--skills` to refresh them without any question.

```bash theme={null}
ankra upgrade [flags]
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--allow-unverified` | `false` | install even when no SHA-256 checksum is published (insecure) |
| `--beta` | `false` | include pre-release versions for this run (overrides the saved channel) |
| `--check` | `false` | check for a newer release without installing |
| `--force` | `false` | reinstall even if already on the target version |
| `--skills` | `true` | refresh the Ankra agent skills already installed for your assistants once the new binary is in place, replaying each install's options; `--skills=false` leaves them as they are, and without the flag you are asked (never refreshed by `--yes` alone) |
| `--version` | | exact release to install for an upgrade or downgrade, e.g. v0.2.5 (default: latest) |
| `-y`, `--yes` | `false` | skip the upgrade confirmation prompt (the installed agent skills are refreshed only with `--skills`) |


# ankra workspace
Source: https://docs.ankra.ai/reference/cli/workspace

Manage this checkout's Ankra Workspace, where 'ankra exec' runs commands

## ankra workspace

An Ankra Workspace is your long-lived pod on the organisation's CI pool,
built from the repository's workspace profile (or its pipeline's image), that
'ankra exec' runs heavy commands in instead of on this machine.

The repository is the checkout's origin remote (GitHub, GitLab or Bitbucket),
which must be connected to Ankra Pipelines. Each repository has one workspace
per kind (default "default"); 'ankra exec `--kind` K' uses the K one.

Needs the workspaces.use permission.

## ankra workspace down

Tear this checkout's workspace of the given kind down: its pod, its volume and
everything synced into it. The next 'ankra exec' or 'ankra workspace up'
brings a fresh one up (and sends the checkout's history again).

Asks for confirmation unless `--yes` is given; declining exits 4. Exits 3 when
there is no live workspace of that kind.

```bash theme={null}
ankra workspace down [flags]
```

**Examples**

```bash theme={null}
ankra workspace down
ankra workspace down --kind playwright --yes
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--kind` | `default` | Workspace kind to tear down |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `-y`, `--yes` | `false` | Skip the confirmation prompt |

## ankra workspace status

Show this checkout's live workspaces (every kind, or the `--kind` one). Reading a
provisioning workspace moves it on: the platform runs its preflight.

Exit codes: 0 when a workspace was found, 3 when the repository has none (or
is not connected to Ankra Pipelines).

```bash theme={null}
ankra workspace status [flags]
```

**Examples**

```bash theme={null}
ankra workspace status
ankra workspace status --kind playwright -o json
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--kind` | | Only the workspace of this kind |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |

## ankra workspace up

Bring this checkout's workspace of the given kind up, or answer the one that
is already live. A new workspace starts provisioning; `--wait` reads it until it
is ready (the platform runs its preflight on each read) or failed.

Exit codes: 0 when the workspace is up (ready, or provisioning without `--wait`),
1 when it failed, 5 when `--wait` timed out.

```bash theme={null}
ankra workspace up [flags]
```

**Examples**

```bash theme={null}
ankra workspace up
ankra workspace up --kind playwright --wait
```

**Flags**

| Flag | Default | Description |
| - | - | - |
| `--kind` | `default` | Workspace kind (the repository's workspace profile) |
| `-o`, `--output` | | Output format: json or yaml (default: human-readable) |
| `--timeout` | `16m0s` | How long `--wait` waits |
| `--wait` | `false` | Wait until the workspace is ready or failed |


# Cost API fields
Source: https://docs.ankra.ai/reference/cost-api

Field meanings for scripts that read cloud cost - readiness states, cost settings, the what-if estimate, and how provider comparisons pick sizes.

This page lists what the cost fields mean when you read cost from a script. It complements [Cloud Cost](/platform/cloud-cost), which explains the feature, and the [API Reference](/api-reference/introduction), which lists every cost endpoint with its full schema. Every money figure is an estimate in cents, in the currency the response names.

***

## Readiness states

A cluster's cost read carries `readiness.state`, which says whether an estimate exists and, if not, why.

| Value | Meaning |
| - | - |
| `ready` | A cost estimate is available |
| `no_credential` | No cloud credential is attached for this provider |
| `no_rate_card` | Private capacity (Proxmox, VMware, imported hardware) that has no [rate card](/platform/cloud-cost#private-capacity-rate-cards) yet |
| `unsupported_provider` | The cluster's provider is not supported for cost estimation |
| `cluster_offline` | The cluster is offline, so its inventory cannot be synced |
| `awaiting_nodes` | Waiting for the first node inventory sync |
| `awaiting_pricing` | Nodes are known; pricing is still resolving |
| `estimate_pending` | Inventory and pricing are present; the first estimate is being computed |

A priced estimate whose nodes or volumes were not all priced sets `coverage_incomplete`, so the figure understates the real cost.

***

## Cost settings

| Field | Meaning |
| - | - |
| `currency` | The organisation's default display currency: `eur` (the default), `usd`, `gbp`, `sek`, `nok`, `dkk`, `chf`, `pln`, `czk`, `jpy`, `cad`, `aud` or `inr` |
| `effective_discount_pct` | A flat discount from 0 to 100 applied to list prices |
| `include_network_egress_estimate` | Whether an estimated network egress component is added |
| `display_currency` | Read only: the currency in effect for the caller, after their personal preference |
| `fx_rates` | Read only: the exchange rates used for conversion |

Only organisation admins can change the settings (`PUT /api/v1/org/cloud-cost/settings`).

***

## What-if estimate

`GET /api/v1/org/clusters/{cluster_id}/cost/estimate` returns what the cluster runs today, priced, to seed a draft. `POST` to the same path prices a draft. Nothing is saved or applied.

```bash cURL theme={null}
curl -X POST "https://platform.ankra.app/api/v1/org/clusters/<cluster-id>/cost/estimate" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "node_groups": [
      { "name": "workers", "count": 3, "vcpus": 4, "memory_gb": 8, "disk_gb": 100 },
      { "name": "batch", "count": 1, "vcpus": 2, "memory_gb": 4, "disk_gb": 0, "spot": true }
    ],
    "network": { "load_balancers": 2 },
    "provider": "upcloud"
  }'
```

### Request

| Field | Meaning |
| - | - |
| `node_groups` | The full set of node groups the draft runs: `name`, `count`, `vcpus`, `memory_gb`, `disk_gb` per node, and `spot`. Optional `gpus` (0 to 16 per node) and `gpu_model` (such as `L40S`): see [GPU node groups](#gpu-node-groups) |
| `network` | Optional counts of `load_balancers`, `nat_gateways`, `gateways` and `flexible_ips`. Omit it to keep today's network resources |
| `provider` | Optional. Prices the draft on another provider; it must be one of the response's `available_targets`. The cluster's own provider re-sizes the fleet in place |
| `match` | `cheapest` (the default) or `like_for_like`. See [vCPU classes](#vcpu-classes) |

### Response

| Field | Meaning |
| - | - |
| `baseline` | Today's configuration, priced |
| `estimate` | The draft, priced: one line per node group with the size it was placed on and its `instance_class`, the provisioned `control_plane`, the network resources, and totals with a `coverage_incomplete` flag. A line with GPUs also carries `gpus`, `gpu_model`, `instance_gpus` and `instance_gpu_model` |
| `metered_monthly_cents` | Today's metered bill |
| `predicted_monthly_cents` | The predicted bill: today's bill plus the priced difference. Withheld when an unpriced part differs between draft and today |
| `delta_monthly_cents` | The change between the two |
| `priced_delta_monthly_cents` | The change over the parts both sides could price, returned even when the prediction is withheld |
| `pricing` | How the cluster's own side is priced: `mode` is `catalog`, `rate_card` or `unavailable`, with the source and unit prices |
| `available_targets` | The providers the draft can be priced on |
| `target_provider`, `target_pricing` | Present when `provider` named another provider: the target and how it is priced |
| `volumes` | The cluster's metered volume storage and what it would bill on the target |

***

## GPU node groups

A node group's `gpus` is how many GPUs each node needs. The baseline reads it from the size the group runs on, or from the GPUs its nodes advertise (`nvidia.com/gpu`, `amd.com/gpu`) where the size does not say.

| Draft | Result |
| - | - |
| `gpus` omitted | The group keeps the GPUs of the baseline group with the same name |
| `gpus` above 0 | The group is placed only on a size that carries at least that many GPUs |
| `gpus` is 0 | The GPUs are dropped and the group is placed on a size without any |
| `gpu_model` set | Sizes carrying that card are preferred. When none holds the group, it lands on another card and the line's `note` names it |

A group without GPUs is never placed on a GPU size. Where the price book records no GPU sizes for the provider, a GPU group is unpriced and its `note` says so.

On UpCloud every GPU plan in the price book is a size, read from the plan name (`GPU-8xCPU-64GB-1xL40S` is 8 vCPU, 64 GB and one L40S). GPU plans bundle no storage, so the group's `disk_gb` is priced as volume storage. UpCloud sells GPU spot capacity as separate `GPU-SPOT-` plans: a group with `spot` set lands on one where it fits and is priced at that plan's own rate.

***

## Hyperscaler sizes

When a draft or a [provider comparison](/platform/cloud-cost#compare-providers) is priced on AWS, Google Cloud or Azure, Ankra places each node group on a size from that provider's catalogue.

| Provider | Sizes offered |
| - | - |
| AWS | Every current-generation EC2 instance type with a published vCPU count, memory size and CPU architecture, except Apple Mac hosts. GPU, memory-optimised and burstable T types are included; T types count as shared-core. The catalogue does not record which types carry GPUs, so a group that needs GPUs is not placed on any of them |
| Google Cloud | Shapes are read from the machine type name (an `n2-standard-8` is 8 vCPU and 32 GB), so only the general-purpose and compute-optimised families are used. Accelerator, memory-optimised and HPC families, and the shared-core `e2-micro`, `e2-small` and `e2-medium`, are left out |
| Azure | Shapes are read from the size name (a `Standard_D8s_v5` is 8 vCPU and 32 GB), so only the D (general-purpose), E (memory-optimised) and F (compute-optimised) series are used. B burstable, L, M, N and H series, confidential sizes, and sizes whose feature letters change the memory ratio are left out |

Hyperscaler catalogues are priced per region. Each comparison column names the region it used: the cluster's own region when the target prices it, else the first region in a fixed preference list that the target prices, else the region with the most priced sizes.

| Provider | Preference list |
| - | - |
| AWS | `eu-central-1`, `eu-west-1`, `eu-north-1`, `eu-west-2`, `us-east-1` |
| Google Cloud | `europe-west1`, `europe-west3`, `europe-west4`, `us-central1` |
| Azure | `westeurope`, `northeurope`, `swedencentral`, `eastus` |

A hyperscaler whose catalogue has not been read yet is not offered as a target.

***

## vCPU classes

The `like_for_like` rule keeps each node group on the same vCPU class, shared or dedicated, when the target sells one. If no same-class size holds the group, the cheapest size that does is used and the mapping says so. Rate-carded providers (Proxmox VE, HPE Morpheus) have no class.

| Provider | Dedicated cores | Shared cores |
| - | - | - |
| Hetzner | CCX | CX, CPX |
| DigitalOcean | Dedicated-CPU droplets | Basic droplets |
| OVHcloud | B3, C3, R3 | Discovery |
| UpCloud | General Purpose, Premium, Cloud Native | Developer, Starter |
| AWS | Every current family except T | T |
| Google Cloud | Every Compute Engine family except E2 | E2 |
| Azure | D, E and F series | - |


# DigitalOcean Reference
Source: https://docs.ankra.ai/reference/digitalocean

Configuration options, regions, droplet sizes, and API endpoints for Ankra-managed DigitalOcean clusters.

Reference material for [DigitalOcean clusters](/guides/digitalocean-clusters).

***

## Cluster Configuration Options

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name |
| `credential_id` | *required* | DigitalOcean API credential ID |
| `ssh_key_credential_id` | *required* | SSH key credential ID |
| `region` | *required* | DigitalOcean region slug |
| `network_ip_range` | `10.0.0.0/16` | Private VPC IP range |
| `bastion_size` | `s-1vcpu-1gb` | Droplet size for the bastion host |
| `control_plane_count` | `1` | Number of control plane nodes (1 or 3) |
| `control_plane_size` | `s-2vcpu-4gb` | Droplet size for control planes |
| `worker_count` | `1` | Number of worker nodes (legacy, use `node_groups` instead) |
| `worker_size` | `s-2vcpu-4gb` | Droplet size for workers (legacy, use `node_groups` instead) |
| `node_groups` | | Array of node group definitions; `node_groups` wins when `worker_count` is also given |
| `distribution` | `kubeadm` | Kubernetes distribution (`kubeadm` or `k3s`) |
| `kubernetes_version` | *latest stable* | Kubernetes version (optional) |
| `cni` | `cilium` (kubeadm), `flannel` (k3s) | CNI plugin. Follows the distribution when omitted; kubeadm clusters always use `cilium` |
| `cni_features` | *all off* | CNI feature toggles, fixed at creation. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) |
| `etcd_topology` | `stacked` | kubeadm only. `stacked` or `external` (dedicated etcd droplets) |
| `etcd_node_count` | `3` | kubeadm `external` topology only (3 or 5) |
| `etcd_size` | `s-2vcpu-4gb` | kubeadm `external` topology only. Droplet size for etcd nodes |
| `include_networking` | `true` | Deploy the networking stack: Traefik, cert-manager and a `letsencrypt-prod` Let's Encrypt ClusterIssuer |
| `include_dns` | `true` | Give the cluster a delegated subdomain on `ankra.cc` with external-dns wired |

### DigitalOcean Regions

| Region | Location |
| - | - |
| `nyc3` | New York 3, United States |
| `sfo3` | San Francisco 3, United States |
| `ams3` | Amsterdam 3, Netherlands |
| `sgp1` | Singapore 1, Singapore |
| `lon1` | London 1, United Kingdom |
| `fra1` | Frankfurt 1, Germany |

> [!NOTE]
>
> Available regions and sizes depend on your account. Use `ankra cluster digitalocean regions` and `ankra cluster digitalocean sizes` to list what your credential can deploy.

### Common Droplet Sizes

| Size | vCPUs | RAM | Typical use |
| - | - | - | - |
| `s-1vcpu-1gb` | 1 | 1 GB | Bastion |
| `s-1vcpu-2gb` | 1 | 2 GB | Small workers |
| `s-2vcpu-4gb` | 2 | 4 GB | Control plane, general workers |
| `s-4vcpu-8gb` | 4 | 8 GB | Larger workloads |

***

## Node Group API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/digitalocean/{id}/node-groups` | GET | List all node groups |
| `/api/v1/clusters/digitalocean/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/digitalocean/{id}/node-groups/{name}/scale` | PUT | Scale a node group (0-100) |
| `/api/v1/clusters/digitalocean/{id}/node-groups/{name}/instance-type` | PUT | Change droplet size |
| `/api/v1/clusters/digitalocean/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/digitalocean/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/digitalocean/{id}/node-groups/{name}` | DELETE | Delete a node group |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/digitalocean/{id}/nodes` | GET | List all nodes (control plane, workers, bastion) |
| `/api/v1/clusters/digitalocean/{id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/digitalocean/{id}/nodes/{node_id}/restart` | POST | Restart a node (native reboot, falls back to power cycle) |
| `/api/v1/clusters/digitalocean/{id}/bastion/instance-type` | PUT | Resize the bastion instance type |

See [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [Bastion](/guides/operate-ankra-managed-clusters#bastion) for usage.

***

## Architecture

| Component | Description |
| - | - |
| **VPC** | Private network for inter-node communication |
| **NAT Gateway** | VPC NAT gateway providing outbound internet access for the private node Droplets |
| **Cloud Firewalls** | Two tag-scoped firewalls providing defence in depth; on clusters created before private-Droplet support they are the only ingress boundary |
| **Bastion Host** | Jump host Ankra uses to provision and manage nodes - the only Droplet reachable on SSH from the internet |
| **Control Plane(s)** | Kubernetes control plane Droplets |
| **Worker(s)** | Kubernetes worker Droplets organised in [node groups](/guides/operate-ankra-managed-clusters#node-groups) |
| **etcd Node(s)** | Dedicated etcd Droplets, only for kubeadm clusters with an `external` [etcd topology](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) |
| **SSH Keys** | Deployed to all Droplets for access |
| **Cloud Provider Stack** | DigitalOcean CCM and CSI for load balancers and block storage |

```mermaid theme={null}
flowchart TB
    Internet((Internet))
    Platform[Ankra Platform]

    subgraph VPC [DigitalOcean VPC + tag-scoped cloud firewalls]
        Bastion[Bastion droplet<br/>public + private IP]
        CP[Control plane droplets<br/>private IP only]
        Workers[Worker droplets<br/>private IP only]
        NAT[VPC NAT gateway<br/>VPC default route]
        Agent[Ankra Agent<br/>runs in the cluster]
    end

    LB[DigitalOcean Load Balancers<br/>created by the DO CCM]

    Platform -->|SSH port 22| Bastion
    Bastion -->|SSH jump over VPC| CP
    Bastion -->|SSH jump over VPC| Workers
    Agent -->|outbound only - NATS| Platform
    CP -->|egress| NAT
    Workers -->|egress| NAT
    NAT --> Internet
    Internet --> LB
    LB --> Workers
```

Cluster nodes are private Droplets with no public IP; the bastion is the only Droplet with a public address. Outbound traffic from the nodes (image pulls, package downloads, the Ankra Agent connection) leaves through the VPC NAT gateway. Inter-node and jump traffic stays on the VPC. Ankra deploys the **digitalocean-cloud-provider** stack (CCM and CSI) after the Ankra Agent is installed, backed by your API credential.


# Hetzner Reference
Source: https://docs.ankra.ai/reference/hetzner

Configuration options, locations, API endpoints, and the hcloud stack (CCM, CSI, ingress) for Ankra-managed Hetzner clusters.

Reference material for [Hetzner clusters](/guides/hetzner-clusters): every configuration parameter, datacenter location, and the details of the infrastructure Ankra provisions.

***

## Cluster Configuration Options

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name |
| `credential_id` | *required* | Hetzner API credential ID |
| `ssh_key_credential_ids` | *required* | Array of SSH key credential IDs |
| `ssh_key_credential_id` | | Single SSH key credential ID (backward compatible, use `ssh_key_credential_ids` for multiple) |
| `location` | *required* | Hetzner datacenter location |
| `network_ip_range` | `10.0.0.0/16` | Private network IP range |
| `subnet_range` | `10.0.1.0/24` | Subnet range within the network |
| `bastion_server_type` | *see below* | Server type for the bastion host |
| `control_plane_count` | `1` | Number of control plane nodes |
| `control_plane_server_type` | *see below* | Server type for control planes |
| `worker_count` | `1` | Number of worker nodes (legacy, use `node_groups` instead) |
| `worker_server_type` | *see below* | Server type for workers (legacy, use `node_groups` instead) |
| `node_groups` | | Array of node group definitions (see [Node groups](/guides/operate-ankra-managed-clusters#node-groups)) |
| `distribution` | `kubeadm` | Kubernetes distribution (`kubeadm` or `k3s`) |
| `kubernetes_version` | *stable* | Version for the chosen distribution: a plain upstream tag such as `v1.36.4` for `kubeadm`, a k3s build such as `v1.35.7+k3s1` for `k3s` (a bare patch resolves to its newest `+k3sN` build). A `+k3sN` build with `kubeadm` is refused. Omit it to install the version catalogue's stable version for the distribution |
| `include_networking` | `true` | Deploy the networking stack: Traefik, cert-manager and a `letsencrypt-prod` Let's Encrypt ClusterIssuer |
| `include_dns` | `true` | Give the cluster a delegated subdomain on `ankra.cc` with external-dns wired |
| `gitops_credential_name` | | GitHub credential name for GitOps integration |
| `gitops_repository` | | GitHub repository for GitOps (e.g., `org/repo`) |
| `gitops_branch` | `master` | Branch for GitOps pushes |

A server type you leave out is chosen from what the location can provision now: the cheapest available x86 type with at least 2 vCPU and 4 GB of memory for the bastion and workers, and at least 4 vCPU and 8 GB for the control plane and dedicated etcd nodes. Out-of-stock and deprecated types are skipped, and the response's `server_types` object (`bastion`, `control_plane`, `worker`, `etcd`) names the type each provisioned role got. If the location has no such type, the create is refused with the list of types it does offer. A server type you name is checked against the location, and refused with the available types of at least that size when the location cannot provision it. The `cx` line is often unavailable, so check `ankra cluster hetzner server-types --credential-id <id> --location <location>` and name types from its `AVAILABLE=yes` rows, for example `cpx12` for the bastion and `cpx22` for the control plane and workers.

### Hetzner Locations

| Location | Region |
| - | - |
| `fsn1` | Falkenstein, Germany |
| `nbg1` | Nuremberg, Germany |
| `hel1` | Helsinki, Finland |
| `ash` | Ashburn, USA |
| `hil` | Hillsboro, USA |
| `sin` | Singapore |

***

## Node Group API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/hetzner/{id}/node-groups` | GET | List all node groups |
| `/api/v1/clusters/hetzner/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/hetzner/{id}/node-groups/{name}/scale` | PUT | Scale a node group |
| `/api/v1/clusters/hetzner/{id}/node-groups/{name}/instance-type` | PUT | Upgrade instance type |
| `/api/v1/clusters/hetzner/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/hetzner/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/hetzner/{id}/node-groups/{name}` | DELETE | Delete a node group |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/hetzner/{id}/nodes` | GET | List all nodes (control plane, workers, bastion) |
| `/api/v1/clusters/hetzner/{id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/hetzner/{id}/nodes/{node_id}/restart` | POST | Restart a node (native reboot, falls back to power cycle) |
| `/api/v1/clusters/hetzner/{id}/bastion/instance-type` | PUT | Resize the bastion instance type |
| `/api/v1/clusters/hetzner/{id}/control-plane` | GET | Control plane count and instance type, and how each can change right now |
| `/api/v1/clusters/hetzner/{id}/control-plane/instance-type` | PUT | Change the control plane instance type. Resizing the only controller of a running cluster needs `accept_api_downtime: true` |

See [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node), [Bastion](/guides/operate-ankra-managed-clusters#bastion) and [Change the control plane instance type](/guides/operate-ankra-managed-clusters#change-the-control-plane-instance-type) for the dashboard and CLI equivalents.

## SSH Key API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/hetzner/{id}/ssh-keys` | GET | List current and available SSH keys |
| `/api/v1/clusters/hetzner/{id}/ssh-keys` | PUT | Update SSH keys on the cluster |
| `/api/v1/clusters/hetzner/{id}/access-info` | GET | Get bastion and control plane IPs |

***

## Architecture

A Hetzner cluster provisions the following infrastructure:

| Component | Description |
| - | - |
| **Bastion Host** | The only server with a public IP - SSH jump host *and* NAT gateway for all node egress |
| **Private Network** | Isolated network for inter-node communication |
| **Control Plane(s)** | Kubernetes control plane nodes (private IPs only) |
| **Worker(s)** | Kubernetes worker nodes organised in [node groups](/guides/operate-ankra-managed-clusters#node-groups), each with independent instance types, labels, and taints |
| **SSH Keys** | Deployed to all servers for access (multiple keys supported) |
| **External Cloud Provider** | k3s is configured with `cloud-provider=external` for Hetzner CCM compatibility |

```mermaid theme={null}
flowchart TB
    Internet((Internet))
    Platform[Ankra Platform]

    subgraph Network [Hetzner private network]
        Bastion[Bastion<br/>public + private IP<br/>NAT masquerade]
        CP[Control plane nodes<br/>private IP only]
        Workers[Worker nodes<br/>private IP only]
        Agent[Ankra Agent<br/>runs in the cluster]
    end

    LB[Hetzner Load Balancers<br/>created by the hcloud CCM]

    Platform -->|SSH to public IP| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    Agent -->|outbound only - NATS| Platform
    CP -->|default route| Bastion
    Workers -->|default route| Bastion
    Bastion -->|NAT| Internet
    Internet --> LB
    LB --> Workers
```

All nodes are deployed within a private Hetzner network and have no public IPs. The bastion host plays two roles:

* **SSH jump host** - Ankra provisions and manages nodes through it, and it is the entry point for `ssh -J` access.
* **NAT gateway** - a network route sends the nodes' default traffic (`0.0.0.0/0`) to the bastion, which masquerades it out through its public IP. All node egress - image pulls, package installs, and the Ankra Agent's outbound connection - flows through the bastion.

> [!WARNING]
>
> Because the bastion is the egress path on Hetzner, stopping or deleting it cuts off internet access for every node in the cluster. This differs from [OVH clusters](/reference/ovh#architecture), where egress uses a provider-managed gateway and the bastion is only a jump host.

Inbound traffic to workloads does not pass through the bastion: `LoadBalancer` services get Hetzner Load Balancers from the CCM, attached to nodes over the private network.

### Automatic Cloud Integration (hcloud Stack)

Ankra automatically deploys a **hcloud stack** during cluster provisioning. This stack includes:

1. **`hcloud` namespace** - dedicated namespace for Hetzner cloud components
2. **`hcloud-token` secret** - contains your Hetzner API token and network ID, sourced from the credential used to create the cluster
3. **[hcloud-cloud-controller-manager](https://github.com/hetznercloud/hcloud-cloud-controller-manager)** - integrates the cluster with Hetzner Cloud APIs (node metadata, load balancers, node lifecycle)
4. **[hcloud-csi](https://github.com/hetznercloud/csi-driver)** - provides persistent storage using Hetzner Cloud Volumes

The hcloud stack is deployed automatically after the Ankra Agent is installed. The CCM and CSI charts both depend on the `hcloud-token` secret, and Ankra ensures the correct dependency order.

> [!NOTE]
>
> You do not need to manually set up the CCM or CSI driver - they are provisioned as part of cluster creation using the same Hetzner API credential you provided.

### External Cloud Provider

Hetzner clusters are provisioned with `--kubelet-arg=cloud-provider=external` and `--disable-cloud-controller`. This configures k3s to delegate node initialization to the Hetzner Cloud Controller Manager.

When nodes first join the cluster, they carry a `node.cloudprovider.kubernetes.io/uninitialized` taint that prevents workload scheduling. The CCM removes this taint after initializing each node with its Hetzner provider ID, zone labels, and instance metadata. The Ankra Agent tolerates this taint so it can schedule immediately and begin managing the cluster before the CCM is fully running.

***

## Hetzner Cloud Controller Manager (hcloud-ccm)

The [Hetzner Cloud Controller Manager](https://github.com/hetznercloud/hcloud-cloud-controller-manager) is automatically deployed as part of the hcloud stack and provides:

* **Node metadata** - automatic zone, region, and instance type labels on nodes
* **Load Balancers** - Kubernetes `LoadBalancer` services backed by Hetzner Cloud Load Balancers
* **Node lifecycle** - automatic removal of deleted nodes from the cluster
* **Route management** - pod network routes via Hetzner Cloud Networks

The CCM is deployed in the `hcloud` namespace with 3 replicas and a PodDisruptionBudget. It reads the Hetzner API token from the `hcloud-token` secret that Ankra creates automatically.

### CCM Configuration

The default CCM values configured by Ankra:

```yaml theme={null}
replicaCount: 3
env:
  HCLOUD_TOKEN:
    valueFrom:
      secretKeyRef:
        name: hcloud-token
  HCLOUD_NETWORK_ROUTES_ENABLED:
    value: "false"
  HCLOUD_LOAD_BALANCERS_ENABLED:
    value: "true"
  HCLOUD_LOAD_BALANCERS_USE_PRIVATE_IP:
    value: "true"
  HCLOUD_LOAD_BALANCERS_DISABLE_PRIVATE_INGRESS:
    value: "true"
  HCLOUD_LOAD_BALANCERS_LOCATION:
    value: "<your-cluster-location>"
networking:
  enabled: true
  clusterCIDR: "10.0.0.0/16"
  network:
    valueFrom:
      secretKeyRef:
        name: hcloud-token
podDisruptionBudget:
  enabled: true
  minAvailable: 1
```

To customize the CCM configuration after creation, edit the `hcloud-cloud-controller-manager` addon in the `hcloud` stack via the Stack Builder.

> [!NOTE]
>
> The CCM creates Hetzner Cloud Load Balancers when you create Kubernetes `Service` resources of type `LoadBalancer`. Terminating the cluster deletes them, together with any Load Balancer attached to the cluster's network - see [Hetzner specifics](/guides/hetzner-clusters#hetzner-specifics).

***

## Hetzner CSI Driver (hcloud-csi)

The [Hetzner CSI Driver](https://github.com/hetznercloud/csi-driver) is automatically deployed as part of the hcloud stack and provides:

* **Dynamic provisioning** - create Hetzner Cloud Volumes on demand via `PersistentVolumeClaim`
* **Volume expansion** - resize volumes without downtime
* **Storage classes** - `hcloud-volumes` StorageClass available out of the box

### CSI Configuration

The default CSI values configured by Ankra:

```yaml theme={null}
controller:
  replicaCount: 3
  hcloudToken:
    existingSecret:
      name: hcloud-token
  podDisruptionBudget:
    enabled: true
node:
  hostNetwork: true
  hcloudToken:
    existingSecret:
      name: hcloud-token
      key: token
storageClasses:
  - name: hcloud-volumes
    defaultStorageClass: true
    reclaimPolicy: Retain
```

Once deployed, create PersistentVolumeClaims with `storageClassName: hcloud-volumes`:

```yaml theme={null}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-data
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: hcloud-volumes
  resources:
    requests:
      storage: 10Gi
```

> [!NOTE]
>
> The CSI driver creates Hetzner Cloud Volumes when you create PersistentVolumeClaims using the `hcloud-volumes` StorageClass. These Volumes are managed by Hetzner Cloud, not by Ankra. The default `reclaimPolicy` is `Retain`, meaning Hetzner Volumes are **not** deleted when PVCs are removed. Terminating the cluster lists the volumes its PersistentVolumes use and deletes them once you accept it; a volume labelled `ankra-retain` is kept - see [Terminate a cluster](/guides/operate-ankra-managed-clusters#terminate-a-cluster).

***

## Networking Stack

With `include_networking` on (the default), Ankra deploys a `networking` stack alongside the hcloud stack. It includes:

1. **[Traefik](https://traefik.io/)** - the Ingress controller (ingress class `traefik`, the cluster default) behind a Hetzner Cloud Load Balancer
2. **[cert-manager](https://cert-manager.io/)** - automated TLS certificate management
3. **Let's Encrypt ClusterIssuer** - a `letsencrypt-prod` ClusterIssuer configured for HTTP-01 validation through Traefik

With `include_dns` on (the default), the cluster also gets a delegated subdomain on `ankra.cc` and external-dns publishes Ingress hostnames into it.

### Load Balancer Configuration

Traefik's Service carries Hetzner Load Balancer annotations, and the balancer forwards over the private network with PROXY protocol so the client address reaches your workloads:

```yaml theme={null}
service:
  annotations:
    load-balancer.hetzner.cloud/location: "<your-cluster-location>"
    load-balancer.hetzner.cloud/use-private-ip: "true"
    load-balancer.hetzner.cloud/uses-proxyprotocol: "true"
```

Traefik and cert-manager each run two replicas with a PodDisruptionBudget of one. These values are applied when the cluster is created; later changes you make to them are kept.

### Using Ingress with TLS

Once the networking stack is deployed, create Ingress resources with automatic TLS:

```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - app.example.com
      secretName: my-app-tls
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app
                port:
                  number: 80
```

> [!TIP]
>
> Point your DNS record for `app.example.com` to the Hetzner Load Balancer IP that Traefik's Service creates, or use a hostname under the cluster's `ankra.cc` subdomain and let external-dns publish it. cert-manager handles the Let's Encrypt certificate issuance and renewal.


# ImportCluster YAML Schema
Source: https://docs.ankra.ai/reference/importcluster

Every field of the ImportCluster manifest - metadata, git_repository, stacks, manifests, add-ons, applications, parents, and SOPS encrypted_paths.

The `ImportCluster` manifest is the declarative entry point for onboarding a cluster into Ankra and describing its stacks. Apply it with the CLI:

```bash theme={null}
ankra cluster apply -f cluster.yaml --cluster my-cluster
```

`--cluster` targets the cluster you name, by name or id; without it the target is the manifest's `metadata.name`. `cluster apply` honours `--cluster` from CLI v0.16.0 - earlier versions ignore it and use `metadata.name`. The same schema is what Ankra reads from a connected [GitOps repository](/concepts/gitops).

> [!NOTE]
>
> `ankra cluster apply -f` sends neither `spec.log_source` nor `spec.helm_registries`. A sync from the connected Git repository reads `spec.log_source`, so put that block in a file Ankra syncs from Git. A sync does not read `spec.helm_registries`; the `spec.helm_registries[]` section below says what does. File paths such as `from_file` resolve against the cluster directory in a sync, and against the applied file's own directory in `ankra cluster apply -f`; see [Files in the cluster directory](#files-in-the-cluster-directory).

## Full Example

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
  description: Importing my Kubernetes cluster
spec:
  git_repository:
    provider: github
    credential_name: my-git-credential
    repository: my-org/my-gitops-repo
    branch: main
  stacks:
    - name: logging
      description: Stack for logging
      manifests:
        - name: namespace-fluent-bit
          parents: []
          from_file: "manifests/fluent-bit-namespace.yaml"
        - name: configmap-fluent-bit
          parents:
            - kind: manifest
              name: namespace-fluent-bit
          from_file: "manifests/fluent-bit-configmap.yaml"
          agents_md_from_file: "manifests/fluent-bit-configmap.AGENTS.md"
      addons:
        - name: fluent-bit
          chart_name: fluent-bit
          chart_version: 0.49.1
          registry_name: fluent
          registry_url: https://fluent.github.io/helm-charts
          namespace: fluent-bit
          parents:
            - kind: manifest
              name: configmap-fluent-bit
          agents_md_from_file: "addons/fluent-bit/AGENTS.md"
          configuration:
            from_file: "values/fluent-bit.yaml"
```

## Top Level

| Field | Required | Description |
| - | - | - |
| `apiVersion` | yes | Always `v1` |
| `kind` | yes | Always `ImportCluster` |
| `metadata.name` | yes | Cluster name - letters, digits, and hyphens only |
| `metadata.description` | no | Free-text description shown in the platform |
| `spec` | yes | The cluster specification |

## `spec.git_repository`

Connect a Git repository so stacks are stored and synced from Git. Omit the block entirely for a non-GitOps import.

| Field | Required | Description |
| - | - | - |
| `provider` | no | `github` (the default) or `bitbucket_cloud`. The legacy spelling `bitbucket` is read as `bitbucket_cloud`. Any other value, `bitbucket_data_center` and `bitbucket_dc` included, is refused with a `422` naming the accepted values; matching is case-sensitive, so `GitHub` is refused too |
| `credential_name` | yes | Name of a Git credential registered in Ankra |
| `repository` | yes, for GitHub | `owner/name` form, e.g. `my-org/my-gitops-repo`. For Bitbucket Cloud, `workspace/repo-slug` |
| `workspace`, `repo_slug` | no | Bitbucket Cloud only: the workspace and the repository slug, in place of `repository` |
| `branch` | yes | Branch Ankra reads from and pushes to. The cluster's GitOps settings list the repository's branches to pick from, for GitHub and Bitbucket Cloud alike |

Applying a changed `git_repository` block **repoints the cluster**. Ankra first writes the cluster's current state - every stack, add-on and manifest it manages, with secrets sealed under your organisation's key - to the new repository and branch as a commit, overwriting the files it manages there, and only then syncs from it. The new source does not need to be seeded by hand: the switch itself brings it to parity. Any branch works - a cluster is not tied to its repository's default branch, so one repository with a branch per environment is a supported layout - but the branch must already exist; Ankra does not create branches.

A repoint is refused until you acknowledge it: `ankra cluster apply --allow-repoint`, plus `--allow-repoint-destroying-data` when the cluster holds PersistentVolumeClaims. The refusal lists what the cluster runs today; it is not a diff against the target.

> [!WARNING]
>
> The switch is atomic. If the first write to the new source fails - the branch does not exist, the branch is protected against direct pushes, the credential's GitHub App installation cannot reach the repository - nothing changes: the cluster keeps syncing from its current source and the error names the cause. A missing branch is reported together with the branches the repository does have.
>
> From the switch on, the new source is authoritative: anything that later leaves it is pruned from the cluster, PersistentVolumeClaims included, unless one sync would remove a large share of the cluster, which is [held until you confirm it](/concepts/gitops#large-removals-are-held). Keep the repository's history if you may need to roll a change back.

## Observability sources in Git

`spec.prometheus_metrics` and `spec.log_source` connect the cluster's metrics and log data sources. Both are read back from the cluster document on every sync, so authoring or editing either block in Git connects the source and updates it - the same result as filling in the platform's [metrics](/integrations/prometheus) or [log source](/integrations/log-sources) settings.

Three rules apply to both members:

* **Credentials are never in Git.** `username`, `password`, `token` and `auth_scheme` inside a source block are refused by name, because ignoring them would leave a live secret sitting in your repository while you believe it is in effect. Create the credential in the platform and reference it by `credential_name`.
* **Unknown top-level fields are refused**, not ignored, and the error names the offending key and the accepted set. A mistyped field fails the sync rather than silently doing nothing.
* **Removing the block does not disconnect the source.** Git can create and update a source; only the platform can disconnect one.

> [!WARNING]
>
> Deleting `prometheus_metrics` or `log_source` from the file is not a disconnect. The source survives the sync, and the next time Ankra regenerates the cluster document the block comes back. To disconnect, remove the source in the cluster's **Settings** → **Integrations**; the platform then drops the block from Git on its own.
>
> This asymmetry is deliberate: reading "disconnect" out of an absent key is what deleted hand-written blocks before these members round-tripped, so a destructive change stays a platform action.

## `spec.prometheus_metrics`

The cluster's metrics data source. See [Prometheus](/integrations/prometheus) for endpoint examples per product.

| Field | Required | Description |
| - | - | - |
| `endpoint` | yes | Query endpoint the Ankra agent reaches from inside the cluster. `http://` or `https://`, or a scheme-less `host:port`. Any other scheme is refused, as is an endpoint containing whitespace or control characters |
| `credential_name` | no | Name of a metrics credential already registered in Ankra. Omitting it does not turn authentication off: a cluster that already has a saved metrics credential keeps sending it with every query (the **Metrics** panel under **Settings** → **Integrations** names it), and only a cluster with no saved metrics credential queries unauthenticated - ordinary for in-cluster Prometheus. A name that resolves to no credential on the cluster fails the sync |
| `flavor` | no | Which Prometheus-compatible product is behind the endpoint: `self_hosted`, `grafana_cloud`, or `victoria_metrics`. Affects the labels and placeholders the portal shows, not how the endpoint is queried |
| `verify_ssl` | no | Verify the endpoint's TLS certificate. Omitted means not verified, which is the historical behaviour for clusters that never set it |

```yaml theme={null}
spec:
  prometheus_metrics:
    endpoint: http://prometheus-operated.monitoring.svc.cluster.local:9090
    flavor: self_hosted
```

## `spec.log_source`

The cluster's log data source. See [Log Sources](/integrations/log-sources) for provider endpoints and field-mapping defaults.

| Field | Required | Description |
| - | - | - |
| `provider` | yes | `loki`, `elasticsearch`, or `opensearch`. Any other value is refused - the provider decides how the agent queries the store |
| `endpoint` | yes | Query endpoint the Ankra agent reaches from inside the cluster. Same rules as `prometheus_metrics.endpoint` |
| `credential_name` | no | Name of a log credential already registered in Ankra. Omit for an unauthenticated endpoint. A name that resolves to no credential on the cluster fails the sync |
| `tenant_id` | no | Loki tenant sent as `X-Scope-OrgID`, for multi-tenant Loki and Grafana Cloud |
| `index_pattern` | no | Elasticsearch/OpenSearch index pattern to search (default `*`) |
| `field_mappings` | no | Map of `timestamp`, `message`, `namespace`, `pod`, `container` to the paths your index actually uses. Keys outside that set are ignored rather than refused, so a mapping the platform wrote stays valid |
| `verify_ssl` | no | Verify the endpoint's TLS certificate. Omitted means not verified |

```yaml theme={null}
spec:
  log_source:
    provider: loki
    endpoint: http://loki-gateway.monitoring.svc:80
    credential_name: loki-read
    tenant_id: my-tenant
```

## `spec.helm_registries[]`

Declare the Helm registries the file's add-ons depend on. The import API reads this block: an import request to `POST /api/v1/clusters/import` that carries it, or a manifest applied with the `apply_cluster_manifest` [MCP tool](/platform/mcp-tools) (inline content only: the tool refuses `from_file`), connects any registry that is not already present before add-ons deploy. A declaration matching an existing registry (same name, same URL - org-scoped or global) is an idempotent no-op; a declaration whose name is taken by a registry with a different URL fails the import before anything is written. Credentials are referenced by name and must already exist, so secrets stay out of Git.

> [!WARNING]
>
> A sync from Git does not read `spec.helm_registries`, and `ankra cluster apply -f` does not send it. Connect the registry first with `ankra helm registries create` or in the portal; see [Adding a Registry](/guides/registries#adding-a-registry). Keep the block out of the cluster file in Git: the sync ignores it, and a cluster file you edited in Git stays yours, so a later change made in Ankra is applied to the cluster but does not reach that file, and the cluster reads **Diverged** until the two versions agree again or a person decides the file; see [Diverged files](/concepts/gitops#diverged-files). When a sync merges such a change with your commit, the regenerated file no longer carries the block.

| Field | Required | Description |
| - | - | - |
| `name` | yes | Registry name, referenced by add-ons via `registry_name` |
| `url` | yes | Registry URL - `https://...` for HTTP chart repositories, `oci://...` for OCI registries |
| `credential_name` | no | Name of a Helm registry credential registered in Ankra, for private registries |
| `exclude_charts` | no | Chart names to skip during indexing |

```yaml theme={null}
spec:
  helm_registries:
    - name: ory
      url: https://k8s.ory.com/helm/charts
    - name: private-hub
      url: oci://artifact.example.com/charts
      credential_name: example-harbor-pull
```

## `spec.stacks[]`

Each stack groups related manifests, add-ons, and applications.

| Field | Required | Description |
| - | - | - |
| `name` | yes | Stack name, unique within the cluster |
| `description` | no | Free-text description |
| `description_from_file` | no | Read the description from a file in the cluster directory, named by its path relative to that directory. See [Files in the cluster directory](#files-in-the-cluster-directory) |
| `deploy_wave` | no | Integer `>= 0` ordering stacks against each other - see [Deploy waves](#deploy-waves) |
| `variables` | no | Map of stack-scoped variables, referenced as `${{ ankra.NAME }}` - highest precedence in the [variable hierarchy](/concepts/variables) |
| `manifests` | no | List of [manifest entries](#spec-stacks-manifests) |
| `addons` | no | List of [add-on entries](#spec-stacks-addons) |
| `applications` | no | List of [application entries](#spec-stacks-applications) |
| `backup` | no | The stack's [backup policy](#spec-stacks-backup) |

### `spec.stacks[].backup`

Protecting a stack is one block. Ankra takes scheduled restore points of the stack into the [backup vault](/guides/backups) you name, on the schedule the block gives, through the same capture a manual restore point uses. For each CloudNativePG cluster it also writes the barman-cloud archiver into the cluster's member and keeps the object store the archiver writes into in a stack member of its own, `ankra-backup-policy-<stack>`; see [Protect a stack](/guides/backups#protect-a-stack) for what that does to the cluster.

`ankra cluster stacks protect <stack>` writes this same block without editing the file; `ankra cluster stacks unprotect <stack>` sets `enabled: false`. See [Protect a stack](/guides/backups#protect-a-stack).

| Field | Required | Description |
| - | - | - |
| `enabled` | no | `true` protects the stack; `false` removes protection. Default `false` |
| `vault` | when enabled | Name or id of the [backup vault](/guides/backups) restore points are written to |
| `schedule` | no | `hourly`, `daily`, `weekly`, or a five-field cron expression. Default `daily` |
| `retention.hourly` / `.daily` / `.weekly` / `.monthly` / `.yearly` | no | How many restore points of each calendar period to keep. `0` (the default) disables that tier |
| `retention.minimum_count` | no | Keep at least this many restore points however the tiers fall out |
| `retention.minimum_age` | no | A Go duration (`24h`, `720h`). Nothing younger than this is expired |
| `selection.databases` | no | Whether the stack's database clusters are captured. Default `true` |
| `selection.persistent_volume_claims` | no | Names of the volume data assets to capture. **Default empty** |
| `selection.confirm_exclude_databases` | when excluding | Required acknowledgement when `selection.databases` is `false` |

```yaml theme={null}
stacks:
  - name: platform
    backup:
      enabled: true
      vault: offsite
      schedule: daily
      retention:
        daily: 7
        weekly: 4
        monthly: 6
        minimum_count: 3
        minimum_age: 24h
      selection:
        databases: true
        persistent_volume_claims:
          - grafana/grafana-storage
    addons: [...]
```

> [!NOTE]
>
> **Protecting a stack does not sweep every volume in it.** Databases are captured by default, because a restore point without the database contents is the one nobody forgives. Volumes are captured only when you name them in `selection.persistent_volume_claims`, because a stack's namespaces routinely hold caches, scratch space and metrics storage that nobody wants copied to object storage every night. Use the stack's data inventory - `ankra cluster stacks data list <stack>` - to see the asset names.

> [!WARNING]
>
> **Excluding databases needs an acknowledgement.** Setting `selection.databases: false` requires `selection.confirm_exclude_databases: true` in the same block, and the stack then carries a standing warning: its restore points bring back volumes and configuration, but no database contents. The acknowledgement covers the write that carried it - a later edit that keeps databases excluded has to say so again.

**An omitted block never removes protection.** A file that does not mention `backup` leaves the stored policy exactly as it was. That is deliberate: `ankra cluster apply` replaces a stack with what the file says, and an older CLI or a hand-written file that simply did not know about the block would otherwise unprotect the stack in silence. Removing protection is `backup: {enabled: false}` - something a person typed. When an apply does narrow protection, the result carries a warning naming what is no longer covered.

The schedule itself is **never stored as a stack member**: it is read from this block every time the stack is due, so no apply, clone or profile capture can leave a stack with a schedule that no longer matches its policy. The two things protect does write into the stack for a CloudNativePG cluster - the archiver on the `Cluster` and the `ankra-backup-policy-<stack>` member holding its object store - are Ankra's: a clone and a profile capture leave both out and say so. An apply that replaces the stack from a file without them heals in two ways, depending on what the file dropped. If only the object store member went, the next restore point - scheduled or manual - puts it back, because that restarts nothing. If the archiver itself went, scheduled backups are skipped with `archiver_not_wired` until you protect the stack again or take a restore point by hand; either puts the archiver back and restarts the instances once.

### Deploy waves

`deploy_wave` sequences whole stacks: a stack in wave N starts deploying only after every stack in a lower wave finished successfully, and teardown unwinds in reverse wave order. Stacks in the same wave deploy in parallel, and stacks without a `deploy_wave` stay independent of the ordering entirely - existing clusters keep their current behaviour.

```yaml theme={null}
stacks:
  - name: infrastructure     # cert-manager, ingress, storage
    deploy_wave: 1
    addons: [...]
  - name: platform           # databases, message queues
    deploy_wave: 2
    addons: [...]
  - name: applications       # your workloads
    deploy_wave: 3
    addons: [...]
  - name: monitoring         # independent: deploys any time
    addons: [...]
```

Wave numbers do not need to be contiguous - `1, 5, 20` works and leaves room to slot stacks in later. If a stack in wave N fails, later waves stay blocked until it is fixed or removed. Within a stack, [parents](#parents) still control resource-level order.

### Files in the cluster directory

A cluster that syncs from Git reads one directory in the repository: the cluster's directory, `clusters/<cluster-name>-<short-id>/` for a cluster Ankra writes. The file in it named after the cluster, `<cluster-name>.yaml`, is the only file read as a cluster definition. Every other file in the directory, in subdirectories too, is content that an entry names by its path relative to the directory:

* `from_file` on a manifest or an application, and `configuration.from_file` on an add-on, name the YAML content.
* `agents_md_from_file` on a manifest or an add-on names its AGENTS.md file.
* `description_from_file` on a stack names its description.

Each path is looked up exactly as written. There is no folder or wildcard form, a path outside the directory never matches, and a symlink is never followed. A manifest, add-on, application or stack description whose file is not in the directory stops the sync, and nothing from it is applied; a missing AGENTS.md file is skipped. `encrypted_paths` is not a file reference: it lists key names.

With `stacks/logging/README.md`, `manifests/logging-namespace.yaml` and `values/fluent-bit.yaml` in the cluster directory, a stack reads:

```yaml theme={null}
stacks:
  - name: logging
    description_from_file: stacks/logging/README.md
    manifests:
      - name: logging-namespace
        from_file: manifests/logging-namespace.yaml
    addons:
      - name: fluent-bit
        chart_name: fluent-bit
        chart_version: 0.49.1
        registry_name: fluent
        registry_url: https://fluent.github.io/helm-charts
        namespace: logging
        configuration:
          from_file: values/fluent-bit.yaml
        parents:
          - kind: manifest
            name: logging-namespace
```

A file at `stacks/<stack>/manifests/<name>.yaml` (or `.yml`) that no entry already names, for a stack the cluster file declares, is added to that stack as a manifest called `<name>`, unless a stack already lists that name. If two declared stacks offer the same unlisted name, the sync stops until you list it under the stack you mean.

`ankra cluster apply -f` resolves the same keys on your machine, against the directory the applied file is in, and refuses a path that is absolute or contains `..`; applied from its place in the cluster directory, the cluster file resolves the same `from_file` paths a sync does. It does not add unlisted manifest files. The CLI also accepts inline content (`manifest`, `manifest_base64`, `configuration.values`, `configuration.values_base64`). A sync from Git reads a manifest's content only from its file: it refuses `manifest_base64` in the cluster file and does not read `manifest`.

## `spec.stacks[].manifests[]`

Raw Kubernetes YAML resources.

| Field | Required | Description |
| - | - | - |
| `name` | yes | Manifest name, unique within the cluster. The name is the manifest's identity: renaming it is a delete of the old manifest plus a create of the new one, see the warning below |
| `from_file` | one of | Path of the YAML file, relative to the cluster directory. See [Files in the cluster directory](#files-in-the-cluster-directory) |
| `manifest` / `manifest_base64` | one of | Inline content, for `ankra cluster apply -f` only (the CLI accepts plain YAML under `manifest:` and encodes it). A sync from Git refuses `manifest_base64` and does not read `manifest` |
| `parents` | no | [Dependency edges](#parents) - deploy only after these succeed |
| `encrypted_paths` | no | Key names Ankra seals with SOPS when it writes the manifest to Git. An entry names a key, not a location: every key of that name is sealed at every depth - see [What an Entry Actually Matches](/guides/sops#what-an-entry-actually-matches). On an update, omit it to keep the stored declaration; an explicit `[]` sent over the API clears it, while the CLI drops an empty list - see [An Empty or Absent Declaration](/guides/sops#an-empty-or-absent-declaration) |
| `force` | no | Replace the live object on conflict instead of failing (default `false`) |
| `auto_remediate` | no | Re-apply automatically when drift is detected (default `false`) |
| `group` | no | Organizational grouping label within the stack (max 63 characters). Purely visual - grouping resources never changes deployment order and never triggers a redeploy |
| `agents_md` | no | Inline markdown of operational learnings for this manifest - see [AGENTS.md](/platform/agents-md). Documentation-only - never triggers a redeploy |
| `agents_md_from_file` | no | Path of an AGENTS.md file to read the content from instead of inlining it, relative to the cluster directory |
| `dependencies_override` | no | Advanced: override computed dependency ordering |

> [!WARNING]
>
> **Renaming a manifest deletes its resources.** Ankra identifies a manifest by its `name`, not by its content. When a stack is applied (with `ankra cluster apply`, a GitOps sync, or an edit in the portal) and a manifest name is no longer present, Ankra removes that manifest and runs the equivalent of `kubectl delete` on every object in its stored YAML. A manifest that appears under a new name is applied as a new manifest, and nothing orders that apply against the delete of the old one.
>
> For a manifest that holds a `Namespace`, this deletes the namespace and every PersistentVolumeClaim in it. For a manifest that holds PVCs, the delete removes the PVCs the new manifest has just applied. With a StorageClass whose `reclaimPolicy` is `Delete` (the default for most CSI drivers, including AWS EBS gp3), the underlying volumes are destroyed as well.
>
> Keep the names of manifests that own namespaces or stateful resources fixed. If you must rename one, move its data first, or make sure the PersistentVolumes behind it use `reclaimPolicy: Retain`. See [Protect Persistent Data Before Changing a Stack](/guides/protect-persistent-data).

## `spec.stacks[].addons[]`

Helm releases.

| Field | Required | Description |
| - | - | - |
| `name` | yes | Add-on name, unique within the cluster |
| `chart_name` | yes | Chart name in the registry |
| `chart_version` | yes | Exact chart version - pin it, especially in production |
| `registry_name` | yes | Name of the Helm registry connected in Ankra - see [Registries](/guides/registries) |
| `registry_url` | yes | URL of that registry, e.g. `https://fluent.github.io/helm-charts` |
| `namespace` | yes | Target namespace for the release. Must be a valid Kubernetes namespace name ([RFC 1123 DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names)): 1-63 characters, lowercase letters, digits and `-`, starting and ending with a letter or digit. Short names like `ory` are fine. `ankra cluster validate` enforces the same rules as apply |
| `registry_credential_name` | no | Credential for private registries |
| `configuration.values` / `values_base64` | no | Helm values, inline: `values` as YAML text, `values_base64` base64-encoded. A sync from Git reads `values_base64` and does not read `values`; `ankra cluster apply -f` accepts both |
| `configuration.from_file` | no | Path of a values file, relative to the cluster directory |
| `configuration.encrypted_paths` | no | Values paths that are SOPS-encrypted; see [SOPS](/guides/sops). Same empty-versus-absent rule as a manifest's `encrypted_paths` |
| `parents` | no | [Dependency edges](#parents) |
| `settings` | no | Sync behaviour for the add-on (automated sync, prune, self-heal, retry) - see below |
| `namespace_migration_strategy` | no | How to handle a namespace change on update |
| `job_configuration` | no | Per-add-on job timeouts (`read_job_timeout`, `update_job_timeout`, `delete_job_timeout`) |
| `group` | no | Organizational grouping label within the stack (max 63 characters). Purely visual - never triggers a redeploy |
| `agents_md` | no | Inline markdown of operational learnings for this add-on - see [AGENTS.md](/platform/agents-md). Documentation-only - never triggers a redeploy |
| `agents_md_from_file` | no | Path of an AGENTS.md file to read the content from instead of inlining it, relative to the cluster directory |

### `settings` defaults

Sync behaviour defaults to fully automated. See [Add-on Settings](/concepts/addon-settings) for semantics.

```yaml theme={null}
settings:
  sync_policy:
    automated: true
    auto_prune: true
    self_heal: true
    sync_options:
      - CreateNamespace=true
      - ServerSideApply=true
  retry_policy:
    limit: 5
    backoff_duration: 5s
    backoff_factor: 2
    backoff_max: 3m
```

## `spec.stacks[].applications[]`

Deployments of [Applications](/concepts/applications) created in Ankra.

| Field | Required | Description |
| - | - | - |
| `name` | yes | Application resource name |
| `platform_application_id` | no | The Ankra application to deploy |
| `platform_application_version` | no | Pinned application version |
| `from_file` | no | Path of the YAML file holding the application's Kubernetes manifest, relative to the cluster directory. Ankra writes an application's manifest to `stacks/<stack>/applications/<name>/manifest.yaml` unless this names another path. A sync from Git reads an application's content only from this file. See [Files in the cluster directory](#files-in-the-cluster-directory) |
| `namespace` | no | Target namespace |
| `parameters` | no | Map of application parameters |
| `parents` | no | [Dependency edges](#parents) |
| `group` | no | Organizational grouping label within the stack (max 63 characters). Purely visual - never triggers a redeploy |

## Parents

`parents` are the dependency edges that control deployment order: a resource deploys only after all of its parents succeed. Every parent is a `kind` + `name` pair - write both keys:

```yaml theme={null}
parents:
  - kind: manifest
    name: namespace-fluent-bit
  - kind: addon
    name: cert-manager
```

`kind` must be `manifest` or `addon`, and the parent must be defined somewhere in the same file. Namespace manifests must be parents of everything deployed into that namespace.

Parents reference the other resource by `name`. Because a rename is a delete plus a create (see the [manifests](#spec-stacks-manifests) warning), renaming a parent also means updating every `parents` entry that points at it in the same change.

> [!WARNING]
>
> The shorthand `- manifest: <name>` does **not** work. It parses to an empty parent and the
> dependency edge is silently dropped - the resource deploys unordered, and both local and
> server-side validation still pass, because parent names are never resolved. Verify what was
> actually stored with `ankra cluster stacks list <stack> -o json`, which echoes each resource's
> real `parents`.

## Validation

`ankra cluster apply` validates the file before sending anything: unknown fields, missing parents, and invalid parent kinds are rejected with the offending path. Use `--dry-run` to validate without applying.

`ankra cluster validate -f cluster.yaml` is the server-side pre-flight gate, built for CI: it runs every rule apply enforces without touching the cluster. That covers structure (duplicate names, missing parents, dependency cycles), chart resolution (registry connected, chart exists, pinned version exists), plaintext-secret detection, and the per-resource field rules - add-on namespaces (Kubernetes DNS label: 1-63 characters, lowercase letters, digits and `-`, starting and ending with a letter or digit), group names, and empty manifest bodies. Pass `--cluster <id>` to additionally validate against that cluster's live resources, exactly as an apply to it would.

`validate` also warns when a declared `encrypted_paths` entry seals more keys than the one it names (category `encrypted_paths_over_match`, see [What an Entry Actually Matches](/guides/sops#what-an-entry-actually-matches)). The warning is computed from the entries you declare, so a resource with an empty declaration never produces one, and `ankra cluster apply` does not report it - run `validate` first when a pipeline drives the API.


# Managed Kubernetes Reference
Source: https://docs.ankra.ai/reference/managed-kubernetes

Provider kinds, API endpoints, and provider-specific option blocks for Cloud Managed Kubernetes (DOKS, UKS, GKE, OVHcloud MKS, AKS, EKS, Scaleway Kapsule).

Reference material for [Managed Kubernetes](/guides/managed-kubernetes).

***

## Provider kinds

The `{provider}` path segment in every endpoint below is one of:

| Provider kind | Service | Location field |
| - | - | - |
| `doks` | [DigitalOcean Kubernetes](/guides/doks-clusters) | region |
| `uks` | [UpCloud Managed Kubernetes](/guides/uks-clusters) | zone |
| `gke` | [Google Kubernetes Engine](/guides/gke-clusters) | location (zone or region) |
| `ovh_mks` | [OVHcloud Managed Kubernetes](/guides/ovh-mks-clusters) | region |
| `aks` | [Azure Kubernetes Service](/guides/aks-clusters) | location |
| `eks` | [Amazon EKS](/guides/eks-clusters) | region |
| `kapsule` | [Scaleway Kapsule](/guides/managed-kubernetes#scaleway-kapsule-closed-beta) (Closed Beta) | region |

> [!NOTE]
>
> The CLI accepts these values via `--provider` (`ovh-mks` and `mks` are accepted as aliases for `ovh_mks`).

***

## API Reference

All endpoints are bearer-token authenticated under `/org/clusters/managed/{provider}`.

| Endpoint | Method | Description |
| - | - | - |
| `/org/clusters/managed/{provider}/options` | GET | Live regions, versions, sizes, plans, and capabilities for a `credential_id` |
| `/org/clusters/managed/{provider}/discover` | GET | Discover existing clusters at the provider for a `credential_id` |
| `/org/clusters/managed/{provider}/preflight` | POST | Run provider preflight checks without creating |
| `/org/clusters/managed/{provider}/import` | POST | Adopt a discovered cluster into Ankra |
| `/org/clusters/managed/{provider}` | POST | Create a managed cluster |
| `/org/clusters/managed/{provider}/{cluster_id}` | DELETE | Deprovision a managed cluster (`?force=true` to bypass idle checks) |
| `/org/clusters/managed/{provider}/{cluster_id}/node-pools` | GET | List node pools |
| `/org/clusters/managed/{provider}/{cluster_id}/node-pools` | POST | Add a node pool |
| `/org/clusters/managed/{provider}/{cluster_id}/node-pools/{name}/scale` | POST | Scale a node pool to a fixed count |
| `/org/clusters/managed/{provider}/{cluster_id}/node-pools/{name}` | PATCH | Update a node pool (count and/or autoscaling bounds), or hand its count to an external autoscaler with `externally_managed` |
| `/org/clusters/managed/{provider}/{cluster_id}/node-pools/{name}` | DELETE | Delete a node pool |
| `/org/clusters/managed/{provider}/{cluster_id}/node-pools/{name}/replace` | POST | Replace a pool's machine size blue/green (create new pool, wait ready, delete old) |
| `/org/clusters/managed/{provider}/{cluster_id}/upgrades` | GET | List available Kubernetes upgrade targets |
| `/org/clusters/managed/{provider}/{cluster_id}/upgrade` | POST | Upgrade the Kubernetes version |
| `/org/clusters/managed/{provider}/{cluster_id}/stop` | POST | Stop the cluster (providers advertising `supports_stop_start`; AKS today) |
| `/org/clusters/managed/{provider}/{cluster_id}/start` | POST | Start a stopped cluster |

> [!NOTE]
>
> The `ankra cluster managed` CLI covers `create`, `delete`, `node-pool add|scale|update|delete`, `upgrade`, `stop`/`start`, and `discover`/`import` (v0.11.0 or later). Live options, preflight, and pool size replacement are portal/API only.

Every pool in the `node-pools` listing carries `externally_managed` (boolean) and `observed_count` (integer or null). A `PATCH` whose body is only `{"externally_managed": true}` hands the pool's node count to something outside Ankra, such as a cluster autoscaler you run; sending it beside any other field is refused. While the flag is set, scale, a `count` update, delete and size replacement answer `409` with `Node pool is externally managed; clear externally_managed before changing it through Ankra`, `count` stays the last value Ankra wrote, and `observed_count` is what the provider reports now (null when it could not be read). `{"externally_managed": false}` hands the pool back and adopts the provider's current count. See [externally managed node pools](/guides/managed-kubernetes#externally-managed-node-pools).

Managed node pool machine sizes are immutable at every provider, so changing a pool's size is a **blue/green replacement**: Ankra creates a pool with the new size (copying count, labels, taints, and autoscaling), waits until it is ready, then deletes the old pool. Expect transient double capacity while both pools exist; workloads are rescheduled by Kubernetes when the old pool is removed. Whether a provider supports stop/start is advertised per provider as `supports_stop_start` in the `/options` capabilities.

***

## Provider-specific option blocks

| Provider | Block | Fields |
| - | - | - |
| DOKS | top level | `ha` - highly available control plane |
| UKS | top level | `cluster_plan` (`development` / `production`); GPU pools take `gpu_plan.storage_size` |
| GKE | `gke` | `release_channel` (`RAPID`, `REGULAR`, `STABLE`), `mode` (`standard` or `autopilot`) |
| OVH MKS | `ovh_mks` | `plan` (`free`, `standard`), `private_network_id`, `anti_affinity`, `monthly_billed`, `update_policy` |
| AKS | `aks` | `resource_group`, `network_plugin` (`azure`, `kubenet`), `private_cluster`, `sku_tier` (`Free`, `Standard`, `Premium`) |
| EKS | `eks` | `subnet_ids`, `security_group_ids`, `enable_control_plane_logging` |
| Kapsule | `kapsule` | `private_network_id` (required), `private_endpoint` (must be `false`); top-level `cni` (`cilium`, `cilium_native`, `calico`); pools take `zone`, `root_volume_type` (`l_ssd`, `b_ssd`, `sbs_5k`, `sbs_15k`), `root_volume_size_gb`, `security_group_id`, `public_ip`, `autohealing`, `upgrade_policy` (`surge`, `unavailable`, `balanced`) |


# Managed Service Settings
Source: https://docs.ankra.ai/reference/managed-services

Every setting of the seven Ankra managed services, with its range, default and unit, and what it changes in the running service - and what Ankra checks for each service's health and readiness.

> [!WARNING]
>
> **Closed beta.** These settings belong to [Managed services](/concepts/managed-services), which is in closed beta and enabled per organisation on request. [Contact support](/platform/support) to have it turned on for your organisation.

You choose these settings when you [set up a service](/guides/set-up-a-managed-service). Each one is a whole number within its range, and a field left empty takes the default. Changing a running service's settings from **Managed services** is not available yet, so size it for what you need from the start.

Three rules hold for every service:

* `memory_mib` is both the memory request and the limit, so the service is capped at it.
* `cpu_millicores` is a CPU request, where 1000 is one core. CPU is not capped.
* `storage_gib` is the size of each volume, taken from the cluster's default StorageClass. A volume never shrinks, and it can only grow where the StorageClass allows volume expansion.

## PostgreSQL

Package `postgresql` 1.0.0: PostgreSQL 18.6, run by the CloudNativePG operator.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `instances` | 1 to 3 | 1 | One primary plus `instances - 1` streaming replicas, spread across nodes where the cluster has more than one. 1 is a single database with no failover; 3 survives the loss of one node, with automatic failover. Each instance has its own volume. |
| `storage_gib` | 1 to 1000 GiB | 10 | Size of each instance's data volume. |
| `memory_mib` | 256 to 16384 MiB | 512 | Memory for each instance. PostgreSQL's `shared_buffers` stays at its 128 MB default, so the rest serves as file cache and per-connection working memory. |
| `cpu_millicores` | 100 to 8000 | 250 | CPU request for each instance. |

With one instance, a voluntary drain of the database's node waits until you add instances: the operator's PodDisruptionBudget holds it, rather than moving the only copy of the data.

## Valkey

Package `valkey` 1.0.0: Valkey 9.1.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `replicas` | 0 to 2 | 0 | Read-only replicas of the primary, served through the read-replicas address. 0 is a single primary. Replicas add read capacity and a warm copy of the data, but they do not take over writes while the primary is down. |
| `memory_mib` | 128 to 16384 MiB | 256 | Memory for each pod. The cache holds at most 60% of it, then evicts the least recently used keys. |
| `storage_gib` | 1 to 100 GiB | 2 | Size of each pod's snapshot volume. It needs to hold one snapshot of the data, which is at most 60% of `memory_mib`. Snapshots let a restarted pod come back with its data. |
| `cpu_millicores` | 50 to 4000 | 100 | CPU request for each pod. |

## NATS

Package `nats` 1.0.0: NATS 2.15 with JetStream.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `replicas` | 1 | 1 | Number of servers. This version runs a single server. |
| `storage_gib` | 1 to 1000 GiB | 10 | Size of the JetStream volume. Streams may use up to 90% of it. |
| `memory_mib` | 128 to 16384 MiB | 256 | Memory for the server. Its Go runtime is told to stay under 80% of it. |
| `cpu_millicores` | 50 to 4000 | 100 | CPU request for the server. |

## OpenSearch

Package `opensearch` 1.0.0: OpenSearch 3.9, as a single node with the security plugin on.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `storage_gib` | 5 to 1000 GiB | 20 | Size of the data volume. OpenSearch stops accepting writes when it is 95% full. |
| `memory_mib` | 1024 to 32768 MiB | 2048 | Memory for the node. Half of it is the JVM heap; the rest is left to the operating system's file cache, which OpenSearch depends on. |
| `cpu_millicores` | 250 to 8000 | 500 | CPU request for the node. |

## SeaweedFS

Package `seaweedfs` 1.0.0: SeaweedFS 4.48 with an S3-compatible API, as one pod on one volume.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `storage_gib` | 1 to 2000 GiB | 20 | Size of the data volume, which holds every object. |
| `memory_mib` | 256 to 16384 MiB | 512 | Memory for the pod. |
| `cpu_millicores` | 100 to 8000 | 250 | CPU request for the pod. |

## VictoriaLogs

Package `victoria-logs` 1.0.0: VictoriaLogs 1.52, as a single server.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `retention_days` | 1 to 365 days | 14 | Days a log line is kept before it is deleted. Once the volume is 80% full, the oldest data is deleted first, so logs that arrive faster than `storage_gib` allows for can go sooner. |
| `storage_gib` | 1 to 1000 GiB | 20 | Size of the log volume. |
| `memory_mib` | 256 to 16384 MiB | 512 | Memory for the server. |
| `cpu_millicores` | 100 to 8000 | 250 | CPU request for the server. |

## VictoriaMetrics

Package `victoria-metrics` 1.0.0: VictoriaMetrics 1.153, as a single server.

| Setting | Range | Default | What it changes |
| - | - | - | - |
| `retention_days` | 1 to 3650 days | 30 | Days a sample is kept before it is deleted. |
| `storage_gib` | 1 to 1000 GiB | 20 | Size of the data volume. VictoriaMetrics stops accepting writes when it is full. |
| `memory_mib` | 256 to 16384 MiB | 512 | Memory for the server. VictoriaMetrics sizes its caches to 60% of it. |
| `cpu_millicores` | 100 to 8000 | 250 | CPU request for the server. |

## Health checks

Ankra decides a service's [health](/concepts/managed-services#health) from these checks, read from its synced view of the service's cluster, in the service's namespace.

| Service | Workload, ready against the plan | Kubernetes Service | Secret, with every key [the connection lists](/guides/connect-to-a-managed-service#addresses-and-secrets) |
| - | - | - | - |
| PostgreSQL | CloudNativePG pods labelled `cnpg.io/cluster=postgresql`: the primary Ready, `instances` pods Ready, and one `Bound` volume claim per instance | `postgresql-rw` | `postgresql-app` |
| Valkey | StatefulSet `valkey`, `1 + replicas` ready | `valkey` | `valkey-credentials` |
| NATS | StatefulSet `nats`, `replicas` ready | `nats` | `nats-credentials` |
| OpenSearch | StatefulSet `opensearch`, 1 ready | `opensearch` | `opensearch-credentials` |
| SeaweedFS | Deployment `seaweedfs-all-in-one`, 1 available | `seaweedfs-all-in-one` | `seaweedfs-s3-secret` |
| VictoriaLogs | StatefulSet `victoria-logs`, 1 ready | `victoria-logs` | `victoria-logs-credentials` |
| VictoriaMetrics | StatefulSet `victoria-metrics`, 1 ready | `victoria-metrics` | `victoria-metrics-credentials` |

Every service is also checked for the stack that owns it: a member that failed to apply or is being removed, or a stack that is gone or being removed, reads `degraded`.

| Value | Applies to |
| - | - |
| About 1 minute | How often each service is observed |
| 5 minutes | How long an observation stands before it reads `unknown` |
| 15 minutes | How recent Ankra's view of a resource type on the cluster must be for a missing object to count as missing; older reads `unknown` |
| 10 minutes (PostgreSQL, OpenSearch), 5 minutes (the others) | Grace window after a successful deployment, during which a failing check reads `progressing` |
| 30 minutes | How long after its last write a stack member's apply still counts as in progress |

## Readiness check

Every service has a [readiness](/concepts/managed-services#readiness) check: a short-lived pod the cluster's agent starts in the service's namespace, which connects to the service's primary address as a client would. `<service>` stands for the service name.

| Service | Image | Credentials, by reference from the service's Secret |
| - | - | - |
| PostgreSQL | `postgres:16-alpine` | `password` of `postgresql-app` |
| Valkey | `valkey/valkey:9.1.2-alpine` | `username` and `password` of `valkey-credentials` |
| NATS | `natsio/nats-box:0.19.3` | `username` and `password` of `nats-credentials` |
| OpenSearch | `curlimages/curl:8.16.0` | `username`, `password` and `ca.crt` of `opensearch-credentials` |
| SeaweedFS | `curlimages/curl:8.16.0` | `admin_access_key_id` and `admin_secret_access_key` of `seaweedfs-s3-secret` |
| VictoriaLogs | `curlimages/curl:8.16.0` | `username` and `password` of `victoria-logs-credentials` |
| VictoriaMetrics | `curlimages/curl:8.16.0` | `username` and `password` of `victoria-metrics-credentials` |

Every check image, PostgreSQL's included, is pinned by digest as well as the tag shown, and the digest decides what the cluster pulls. What each check does is listed under [Readiness](/concepts/managed-services#readiness). The PostgreSQL check runs `psql -h postgresql-rw.<service>.svc.cluster.local -p 5432 -U app -d app -c "SELECT 1"`.

| Property | Value |
| - | - |
| Pod label | `app.kubernetes.io/name=ankra-postgres-connection-test` for PostgreSQL, `app.kubernetes.io/name=ankra-service-canary` for the others. The pod is deleted when it finishes. |
| Credential values | Passed to the pod by reference. They never leave the cluster. |
| Interval | About every 5 minutes, measured from the last attempt |
| Result stands | 15 minutes |
| Pod time limit | 60 seconds |
| Grace window | While no check has passed yet: 10 minutes after a successful deployment for PostgreSQL and OpenSearch, 5 minutes for the other services |
| Agent | The checks for services other than PostgreSQL need an agent recent enough to run them. Until it is, the service reads `unverified` and `readiness_check.reason` says to upgrade the agent. |

At most one check pod runs on a cluster at a time.

## Related

> [card] [Set up a managed service](/guides/set-up-a-managed-service)
>
> Where these settings are chosen.

> [card] [Connect to a managed service](/guides/connect-to-a-managed-service)
>
> Addresses and credentials for each service.

> [card] [Managed services](/concepts/managed-services#health-and-readiness)
>
> What each health and readiness state means.


# Morpheus Reference
Source: https://docs.ankra.ai/reference/morpheus

Configuration options and API endpoints for Ankra-managed Morpheus clusters.

Reference material for [Morpheus clusters](/guides/morpheus-clusters).

> [!WARNING]
>
> Morpheus cluster provisioning is in [closed beta](/guides/morpheus-clusters).

***

## Cluster Configuration Options

All Morpheus IDs are the numeric IDs from your appliance - discover them in the portal's create wizard or with the catalog API routes (groups, clouds, networks, layouts, plans).

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name |
| `credential_id` | *required* | Morpheus API credential ID |
| `ssh_key_credential_id` | *required* | SSH key credential ID |
| `group_id` | *required* | Numeric ID of the Morpheus group to provision into |
| `cloud_id` | *required* | Numeric ID of the Morpheus cloud to provision into |
| `network_id` | *required* | Numeric ID of the network the instances attach to (must provide DHCP) |
| `layout_id` | *required* | Numeric ID of the instance layout to provision from |
| `virtual_image_id` | | Numeric ID of a virtual image to pin (optional) |
| `bastion_plan_id` | *required* | Numeric service plan ID for the bastion instance |
| `control_plane_count` | `1` | Number of control plane nodes (1, 3, or 5) |
| `control_plane_plan_id` | *required* | Numeric service plan ID for control planes |
| `worker_count` | `1` | Number of worker nodes (legacy, use `node_groups` instead) |
| `worker_plan_id` | *required* | Numeric service plan ID for workers; required even when `node_groups` is given |
| `node_groups` | | Array of node group definitions sized by numeric `plan_id` |
| `distribution` | `kubeadm` | Kubernetes distribution (`kubeadm` or `k3s`) |
| `kubernetes_version` | *latest stable* | Kubernetes version (optional) |
| `cni` | `cilium` (kubeadm), `flannel` (k3s) | CNI plugin. Follows the distribution when omitted; kubeadm clusters always use `cilium` |
| `etcd_topology` | `stacked` | kubeadm only. `stacked` or `external` (dedicated etcd instances) |
| `etcd_node_count` | `3` | kubeadm `external` topology only (3 or 5) |
| `etcd_plan_id` | | kubeadm `external` topology only. Numeric service plan ID for etcd nodes |

> [!NOTE]
>
> Cost estimates are not available for Morpheus clusters.

***

## Node Group API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/morpheus/{id}/node-groups` | GET | List all node groups |
| `/api/v1/clusters/morpheus/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/morpheus/{id}/node-groups/{name}/scale` | PUT | Scale a node group (0-100) |
| `/api/v1/clusters/morpheus/{id}/node-groups/{name}/instance-type` | PUT | Change service plan |
| `/api/v1/clusters/morpheus/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/morpheus/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/morpheus/{id}/node-groups/{name}` | DELETE | Delete a node group |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/morpheus/{id}/nodes` | GET | List all nodes (control plane, workers, bastion) |
| `/api/v1/clusters/morpheus/{id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/morpheus/{id}/bastion/instance-type` | PUT | Resize the bastion instance type |

See [Bastion](/guides/operate-ankra-managed-clusters#bastion) for usage. Node listing and inspection are also available from the CLI (`ankra cluster morpheus nodes list|get`); bastion resize is dashboard and API only. Restarting individual nodes is not yet supported for Morpheus.

***

## Architecture

| Component | Description |
| - | - |
| **Bastion Instance** | Jump server for SSH access to the cluster nodes |
| **Control Plane(s)** | Kubernetes control plane instances |
| **Worker(s)** | Kubernetes worker instances organised in [node groups](/guides/operate-ankra-managed-clusters#node-groups) |
| **etcd Node(s)** | Dedicated etcd instances, only for kubeadm clusters with an `external` [etcd topology](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) |
| **SSH Keys** | Deployed to all instances for access |

```mermaid theme={null}
flowchart TB
    Platform[Ankra Platform]
    Morpheus[Morpheus appliance API]
    Jumphost[Optional SSH jumphost<br/>hybrid connectivity]
    Router[Your network's router<br/>DHCP gateway]
    Internet((Internet))

    subgraph MorpheusNetwork [Existing Morpheus network - DHCP]
        Bastion[Bastion instance]
        CP[Control plane instances]
        Workers[Worker instances]
        Agent[Ankra Agent<br/>runs in the cluster]
    end

    Platform -->|provision instances| Morpheus
    Platform -->|SSH| Jumphost
    Jumphost -->|SSH| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    Agent -->|outbound only - NATS| Platform
    CP -->|default route| Router
    Workers -->|default route| Router
    Router --> Internet
```

All instances are provisioned through your Morpheus appliance into the group, cloud and network you selected, booting from the chosen image with DHCP addressing. Ankra creates no network infrastructure. When an SSH jumphost is configured, Ankra reaches both the Morpheus API and the bastion through it; without one, Ankra connects to the bastion directly.

Morpheus clusters include no cloud controller manager or load balancer integration, and `external_cloud_provider` is not supported.


# OVH Reference
Source: https://docs.ankra.ai/reference/ovh

Configuration options, regions, instance flavors, and API endpoints for Ankra-managed OVH clusters.

Reference material for [OVH clusters](/guides/ovh-clusters).

***

## Cluster Configuration Options

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name |
| `credential_id` | *required* | OVH API credential ID |
| `ssh_key_credential_id` | *required* | SSH key credential ID |
| `region` | *required* | OVH Cloud region |
| `network_vlan_id` | `0` | VLAN ID for the private network |
| `subnet_cidr` | `10.0.1.0/24` | Subnet CIDR range |
| `dhcp_start` | `10.0.1.100` | DHCP allocation range start |
| `dhcp_end` | `10.0.1.200` | DHCP allocation range end |
| `gateway_flavor_id` | `c3-4` | Instance flavor for the SSH bastion (the field name predates the bastion rename) |
| `control_plane_count` | `1` | Number of control plane nodes |
| `control_plane_flavor_id` | `b3-16` | Instance flavor for control planes |
| `worker_count` | `1` | Number of worker nodes (legacy, use `node_groups` instead) |
| `worker_flavor_id` | `b3-16` | Instance flavor for workers (legacy, use `node_groups` instead) |
| `node_groups` | | Array of node group definitions (see [Node groups](/guides/operate-ankra-managed-clusters#node-groups)) |
| `distribution` | `kubeadm` | Kubernetes distribution (`kubeadm` or `k3s`) |
| `kubernetes_version` | *latest* | Kubernetes version (optional) |

### OVH Cloud Regions

| Region | Location |
| - | - |
| `GRA7` | Gravelines, France |
| `GRA9` | Gravelines, France |
| `GRA11` | Gravelines, France |
| `SBG5` | Strasbourg, France |
| `BHS5` | Beauharnois, Canada |
| `WAW1` | Warsaw, Poland |
| `DE1` | Frankfurt, Germany |
| `UK1` | London, United Kingdom |
| `SGP1` | Singapore |
| `SYD1` | Sydney, Australia |

> [!NOTE]
>
> The regions enabled on each OVH project differ. A region that is not enabled on the project's private network fails the reconcile during network setup. List the regions a credential can actually deploy in with `ankra cluster ovh regions --credential-id <credential_id>` before creating a cluster.

### OVH Instance Flavors

| Flavor | vCPUs | RAM | Description |
| - | - | - | - |
| `b2-7` | 2 | 7 GB | Suitable for the bastion |
| `b2-15` | 4 | 15 GB | General purpose, good for control planes and workers |
| `b2-30` | 8 | 30 GB | Higher performance workloads |
| `b2-60` | 16 | 60 GB | Memory-intensive workloads |

> [!NOTE]
>
> Available flavors vary by region. Check the [OVH Cloud catalog](https://www.ovhcloud.com/en/public-cloud/prices/) for your region's offerings.

***

## Node Group API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/ovh/{id}/node-groups` | GET | List all node groups |
| `/api/v1/clusters/ovh/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/ovh/{id}/node-groups/{name}/scale` | PUT | Scale a node group (0 to 100) |
| `/api/v1/clusters/ovh/{id}/node-groups/{name}/instance-type` | PUT | Change instance flavor |
| `/api/v1/clusters/ovh/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/ovh/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/ovh/{id}/node-groups/{name}` | DELETE | Delete a node group |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/ovh/{id}/nodes` | GET | List all nodes (control plane, workers, bastion/gateway) |
| `/api/v1/clusters/ovh/{id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/ovh/{id}/nodes/{node_id}/restart` | POST | Restart a node (native reboot, falls back to power cycle) |
| `/api/v1/clusters/ovh/{id}/bastion/instance-type` | PUT | Resize the bastion/gateway instance flavor |

See [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [Bastion](/guides/operate-ankra-managed-clusters#bastion) for how to use them.

***

## Architecture

```mermaid theme={null}
flowchart TB
    Internet((Internet))
    Platform[Ankra Platform]

    subgraph Network [OVH private network - vRack VLAN]
        Bastion[Bastion<br/>public + private IP]
        CP[Control plane nodes<br/>private IP only]
        Workers[Worker nodes<br/>private IP only]
        Agent[Ankra Agent<br/>runs in the cluster]
    end

    MGW[OVH managed network gateway<br/>default route + NAT]

    Platform -->|SSH to public IP| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    Agent -->|outbound only - NATS| Platform
    CP -->|egress| MGW
    Workers -->|egress| MGW
    MGW --> Internet
```

The managed network gateway (`<cluster>-network-gw`) is the nodes' router and NAT; the bastion (`<cluster>-bastion`, or `<cluster>-gateway` on clusters created before the rename) is an SSH jump host only. See [What Ankra created in your project](/guides/ovh-clusters#what-ankra-created-in-your-project).


# Portal Links
Source: https://docs.ankra.ai/reference/portal-links

Build a link to a cluster, stack, manifest, add-on, operation or pipeline run in the Ankra portal from the IDs and names the CLI, API and MCP tools return.

The CLI, the REST API and the MCP tools identify a resource by its ID and name, and do not return a portal link with it. Every portal page for those resources has a URL you can build from those values, so a script or an AI assistant can hand a teammate a link to exactly what it found.

Links on this page use `https://platform.ankra.app`. If you sign in to Ankra at a different address, use that one instead. Opening a link needs a signed-in session in the organisation that owns the resource.

***

## Clusters

Every cluster lives under the same path, however it was created:

```text theme={null}
https://platform.ankra.app/organisation/clusters/cluster/imported/<cluster-id>/overview
```

The `imported` segment is a historical name, not a cluster type. A cluster Ankra provisioned on UpCloud, Hetzner, OVH, DigitalOcean, AWS or any other provider uses the same path as a cluster you imported. There is no page at `.../imported/<cluster-id>` on its own: `overview` is the cluster's landing page.

`<cluster-id>` is the cluster's `id`, as returned by `ankra cluster list -o json` and the MCP `get_cluster_details` tool.

Other cluster pages replace `overview` with:

| Page | Path after `<cluster-id>` |
| - | - |
| Overview | `/overview` |
| Stacks | `/stacks` |
| Add-ons | `/add-ons` |
| Operations | `/operations` |
| Security | `/security` |
| Settings | `/settings/general` |

***

## Stacks, manifests and add-ons in a stack

A deployed stack opens in the stack editor:

```text theme={null}
https://platform.ankra.app/organisation/clusters/cluster/imported/<cluster-id>/stacks/<stack-name>/edit
```

To open one manifest or add-on inside the stack, add the `activeTab` and `activeSubTab` query parameters:

```text theme={null}
.../stacks/<stack-name>/edit?activeTab=manifest:<manifest-name>&activeSubTab=configuration
.../stacks/<stack-name>/edit?activeTab=addon:<addon-name>&activeSubTab=configuration
```

`<stack-name>`, `<manifest-name>` and `<addon-name>` are the names `ankra cluster stacks list` and the MCP `list_stacks` and `get_stack_details` tools return. URL-encode a name that contains anything other than letters, digits, `-`, `_` and `.`. The `:` after `manifest` or `addon` can be written as `%3A`.

A link copied from the browser also carries `clusterId` and `stackName` query parameters. They repeat values that are already in the path, so you can leave them out.

These links need a deployed stack. A stack that exists only as a draft has no page under its name; open it from the cluster's **Stacks** list instead.

### An add-on's own page

Each add-on on a cluster also has an overview page outside the stack editor:

```text theme={null}
https://platform.ankra.app/organisation/clusters/cluster/imported/<cluster-id>/add-ons/add-on/<addon-name>
```

`<addon-name>` is the name `ankra cluster addons list` shows.

***

## Operations

An operation (an execution) on a cluster opens at:

```text theme={null}
https://platform.ankra.app/organisation/clusters/cluster/imported/<cluster-id>/operations/<execution-id>/kanban
```

Take both values from `ankra cluster operations list -o json`: `<execution-id>` is the execution's `id` and `<cluster-id>` is its `cluster_id`. There is no page at `.../operations/<execution-id>` without `/kanban`.

An execution whose `scope` is `platform` also has an organisation-level page, which is the only one available when it has no `cluster_id`:

```text theme={null}
https://platform.ankra.app/organisation/operations/<execution-id>
```

That page opens platform executions only. A `cluster` execution is not found there, so use the cluster link above for it.

***

## Pipeline runs

A pipeline run opens at:

```text theme={null}
https://platform.ankra.app/organisation/pipelines/<repository-id>/runs/<pipeline-run-id>
```

Take both values from `ankra pipeline get <run> -o json`: `<repository-id>` is `repository_id` and `<pipeline-run-id>` is `id`. Do not use the run's `run_id` field, which identifies a different record. The **Open this run in Ankra** link in a pull request's pipeline status comment points at the same page.


# Proxmox VE Reference
Source: https://docs.ankra.ai/reference/proxmox

Configuration options, instance sizes, and API endpoints for Ankra-managed Proxmox VE clusters.

Reference material for [Proxmox VE clusters](/guides/proxmox-clusters).

***

## Cluster Configuration Options

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name |
| `credential_id` | *required* | Proxmox VE API credential ID |
| `ssh_key_credential_id` | *required* | SSH key credential ID |
| `node` | *required* | Proxmox node that hosts the cluster VMs (and the bastion in host-spread mode) |
| `placement_nodes` | | Two or more Proxmox nodes to spread the Kubernetes VMs across. Requires same-named storage, bridge, and template on every host, plus at least 3 control planes. See [Host-Spread Placement](/guides/proxmox-clusters#host-spread-placement) |
| `bridge` | *required* | Network the VMs attach to: the `ankra` private SDN network (created during credential setup) or a DHCP-served Linux bridge. Credential setup creates `vmbr0` when no bridge exists |
| `storage` | *auto-picked* | Active Proxmox storage for VM disks. Prefers `local-lvm`, then `local` |
| `template` | *auto-picked* | Cloud-init template to clone, by VMID or name |
| `bastion_instance_type` | `px-small` | Instance size for the bastion VM |
| `control_plane_count` | `1` | Number of control plane nodes (1, 3, or 5; at least 3 with `placement_nodes`) |
| `control_plane_instance_type` | `px-medium` | Instance size for control planes |
| `worker_count` | `1` | Number of worker nodes (legacy, use `node_groups` instead) |
| `worker_instance_type` | `px-medium` | Instance size for workers (legacy, use `node_groups` instead) |
| `node_groups` | | Array of node group definitions |
| `distribution` | `kubeadm` | Kubernetes distribution (`kubeadm` or `k3s`) |
| `kubernetes_version` | *latest stable* | Kubernetes version (optional) |
| `cni` | `cilium` (kubeadm), `flannel` (k3s) | CNI plugin (`flannel`, `calico` or `cilium`). Follows the distribution when omitted; kubeadm clusters always use `cilium` |
| `etcd_topology` | `stacked` | kubeadm only. `stacked` or `external` (dedicated etcd VMs) |
| `etcd_node_count` | `3` | kubeadm `external` topology only (3 or 5) |
| `etcd_instance_type` | `px-medium` | kubeadm `external` topology only. Instance size for etcd nodes |

### Instance Sizes

| Size | vCPUs | RAM | Disk | Typical use |
| - | - | - | - | - |
| `px-small` | 2 | 4 GB | 40 GB | Bastion |
| `px-medium` | 4 | 8 GB | 80 GB | Control plane, general workers |
| `px-large` | 8 | 16 GB | 160 GB | Larger workloads |
| `px-xlarge` | 16 | 32 GB | 320 GB | Heavy workloads |

> [!NOTE]
>
> Proxmox VE has no list pricing, so Ankra does not show cost estimates for Proxmox clusters.

***

## Node Group API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/proxmox/{id}/node-groups` | GET | List all node groups |
| `/api/v1/clusters/proxmox/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/proxmox/{id}/node-groups/{name}/scale` | PUT | Scale a node group (0-100) |
| `/api/v1/clusters/proxmox/{id}/node-groups/{name}/instance-type` | PUT | Change instance size |
| `/api/v1/clusters/proxmox/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/proxmox/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/proxmox/{id}/node-groups/{name}` | DELETE | Delete a node group |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/proxmox/{id}/nodes` | GET | List all nodes (control plane, workers, bastion) |
| `/api/v1/clusters/proxmox/{id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/proxmox/{id}/nodes/{node_id}/restart` | POST | Restart a node (native reboot, falls back to power cycle) |
| `/api/v1/clusters/proxmox/{id}/bastion/instance-type` | PUT | Resize the bastion instance type |

See [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [Bastion](/guides/operate-ankra-managed-clusters#bastion) for usage. Node listing, inspection, and restart are also available from the CLI (`ankra cluster proxmox nodes list|get|restart`); bastion resize is dashboard and API only.

***

## Architecture

| Component | Description |
| - | - |
| **Bastion VM** | Jump server for SSH access to the cluster nodes |
| **Control Plane(s)** | Kubernetes control plane VMs |
| **Worker(s)** | Kubernetes worker VMs organised in [node groups](/guides/operate-ankra-managed-clusters#node-groups) |
| **etcd Node(s)** | Dedicated etcd VMs, only for kubeadm clusters with an `external` [etcd topology](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time) |
| **SSH Keys** | Deployed to all VMs for access |

```mermaid theme={null}
flowchart TB
    Platform[Ankra Platform]
    Jumphost[Optional SSH jumphost<br/>hybrid connectivity]
    Internet((Internet))

    subgraph Host [Proxmox host]
        vmbr0[vmbr0 - management bridge<br/>public / provider IP]
        ankra[ankra - private SDN network<br/>10.20.0.0/16 · SNAT + DHCP]
        subgraph Private [Cluster VMs on ankra]
            Bastion[Bastion VM]
            CP[Control plane VMs]
            Workers[Worker VMs]
            Agent[Ankra Agent<br/>runs in the cluster]
        end
    end

    Platform -->|SSH| Jumphost
    Jumphost -->|SSH| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    Agent -->|outbound only - NATS| Platform
    ankra -->|SNAT| vmbr0
    vmbr0 --> Internet
```

All VMs are QEMU virtual machines on the Proxmox node (or nodes, with host spread) you selected, attached to the selected network. On `ankra` they receive DHCP addresses from the zone's dnsmasq instance and reach the internet through the host's public interface via SNAT. When an SSH jumphost is configured, Ankra reaches both the Proxmox API and the bastion through it; without one, Ankra connects to the bastion directly.

Proxmox VE clusters include no cloud controller manager or load balancer integration, and `external_cloud_provider` is not supported.


# API Tokens
Source: https://docs.ankra.ai/reference/tokens

Securely automate and integrate with the Ankra platform using API tokens for CLI, CI/CD, and custom integrations.

API tokens are secure credentials that allow you to authenticate and interact with the Ankra platform programmatically. They are used for CLI operations, CI/CD automation, and integrating Ankra with your own tools or scripts.

***

## How to Generate an API Token

1. **Click your profile icon** in the bottom left corner of the Ankra dashboard.
2. In the menu, select **Profile**.
3. On your profile page, choose **API Tokens**.
4. Click **Create** on the token list page.
5. Give your token a descriptive name and, if an MCP client will use it, choose its MCP access.
6. **Copy the generated token and store it securely.** You will not be able to view it again!

> [!TIP]
>
> For security, create separate tokens for different use cases (e.g., CLI, CI/CD, integrations). A personal token acts as you; for automation that runs without a person behind it, create a [service token](/guides/service-tokens) with the narrowest role that does the job.

***

## Creating a token from the CLI

`ankra tokens` manages the same tokens as the profile page, which is what you want in a script or a fresh CI runner.

```bash theme={null}
# A REST token for the CLI, the API and CI
ankra tokens create ci-deploy

# A token an MCP client may use, read-only or read-write
ankra tokens create cursor --scopes mcp:read
ankra tokens create cursor --scopes mcp:read,mcp:write

# List, then retire one
ankra tokens list
ankra tokens revoke <token-id>
ankra tokens delete <token-id>
```

```bash theme={null}
# A token pinned to one project, by name, slug or id
ankra tokens create payments-ci --project payments
```

The secret is printed once, at creation. `-o json` writes the whole answer - id, token, type, expiry - for a script to capture:

```bash theme={null}
ankra tokens create ci-deploy -o json > token.json
```

> [!WARNING]
>
> Revoking and deleting are two steps, and only revoking stops the token working. `ankra tokens delete` refuses a token that is still live: revoke it first, then delete it to remove the row. A revoked token is dead immediately, whatever it is stored in.

***

## Scopes

A token created without `--scopes` is a **REST token**: it authenticates the CLI and every `/api/v1` call your role permits. `--scopes` adds access to the [MCP server](/platform/mcp-server), and is the only place scopes apply today.

| Scopes | What it can do |
| - | - |
| *(omitted)* | The REST API and the CLI, bounded by your organisation role |
| `mcp:read` | The MCP server's read-only tools |
| `mcp:read,mcp:write` | The MCP server's tools including the ones that change state |

> [!NOTE]
>
> An MCP-scoped token is **bound to the organisation it was created in** and refuses to act anywhere else: passing `--org` (or `X-Ankra-Organisation-Id`) with one is rejected rather than honoured. Create one token per organisation you want an MCP client to reach. A REST token accepts the override as usual.
>
> A token minted with a [project](/concepts/projects) is **pinned** to it as well. An MCP-scoped token created in the console is pinned to the project chosen in the create dialog, which defaults to the project you are working in, and `--project <name>` pins any token from the CLI. A pinned token acts in that project only: `X-Ankra-Project-Id` naming another project is refused, and the token stops authenticating if its project is deleted. A REST token created without `--project` follows its owner's current project and may name another project of the same organisation with `X-Ankra-Project-Id`. Tokens created before projects were released carry no pin. The token list says which project each token acts in.

A token never exceeds the role of the person who created it - [roles and scopes](/security/identity-and-access#roles-and-scopes) decide what it may do, and a token created by a viewer stays read-only however it is used.

***

## Tokens Ankra creates for you

Not every credential in the platform is one of these tokens, and the distinction matters when you are rotating something.

| Credential | Created by | Rotate it with |
| - | - | - |
| API token | You, here | `ankra tokens revoke` + `create` |
| Application registry robot | Ankra, per application | `ankra application registry robot rotate` - see [Harbor as your application registry](/guides/harbor-registry) |
| Cluster agent token | Ankra, when a cluster is created or imported | Reinstalling the agent with a new install command from the cluster's **Settings** → **General** (**Generate command**) |

Ankra-managed credentials appear in your organisation's credential lists marked as managed; they cannot be edited there, only through the resource that owns them.

***

## Use Cases for API Tokens

### 1. Ankra CLI Authentication

Set the `ANKRA_API_TOKEN` environment variable to authenticate the CLI:

```bash theme={null}
export ANKRA_API_TOKEN="<your-token>"
```

### 2. CI/CD Integration

Use API tokens in your CI/CD pipelines to automate cluster management, addon deployment, or other Ankra API operations. Store tokens as secrets in your CI/CD system (e.g., GitHub Actions, GitLab CI, Jenkins).

**Example (GitHub Actions):**

```yaml theme={null}
env:
  ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
```

### 3. Programmatic Access (Source Code)

API tokens can be used in scripts or applications written in any language that supports HTTP requests (e.g., Python, Go, Node.js, Bash).

**Python Example:**

```python theme={null}
import requests
headers = {"Authorization": "Bearer <your-token>"}
response = requests.get("https://platform.ankra.app/api/v1/clusters", headers=headers)
print(response.json())
```

**Node.js Example:**

```javascript theme={null}
const res = await fetch("https://platform.ankra.app/api/v1/clusters", {
  headers: { Authorization: "Bearer <your-token>" }
});
console.log(await res.json());
```

***

## Troubleshooting

* **Token not working?** Double-check you copied it correctly and that it has the right permissions.
* **Lost your token?** Revoke it, create a new one, then delete the old row.
* **Permission errors?** A personal token acts with its owner's role and a service token with the role it was given; an MCP client also needs the matching `mcp:` scope.

***

## More Information

* [API Reference](/api-reference/introduction) - authenticate and call every Ankra endpoint
* [Ankra CLI](/integrations/ankra-cli) - token-based login for terminal and CI use
* [Contact Support](mailto:hello@ankra.ai)


# UpCloud Reference
Source: https://docs.ankra.ai/reference/upcloud

Configuration options, datacenter zones, server plans, and API endpoints for Ankra-managed UpCloud clusters.

Reference material for [UpCloud clusters](/guides/upcloud-clusters).

***

## Cluster Configuration Options

| Parameter | Default | Description |
| - | - | - |
| `name` | *required* | Unique cluster name |
| `credential_id` | *required* | UpCloud API credential ID |
| `ssh_key_credential_id` | *required* | SSH key credential ID |
| `zone` | *required* | UpCloud datacenter zone |
| `zones` | | Zone pool for a multi-zone cluster, must include `zone` (the primary). At least 3 zones and 3 control planes; `kubeadm` only. See [Multi-zone clusters](/guides/upcloud-clusters#multi-zone-clusters) |
| `network_mode` | *derived* | `private_network` or `wireguard_mesh`; `wireguard_mesh` for a pool, and on a single zone it makes the cluster mesh-capable so zones can be added later. On a `wireguard_mesh` cluster the load balancer backends are addressed on the private network rather than the overlay, so `LoadBalancer` Services work unchanged - see [the guide](/guides/upcloud-clusters#loadbalancer-services-on-a-meshed-cluster) |
| `network_ip_range` | `10.0.0.0/24` | Private network IP range. A multi-zone pool takes one consecutive `/24` per zone from this range |
| `bastion_plan` | `STARTER-1xCPU-1GB` | Server plan for the bastion host |
| `control_plane_count` | `1` | Number of control plane nodes (1 or 3) |
| `control_plane_plan` | `PREMIUM-2xCPU-4GB` | Server plan for control planes |
| `worker_count` | `1` | Number of worker nodes (legacy, use `node_groups` instead) |
| `worker_plan` | `PREMIUM-2xCPU-4GB` | Server plan for workers (legacy, use `node_groups` instead) |
| `node_groups` | | Array of node group definitions (see [Node groups](/guides/operate-ankra-managed-clusters#node-groups)) |
| `distribution` | `kubeadm` | Kubernetes distribution (`kubeadm` or `k3s`) |
| `kubernetes_version` | *latest stable* | Kubernetes version (optional) |

### UpCloud Datacenter Zones

| Zone | Location |
| - | - |
| `fi-hel1` | Helsinki, Finland |
| `de-fra1` | Frankfurt, Germany |
| `us-chi1` | Chicago, United States |
| `nl-ams1` | Amsterdam, Netherlands |
| `uk-lon1` | London, United Kingdom |
| `sg-sin1` | Singapore |
| `au-syd1` | Sydney, Australia |
| `pl-waw1` | Warsaw, Poland |
| `fi-hel2` | Helsinki, Finland (second zone) |
| `se-sto1` | Stockholm, Sweden |
| `es-mad1` | Madrid, Spain |
| `us-nyc1` | New York, United States |
| `us-sjo1` | San Jose, United States |

### UpCloud Server Plans

| Plan | vCPUs | RAM | Monthly Cost |
| - | - | - | - |
| `1xCPU-1GB` | 1 | 1 GB | \$5.00 |
| `2xCPU-4GB` | 2 | 4 GB | \$20.00 |
| `4xCPU-8GB` | 4 | 8 GB | \$40.00 |
| `8xCPU-16GB` | 8 | 16 GB | \$80.00 |

> [!NOTE]
>
> Available plans may vary by zone. Check the [UpCloud pricing page](https://upcloud.com/pricing/) for the latest offerings.

***

## Node Group API Reference

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/upcloud/{id}/zones` | PUT | Grow a multi-zone cluster's zone pool (`{"zones": [...]}`, primary first; zones are only ever added) |
| `/api/v1/clusters/upcloud/{id}/node-groups` | GET | List all node groups |
| `/api/v1/clusters/upcloud/{id}/node-groups` | POST | Add a node group |
| `/api/v1/clusters/upcloud/{id}/node-groups/{name}/scale` | PUT | Scale a node group (0 to 100) |
| `/api/v1/clusters/upcloud/{id}/node-groups/{name}/instance-type` | PUT | Change server plan |
| `/api/v1/clusters/upcloud/{id}/node-groups/{name}/labels` | PUT | Update labels |
| `/api/v1/clusters/upcloud/{id}/node-groups/{name}/taints` | PUT | Update taints |
| `/api/v1/clusters/upcloud/{id}/node-groups/{name}` | DELETE | Delete a node group |

## Node Actions API

| Endpoint | Method | Description |
| - | - | - |
| `/api/v1/clusters/upcloud/{id}/nodes` | GET | List all nodes (control plane, workers, bastion) |
| `/api/v1/clusters/upcloud/{id}/nodes/{node_id}` | GET | Get a single node's details |
| `/api/v1/clusters/upcloud/{id}/nodes/{node_id}/restart` | POST | Restart a node (native reboot, falls back to power cycle) |
| `/api/v1/clusters/upcloud/{id}/bastion/instance-type` | PUT | Resize the bastion instance type |

See [Restart a node](/guides/operate-ankra-managed-clusters#restart-a-node) and [Bastion](/guides/operate-ankra-managed-clusters#bastion) for how to use them.

***

## Architecture

```mermaid theme={null}
flowchart TB
    Internet((Internet))
    Platform[Ankra Platform]

    subgraph Network [UpCloud private SDN network]
        Bastion[Bastion<br/>public + private IP]
        CP[Control plane nodes<br/>no public interface]
        Workers[Worker nodes<br/>no public interface]
        Agent[Ankra Agent<br/>runs in the cluster]
    end

    Router[SDN router]
    NAT[Managed NAT gateway]

    Platform -->|SSH to public IP| Bastion
    Bastion -->|SSH jump| CP
    Bastion -->|SSH jump| Workers
    Agent -->|outbound only - NATS| Platform
    CP -->|default route| Router
    Workers -->|default route| Router
    Router --> NAT
    NAT --> Internet
```

The managed NAT gateway on the router carries all node egress; the bastion is an SSH jump host only. On a multi-zone cluster each additional zone gets its own router, private network and NAT gateway, and a WireGuard mesh (`wg0`) joins every node over the account-wide utility network. See [What Ankra created in your account](/guides/upcloud-clusters#what-ankra-created-in-your-account).


# Agent Compliance Posture
Source: https://docs.ankra.ai/security/agent-compliance

What installing the cluster agent adds to your compliance scope, control by control - including a direct answer on its cluster-admin permissions.

Installing the [Ankra Agent](/concepts/cluster-agent) does not create a new compliance boundary. It creates one new privileged identity inside a boundary you already govern.

That distinction carries the whole page. A new boundary means new controls, new evidence and a new perimeter to defend - the agent introduces none of those. A new privileged identity means an entry in an inventory you already maintain, assessed by a process you already run. The agent is the second thing.

Most controls a reviewer reaches for come back out of scope or already satisfied. One comes back in scope and stays there: the agent holds a cluster-admin ServiceAccount. That is answered directly below rather than left to be discovered.

***

## Scope determination

"Out of scope" means the agent adds nothing the control governs. "Satisfied" means it is in scope and passes as evidence rather than as a gap.

| Control area | What the agent introduces | Determination |
| - | - | - |
| Network perimeter and ingress | No listener reachable from outside the cluster, no inbound firewall rule, no tunnel terminating inward. The agent dials out; nothing on Ankra's side dials in. | **Out of scope** - no new perimeter control to evidence |
| Host and OS hardening | An unprivileged container. No host namespaces, no hostPath mounts, no node agent, no kernel module, no DaemonSet on your nodes. | **Out of scope** - your host baseline is unchanged |
| Regulated data processing | Not in the data path. Does not mount application volumes, connect to your databases, or read application payloads. | **Conditional** - out of scope by design, but log streaming and `exec` can surface regulated data if your workloads emit it |
| Data residency and transfer | Kubernetes object metadata and cluster telemetry egress to the control plane. Secret values are digested before they leave. | **Conditional** - a processor transfer on SaaS, nil when self-hosted |
| Container runtime hardening | Non-root, read-only root filesystem, all capabilities dropped, no privilege escalation, `RuntimeDefault` seccomp. | **In scope, satisfied** - use it as evidence |
| Privileged access and RBAC | A ClusterRole granting all verbs on all resources in all API groups, bound cluster-wide. | **In scope** - cannot be descoped, see below |
| Change and release management | Desired state in your Git repository, applied as attributed commits. AI-proposed writes require human approval by default; opt-in autonomy covers only validated additive changes, all audit-attributed. | **In scope, satisfied** |
| Logging and audit trail | Append-only record of every administrative change, with actor, action, timestamp and source IP. | **In scope, satisfied** |
| Cryptography in transit | TLS to the platform API. NATS authenticated with per-agent credentials on an organisation-isolated account. | **In scope, satisfied** |
| Third-party risk | Ankra becomes a processor for the cluster metadata it holds. | **In scope** - a vendor assessment, not an agent property |
| Reversibility and exit | `helm uninstall` plus deleting the namespace removes the workload, ServiceAccount and ClusterRoleBinding. | **Out of scope** - no lock-in control to evidence |

***

## What crosses the boundary

Every connection is opened by the agent, from inside your cluster, outbound. There is no inbound row in this table because there is no inbound path.

| Destination | Port | Carries | Default |
| - | - | - | - |
| `platform.ankra.app` | 443/tcp | Registration and check-in, job pull, job results, cluster telemetry | Required |
| `command.platform.ankra.app` | 4222/tcp | Command channel, resource watch batches, log and `exec` streams, metrics | Required |
| Your container registry | 443/tcp | Agent image and chart pulls - can be mirrored to a registry you control | Required |
| `api.ipify.org` | 443/tcp | Public egress IP, so the cluster can appear on the fleet map | **Off** |

The egress-IP lookup is the only optional outbound call and it stays off unless you enable it. Both required destinations are stable hostnames, so confining the agent's namespace to them with a `NetworkPolicy` is straightforward - see [Hardening the Agent](/security/agent-hardening).

***

## What never leaves the cluster

* **Secret values** - before a Secret enters the sync pipeline, every `data` and `stringData` value is replaced with a short SHA-256 digest. Key names survive so the console can show key counts, and a rotated value still changes the digest so change detection works, but the plaintext never reaches the control plane and never reaches the agent's own on-disk buffer.
* **Container images and their contents** - vulnerability scanning runs in-cluster and only its reports leave: findings, plus a package inventory (names, versions, licences) on clusters where SBOM generation is turned on. No image layers or filesystem contents.
* **Values decrypted from Git** - values sealed with [SOPS](/guides/sops) are decrypted by the agent inside your cluster at deploy time, and the decrypted result is never sent back. Git holds ciphertext only. The control plane separately holds the values you entered in the Stack Builder - see [Where it lives](/security/overview#where-it-lives).
* **Application traffic and volume data** - the agent never sees request bodies, database contents, or persistent volume data.
* **Credentials in logs** - agent logs pass through a redaction handler that strips authorization headers, embedded URL credentials, provider tokens, password assignments and docker config JSON before a line is emitted.

> [!NOTE]
>
> One exception: a member can reveal one Secret's live values on demand. That is a read by a person rather than a background flow, it needs the `kubernetes.secrets_reveal` permission (held by `owner`, `admin` and `operator`), and each reveal is written to the audit log with who, which cluster and which Secret. Everyone else sees key names and digests only. The digest shown in the console and API is keyed per cluster with a key only the platform holds, so it cannot be used to check a guessed value offline. See [Roles & Access](/guides/roles-and-access#permission-matrix).

***

## Runtime posture as benchmark evidence

The pod ships hardened rather than leaving hardening to you, and every setting below is visible in the chart before you install.

| Control | As shipped | Bears on |
| - | - | - |
| Runs as non-root | `runAsNonRoot: true`, UID/GID 1000 | CIS Kubernetes 5.2.6 |
| No privilege escalation | `allowPrivilegeEscalation: false` | CIS Kubernetes 5.2.5 |
| Capabilities dropped | `capabilities.drop: [ALL]` | CIS Kubernetes 5.2.9 |
| Immutable filesystem | `readOnlyRootFilesystem: true` | NIST SP 800-190 |
| Syscall confinement | `seccompProfile: RuntimeDefault` | NIST SP 800-190 |
| No host namespaces | `hostNetwork`, `hostPID`, `hostIPC` unset | CIS Kubernetes 5.2.2 - 5.2.4 |
| No host filesystem access | Size-limited `emptyDir` volumes only | CIS Kubernetes 5.2 |
| Credential handling | Token read from a Secret reference | ISO/IEC 27001:2022 A.5.17 |

Verify any of these against a running agent with the commands in [Hardening the Agent](/security/agent-hardening#verify-the-posture).

***

## The cluster-admin question

The agent's ClusterRole grants every verb on every resource in every API group, plus all non-resource URLs, bound cluster-wide. There is no way to present that as least privilege.

**Why it is that way.** The agent installs arbitrary Helm charts and raw manifests that you choose, reconciles them, and proxies authenticated `kubectl` - including `watch`, `logs -f` and `exec` - for the whole cluster. A tool that deploys arbitrary workloads needs reach equivalent to the workloads it deploys.

**What it means for your review.** The agent belongs in your privileged-access inventory, recorded as a justified exception and reviewed on the same cadence as your other cluster-admin bindings. It will appear in a CIS 5.1.1 review. That is the correct outcome, not a finding to argue away.

### Compensating controls

* **The identity is revocable from outside the cluster.** Each cluster has its own registration token. Revoking it at the platform, or rotating the Kubernetes Secret holding it, cuts the agent off without needing cluster access. After repeated identity rejection the agent stops and the cluster is marked disconnected.
* **Per-agent, per-organisation transport credentials.** NATS credentials are issued to that agent at registration, scoped to its own command subject, on an account isolated per organisation. Session tokens rotate. There is no shared or long-lived transport secret.
* **Approval gates automated writes.** AI-proposed changes become drafts applied as attributed Git commits, each approved by a person by default. If an organisation enables chat autonomy, a conversation its user has opted into **Auto** executes low-risk, purely additive, pre-validated changes without a per-change click - every such action carries an attributed audit entry, and removals, cluster lifecycle, and anything failing validation still require a human. The AI never mutates a cluster outside this pipeline and is never shown secret values.
* **Reconciliation is bounded.** Release operations serialise on a Kubernetes Lease, and pruning runs behind anti-mass-deletion guards and sync windows, so drift correction converges toward Git rather than issuing surprise deletions.
* **Git holds desired state.** Every change is diffable, attributable and revertable by you, independently of the platform.
* **Administrative actions are append-only audited**, and exportable - see [Audit Export](/security/audit-export).

> [!WARNING]
>
> The ClusterRole cannot currently be narrowed through chart values. If your policy requires a smaller grant, the workable routes are network and admission constraints, cluster tiering, or the self-hosted deployment - all covered in [Hardening the Agent](/security/agent-hardening).

***

## Framework mapping

| Framework | Clauses engaged | How the agent bears on them |
| - | - | - |
| SOC 2 | CC6.1, CC6.6, CC6.7, CC7.2, CC8.1 | Logical access (the cluster-admin binding and its review), boundary protection (outbound only), transmission, monitoring, and change management |
| ISO/IEC 27001:2022 | A.5.15, A.5.17, A.8.2, A.8.9, A.8.15, A.8.16, A.8.24 | Privileged access rights are the live clause. Configuration management, logging, monitoring and cryptography are served by existing behaviour |
| GDPR | Art. 28, Art. 32 | On SaaS, Ankra is a processor for cluster metadata. Art. 32 measures are met by secret digesting, encryption in transit and audit logging |
| NIS2 | Art. 21 supply chain and access control | Assessed as a supplier relationship plus a privileged-access control |
| DORA | ICT risk and change management | An ICT third-party dependency, with Git-backed change management and an audit trail |
| PCI DSS v4.0 | Requirements 1, 6, 7, 8, 10 | If the cluster is in your CDE, the agent is in scope with it. Descope through segmentation, not through the agent's design |

> [!WARNING]
>
> A cluster-admin component inside a cardholder data environment cannot be descoped by asserting it does not touch cardholder data. Either keep Ankra-managed clusters outside the CDE, or assess the agent as an in-scope system component.

***

## Related

> [card] [Hardening the Agent](/security/agent-hardening)
>
> Restrict egress, ship metrics and logs, and pin optional behaviours.

> [card] [Shared Responsibility](/security/shared-responsibility)
>
> Why Ankra's footprint in your certification is narrow.

> [card] [Ankra Agent](/concepts/cluster-agent)
>
> How the agent works and what it does.

> [card] [What Ankra Can See and Do](/security/overview)
>
> What leaves your cluster, where it is stored and for how long.


# Hardening the Agent
Source: https://docs.ankra.ai/security/agent-hardening

Restrict the agent's network egress, scope its service account, ship its metrics and logs to your own stack, and turn off optional behaviours.

The [Ankra Agent](/concepts/cluster-agent) ships hardened by default - non-root, read-only root filesystem, all Linux capabilities dropped. This page covers what you can tighten beyond the defaults, and how to prove the resulting posture to an assessor.

For the scope determination behind these controls, see [Agent Compliance Posture](/security/agent-compliance).

***

## Keep the token out of Helm values

Passing `config.token` on the command line puts the credential in your shell history and in the Helm release Secret. Create the Secret yourself and reference it instead.

```bash theme={null}
kubectl create secret generic ankra-agent-secret \
  --namespace ankra \
  --from-literal=token=<your-token>

helm upgrade --install ankra-agent oci://registry.ankra.cloud/ankra/ankra-agent \
  --namespace ankra \
  --set config.existing_secret_name=ankra-agent-secret \
  --set config.secret_key=token
```

Rotating that Secret and restarting the agent is also the fastest in-cluster way to cut the agent off during an incident.

***

## Restrict network egress

The agent needs two external destinations plus in-cluster access to the Kubernetes API. Everything else can be denied.

```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: ankra-agent-egress
  namespace: ankra
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: ankra-agent
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector: { }
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53
    - to:
        - namespaceSelector: { }
      ports:
        - protocol: TCP
          port: 443
        - protocol: TCP
          port: 6443
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
      ports:
        - protocol: TCP
          port: 443
        - protocol: TCP
          port: 4222
```

> [!WARNING]
>
> Standard `NetworkPolicy` matches on CIDRs, not hostnames, so the external rule above cannot name `platform.ankra.app` directly. If your CNI supports FQDN-based egress policy - Cilium's `toFQDNs` for example - use it to pin the two hostnames exactly. Otherwise the rule limits the agent to two ports on external addresses, which is still a meaningful reduction.

Before you apply a restrictive policy, account for the in-cluster endpoints the agent reaches on your behalf. If you have connected a [Prometheus](/integrations/prometheus) or [log source](/integrations/log-sources) endpoint, or you run the [ArgoCD engine](/concepts/deployment-engines), the agent needs to reach those services too. The in-cluster rule above allows 443 and 6443 across namespaces; widen it to the specific ports and namespace selectors your integrations use, and verify the cluster still reports healthy afterwards.

***

## Turn off optional egress

The public IP lookup is the only outbound call the agent makes that is not required, and it is disabled by default. Confirm it stays that way in restricted-egress environments:

```yaml theme={null}
public_ip:
  reporting_enabled: false
```

You can also narrow what the agent watches. Dynamic API discovery extends the watch set to CRDs and operator resources beyond the curated built-in list. Pinning it off limits both the metadata that egresses and the agent's read footprint:

```yaml theme={null}
k8s_watch:
  dynamic_discovery: false
```

Secret redaction is on by default and should stay on. It replaces every Secret `data` and `stringData` value with a SHA-256 digest before it enters the sync pipeline:

```yaml theme={null}
k8s_watch:
  redact_secrets: true
```

> [!NOTE]
>
> Turning the watch pipeline off entirely (`k8s_watch.enabled: false`) stops resource browsing and live views in the platform. Prefer narrowing discovery over disabling the pipeline.

***

## Mirror the image

Pull the agent image and chart from a registry you control rather than reaching a vendor registry from every cluster. Mirror them into your own registry, then point the chart at it:

```yaml theme={null}
image:
  repository: <your-registry>/ankra/agent
  pull_secrets:
    - name: <your-pull-secret>
```

> [!WARNING]
>
> Pinning `image.tag` breaks the platform's fleet auto-upgrade, which relies on the image following the chart version. If you mirror, mirror new chart versions on a schedule so the agent does not fall behind on security fixes.

***

## The service account

The agent's ClusterRole grants all verbs on all resources in all API groups. It **cannot be narrowed through chart values today** - the rules are fixed in the chart, not templated from values. Anyone telling you to set an `rbac.rules` override is describing a knob that does not exist.

What you can do instead:

* **Constrain the agent by namespace policy rather than RBAC.** Admission policy engines such as Kyverno or Gatekeeper still apply to everything the agent creates. Its Kubernetes privilege does not exempt it from your admission controls, so policy is the effective place to draw the line.
* **Tier your clusters.** Run Ankra-managed clusters as a separate tier from your highest-sensitivity workloads, so the privilege boundary matches your data boundary. This is also the practical answer for PCI scope.
* **Alert on changes to the binding.** Watch the ClusterRole and ClusterRoleBinding for modification, so an unexpected change is a detection rather than a discovery.
* **Review it on your normal cadence.** Record the binding as a justified exception in your privileged-access register and review it alongside your other cluster-admin grants.
* **Move the control plane inside your boundary.** The self-hosted deployment keeps the privileged component on infrastructure you operate.

Inspect exactly what is granted at any time:

```bash theme={null}
kubectl get clusterrole ankra-agent-ankra -o yaml
kubectl get clusterrolebinding -l app.kubernetes.io/name=ankra-agent
```

***

## Ship the agent's metrics

The agent exposes Prometheus metrics on port 8080 at `/metrics`. If you run the Prometheus Operator, enable the bundled ServiceMonitor:

```yaml theme={null}
metrics:
  serviceMonitor:
    enabled: true
    interval: 30s
    scrapeTimeout: 10s
    labels:
      release: kube-prometheus-stack
```

The `labels` block must match your Prometheus instance's `serviceMonitorSelector`, otherwise the ServiceMonitor is created but never scraped.

Without the Prometheus Operator, scrape the Service directly at `ankra-agent.ankra.svc:8080/metrics`.

Metrics worth alerting on:

| Metric | Type | Tells you |
| - | - | - |
| `ankra_agent_watch_events_total` | Counter | Resource events observed - a flat count means the watch pipeline stalled |
| `ankra_agent_watch_publish_failures_total` | Counter | Batches that failed to reach the platform |
| `ankra_agent_watch_events_rate_limited_total` | Counter | Events dropped by the rate limiter, so the platform view may lag |
| `ankra_agent_in_flight_publish_duration_seconds` | Histogram | Publish latency to the control plane |
| `ankra_native_release_apply_duration_seconds` | Histogram | How long releases take to apply |
| `ankra_native_release_drift_detected_total` | Counter | Drift found between Git and the cluster |
| `ankra_native_release_selfheal_total` | Counter | Releases the agent repaired automatically |
| `ankra_native_release_prune_total` | Counter | Resources pruned during reconciliation |

Health endpoints for liveness and readiness probes are on the same port at `/livez` and `/readyz`.

***

## Ship the agent's logs

The agent writes structured JSON to stdout, so any Kubernetes log collector picks it up without extra configuration. Set the verbosity through chart values:

```yaml theme={null}
log_level: "INFO"
```

Accepted values are `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. Keep production at `INFO` - `DEBUG` is verbose enough to matter on a busy cluster.

Secret-bearing strings pass through a redaction handler before a line is emitted, covering authorization headers, credentials embedded in URLs, provider tokens, password assignments and docker config JSON. Do not bypass it by writing agent output through a different path.

To collect the logs with Promtail or Grafana Alloy, select the namespace:

```yaml theme={null}
scrape_configs:
  - job_name: ankra-agent
    kubernetes_sd_configs:
      - role: pod
    relabel_configs:
      - source_labels:
          - __meta_kubernetes_namespace
        regex: ankra
        action: keep
      - source_labels:
          - __meta_kubernetes_pod_label_app_kubernetes_io_name
        regex: ankra-agent
        action: keep
```

If you also want Ankra to search those logs back, connect the store as a [log source](/integrations/log-sources).

***

## Verify the posture

Prove the settings rather than asserting them. These commands produce output you can attach to an audit response.

```bash theme={null}
# Security context actually in effect
kubectl get deployment ankra-agent -n ankra \
  -o jsonpath='{.spec.template.spec.containers[0].securityContext}'

# Confirm no host namespaces are used
kubectl get deployment ankra-agent -n ankra \
  -o jsonpath='{.spec.template.spec.hostNetwork}{" "}{.spec.template.spec.hostPID}{" "}{.spec.template.spec.hostIPC}'

# Confirm only emptyDir volumes are mounted
kubectl get deployment ankra-agent -n ankra \
  -o jsonpath='{.spec.template.spec.volumes}'

# Image and version in use
kubectl get deployment ankra-agent -n ankra \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

# Effective egress policy
kubectl get networkpolicy -n ankra
```

An empty result from the host-namespace query means none are set, which is the expected and correct output.

***

## Related

> [card] [Agent Compliance Posture](/security/agent-compliance)
>
> The scope determination these controls support.

> [card] [Agent Helm Values](/reference/agent-helm-values)
>
> The complete value reference.

> [card] [Monitoring Stack](/guides/monitoring-stack)
>
> Deploy Prometheus and Loki to receive these signals.

> [card] [Compliance Management](/security/compliance-management)
>
> Turn cluster state into audit evidence.


# Audit Export
Source: https://docs.ankra.ai/security/audit-export

Export the organisation audit trail as CSV or JSON, forward it to your SIEM or evidence store, and keep records beyond the platform retention window.

The [Audit Log](/guides/audit-log) is Ankra's append-only record of every administrative change. Export takes that record out of the platform so you can retain it on your own terms, feed it to a SIEM, or attach it to an audit response.

Exporting is the mechanism that turns the audit log from a troubleshooting view into compliance evidence, because evidence has to outlive the platform's retention window and live somewhere your assessor can reach.

***

## What the export contains

Each row is one audit entry, with the same fields the audit viewer shows:

| Column | Contents |
| - | - |
| `created_at` | UTC timestamp of the action |
| `user_email` | The acting member's email address |
| `user_id` | The acting member's stable identifier |
| `actor_type` | Who acted: `human`, `agent` (an action taken by Ankra's AI) or `system` |
| `action_type` | What was done, for example a role assignment or credential change |
| `resource_type` | The kind of resource acted on |
| `resource_id` | The specific resource |
| `target_kind` | The kind of object the action named, where one can be resolved |
| `target_name` | That object's name |
| `outcome` | `succeeded`, `failed`, or `unknown` for actions that record no result marker (most non-AI changes, which are logged once already committed) |
| `ip_address` | Source IP the action came from |
| `cluster_id` | The cluster the action applied to, where the action is cluster-scoped |
| `cluster_name` | That cluster's name at export time |
| `details` | Structured detail of the change, as compact JSON |

A reveal of a Kubernetes Secret's values is one row per Secret: `action_type` `reveal`, `resource_type` `kubernetes_secret`, `resource_id` `<namespace>/<name>`, the `cluster_id`, and `details` holding the namespace, the Secret name, its key names and `surface` (`portal` for the console, `api` for an API token). The values themselves are never written. Filter on `resource_type=kubernetes_secret` to list who read which Secret.

A change Ankra classified as a pre-approved standard change carries `change_classification` in `details`: the `class` (`standard_preapproved`, or `normal` when your organisation requires approval for every change), the `standard_change_id` such as `SC-01`, the catalogue entry, the `catalogue_version` it was decided against and the `basis` it qualified on. To list the pre-approved changes in a JSON export:

```bash theme={null}
jq '[.entries[] | select(.details.change_classification.class == "standard_preapproved")
         | {created_at, cluster_name, action_type, id: .details.change_classification.standard_change_id,
            basis: .details.change_classification.basis}]' audit-export.json
```

See [Change Management](/security/change-management) for the catalogue.

In CSV the `details` column holds a JSON document, so keep the file quoted and parse it with a real CSV reader rather than splitting on commas - the details routinely contain commas and newlines.

Cell values that would otherwise be interpreted as formulas by a spreadsheet application are neutralised before they are written, so opening an export in a spreadsheet does not execute anything an actor put in a resource name.

***

## Permissions

Export is gated by the same `audit.read` permission as the audit viewer, held by **owners** and **admins** by default and available to [custom roles](/guides/roles-and-access). A caller without it receives a `403` naming the missing permission.

Granting `audit.read` to a compliance or security function lets them pull evidence themselves without broader administrative access, which is usually what you want.

An API token calling the export needs the same permission: the role behind the token (the service account's role, or the owner's role for a personal token) must hold `audit.read`, and a token restricted to a list of scopes must include it.

***

## Exporting from the portal

**1. Open the audit log**

Go to **Organisation** → **Audit log**.

**2. Filter to the evidence you need**

Narrow by user, action type, resource type and date range. The export follows the filters currently applied, so filter first.

**3. Export**

Choose the CSV or JSON export action. The file downloads with the organisation and date in its name, for example `audit-log-<organisation-id>-2026-08-13.csv`.

***

## Exporting for automation

Scripts, scheduled jobs and SIEM collectors call the token route of the same export:

```
GET https://platform.ankra.app/api/v1/org/organisation/audit-logs/export
```

It accepts a [service token](/guides/service-tokens) or a personal API token as a bearer credential, and takes the same filters, formats and row cap as the portal download. The export is scoped to the token's organisation.

| Query parameter | Meaning |
| - | - |
| `format` | `csv` (default) or `json` |
| `start_date`, `end_date` | Window bounds, both inclusive. A date (`2026-07-01`) or an RFC 3339 timestamp (`2026-07-31T23:59:59Z`) |
| `action_type`, `resource_type` | Narrow to one kind of action or resource |
| `user_id`, `cluster_id`, `agent_task_id` | Narrow to one member, one cluster, or one AI task |
| `actor_type` | `human`, `agent` or `system` |
| `outcome` | `succeeded` or `failed` |
| `search` | Free-text match, as in the audit viewer |

```bash theme={null}
curl -fsS \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -D headers.txt \
  "https://platform.ankra.app/api/v1/org/organisation/audit-logs/export?format=csv&start_date=2026-07-01&end_date=2026-07-31T23:59:59Z" \
  -o audit-log-2026-07.csv

grep -qi '^x-ankra-export-truncated: true' headers.txt && echo "export truncated - narrow the window" >&2
```

`-f` makes `curl` fail on a `401` or `403` instead of writing the error body to the file. A token without `audit.read` receives a `403` naming the missing permission.

> [!WARNING]
>
> Use the `/api/v1/...` path above. The portal's own route, `/org/organisation/audit-logs/export`, accepts a signed-in browser session only: a request carrying a bearer token is redirected to the sign-in page rather than refused, which looks like success unless you check the file.

***

## Row cap and truncation

A single export returns at most **100,000 rows**. When more rows match your filters, the export is truncated to the newest ones and says so:

* **CSV** responses set the `X-Ankra-Export-Truncated: true` response header.
* **JSON** responses carry a `truncated` member in the document.

> [!WARNING]
>
> Truncation is silent if you only look at the file. A monthly export of a busy organisation can exceed the cap without any visible sign in the CSV itself. Always check the header or the JSON member, and narrow the date window until the export comes back complete.

When the export is truncated, narrow the date window and export again until it comes back complete.

***

## Retention, and why you export

Audit entries are retained for **365 days** by default, after which older rows are removed by a background retention job.

If your framework requires a longer trail - and most do, with ISO/IEC 27001 and many SOC 2 programmes expecting multi-year retention - the platform is not your system of record. Export regularly into storage you control, with the retention and immutability your policy requires: for example a scheduled daily [token export](#exporting-for-automation) into write-once object storage.

***

## Forwarding to a SIEM

There is no push integration: your SIEM pulls. Run a scheduled job that exports a bounded window with a service token and hands the file to your SIEM's ingestion, and keep the raw file in your evidence store as well - the SIEM is for detection, the file is for the assessor.

**1. Create a role that can only read the audit log**

In **Organisation** → **Roles**, create a [custom role](/guides/roles-and-access) holding `audit.read` and nothing else.

**2. Mint a service token with that role**

Create a [service token](/guides/service-tokens) named after the job, for example `siem-audit-export`, with the role from the previous step, and store it in your scheduler's secret store.

**3. Schedule the export**

Pull one closed window per run - yesterday, in UTC - so every row arrives exactly once. Both window bounds are inclusive, so end the window one microsecond before midnight rather than at midnight.

A daily GitHub Actions job, as an example. It uses GNU `date`, as on GitHub-hosted Linux runners; the last step is a placeholder for your SIEM's ingestion:

```yaml theme={null}
name: audit-log-to-siem
on:
  schedule:
    - cron: "15 1 * * *"
  workflow_dispatch: {}

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - name: Export yesterday's audit log
        env:
          ANKRA_API_TOKEN: ${{ secrets.ANKRA_AUDIT_EXPORT_TOKEN }}
        run: |
          day="$(date -u -d yesterday +%Y-%m-%d)"
          curl -fsS \
            -H "Authorization: Bearer $ANKRA_API_TOKEN" \
            "https://platform.ankra.app/api/v1/org/organisation/audit-logs/export?format=json&start_date=${day}T00:00:00Z&end_date=${day}T23:59:59.999999Z" \
            -o "audit-log-${day}.json"
          if jq -e '.truncated' "audit-log-${day}.json" >/dev/null; then
            echo "Export for ${day} hit the 100,000-row cap; split the window" >&2
            exit 1
          fi
          echo "day=${day}" >> "$GITHUB_ENV"

      - name: Forward to the SIEM
        run: |
          # Replace with your SIEM's ingestion, for example an HTTP collector
          # or an upload to the bucket your SIEM reads from.
          jq -c '.entries[]' "audit-log-${day}.json" > "audit-log-${day}.ndjson"
```

The JSON document is `{"entries": [...], "truncated": false}`, newest entry first, with the columns listed [above](#what-the-export-contains) as fields of each entry. Failing the job on `truncated` matters: a truncated window silently drops its oldest rows.

***

## What the audit log does not cover

Being clear about the boundary saves you from over-claiming in an audit response.

* **Individual Kubernetes API calls are not in the audit log.** Ankra records who was given Kubernetes access (grant changes, kubeconfig generation, token minting), every pod terminal session, with a transcript, and every reveal of a Secret's values through the console or the API. Individual calls made against your cluster's API server - by any tool, including `kubectl` through Ankra's proxy - are recorded by your cluster's own Kubernetes audit policy. Enable Kubernetes audit logging separately if you need that trail.
* **Desired-state changes live in Git.** What changed in a cluster definition, and who committed it, is in your repository's history as attributed commits. The audit log records the platform action, and Git records the content of the change. See [GitOps](/concepts/gitops).
* **Data-plane activity is not recorded.** Ankra is not in your application's request path and has no view of it.

Together the audit export, your Git history and your Kubernetes audit log cover platform actions, configuration changes and cluster API activity respectively. An assessor asking "who changed this cluster" is usually satisfied by the first two.

***

## Related

> [card] [Audit Log](/guides/audit-log)
>
> Read and filter the trail in the platform.

> [card] [Change Management](/security/change-management)
>
> Which entries are pre-approved standard changes, and why.

> [card] [Compliance Management](/security/compliance-management)
>
> The organisation compliance report and benchmark results.

> [card] [Roles & Access](/guides/roles-and-access)
>
> Grant `audit.read` to a compliance function.

> [card] [Shared Responsibility](/security/shared-responsibility)
>
> Where this evidence fits in your certification.


# Change Management
Source: https://docs.ankra.ai/security/change-management

How Ankra classifies the changes it makes to your clusters as pre-approved standard changes or normal changes, and how that record supports ISO 27001 change management.

ISO/IEC 27001:2022 control 8.32 asks that changes to information processing facilities follow a change management process. Most organisations meet it with three kinds of change: **standard changes** that are pre-approved because they are low-risk and repeatable, **normal changes** that are approved one at a time, and **emergency changes**.

Ankra records which kind each change is. When a change it makes to a cluster matches an entry in the standard-change catalogue below, the [Audit Log](/guides/audit-log) entry is marked as a pre-approved standard change, with the catalogue entry and the reason it qualified. Every other change is a normal change, approved through your own process: a reviewed pull request on your GitOps repository, an approved AI plan, or a change ticket.

Pre-approval is on for every organisation by default.

***

## The standard-change catalogue

Each entry states what qualifies and how the change is reversed. A change that does not meet every part of the criteria is a normal change.

| ID | Standard change | Qualifies when |
| - | - | - |
| SC-01 | Add-on security patch | One add-on's chart version moves forward, within the same major version, to a version that fixes at least one published security advisory (GHSA, CVE or OSV) Ankra has recorded against the installed version. Nothing else in the Stack changes. |
| SC-02 | Kubernetes patch upgrade | The cluster's Kubernetes version moves forward by a patch release within the same minor version. |
| SC-03 | Operating system patching | Security updates are applied to nodes inside the cluster's patch window. |
| SC-04 | Ankra agent upgrade | The Ankra agent moves to a released version under your organisation's auto-upgrade setting. |
| SC-05 | Autoscaling within configured bounds | The cluster autoscaler adds or removes nodes inside the minimum and maximum set for the node group. |
| SC-06 | Reconcile to the committed state | Ankra returns the cluster to the state already committed in its GitOps repository. |
| SC-07 | Certificate, DNS and credential rotation | A certificate renews, a DNS record is reconciled to its declared value, or a credential is rotated without changing what it grants. |
| SC-08 | Scheduled backup | A backup or snapshot runs on its schedule, or is taken on request, without changing the protected workload. |
| SC-09 | Scheduled power action | A cluster stops or starts as its power schedule or cost policy says. |
| SC-10 | Access revocation and self-heal | Expired access is removed, or Ankra restarts a control-plane node that stopped responding, within the attempt limit. |
| SC-11 | Non-production deploy on merge | An image built and scanned by the pipeline is deployed to a non-production environment after its pull request merged. A deploy to production, or to an installation with no environment set, is a normal change. |
| SC-12 | Ephemeral preview environment | A pull-request preview is created on your staging cluster and removed when the pull request closes. |

Every change on this list writes an audit entry, including the ones Ankra makes on its own: those are recorded with the actor `system` and say what started them.

***

## Security upgrades carry their reason

When you upgrade an add-on from a **Security update available** notice, Ankra looks up the advisories the new version fixes from its own advisory records. It does not rely on what the browser or CLI sent. The audit entry then names them, and so does the commit in your GitOps repository:

```text theme={null}
Security upgrade kyverno 3.8.2 -> 3.9.1 in stack 'ankra-security-baseline'

Fixes-Advisory: GHSA-xxxx-xxxx-xxxx (CVE-2026-xxxxx)
```

The repository history alone then answers why the change was made. An upgrade that fixes no recorded advisory, or that moves to a new major version, is recorded as a normal change.

***

## Reading the audit trail

In a cluster's **Settings > Audit**, an entry that qualified shows **Pre-approved SC-01** (or the matching ID) beside its action. Hover over it to see the catalogue entry and why the change qualified, for example the versions and advisories of a security patch. The full record is in the entry's details under `change_classification`:

```json theme={null}
"change_classification": {
  "class": "standard_preapproved",
  "standard_change_id": "SC-01",
  "standard_change": "Add-on security patch",
  "catalogue_version": "2026-10-17",
  "basis": "kyverno 3.8.2 -> 3.9.1 fixes GHSA-xxxx-xxxx-xxxx (CVE-2026-xxxxx)."
}
```

The classification is decided when the entry is written, and `catalogue_version` names the catalogue it was decided against. A later change to the catalogue does not rewrite earlier entries. Entries without a classification are normal changes, or events that are not changes at all, such as sign-ins.

[Export the audit log](/security/audit-export) to hand the record to an auditor.

***

## Requiring approval for every change

If your change process does not allow pre-approved changes, an organisation admin can turn off **Organisation settings > Security > Pre-approved standard changes**. From then on, changes that match the catalogue are recorded as normal changes. Each entry still names the catalogue entry it matched, and its basis says your organisation requires approval. Turning the setting off or on is itself recorded in the audit log.

Turning pre-approval off does not stop Ankra from making these changes. Autoscaling, power schedules and access expiry keep running as configured. If a change needs approval before it happens, make it through a reviewed pull request on your GitOps repository, or turn off the automation that makes it.


# Compliance Management
Source: https://docs.ankra.ai/security/compliance-management

Ankra's built-in compliance layer - continuous control monitoring, governed exceptions, and the evidence export that backs them in an audit.

Ankra has a compliance management layer built into the platform. It continuously measures your clusters against recognised benchmarks, governs the exceptions you grant against them, and exports the result as evidence.

That combination is what an information security management system needs from a technical control: not a one-off scan, but a control that is monitored on a cadence, exceptions that carry an owner and an expiry, and a record that survives the audit.

This page covers the compliance layer as a management system. The interface mechanics live in [Cluster Security](/guides/cluster-security).

***

## Continuous control monitoring

The **Compliance** view scores every managed cluster against four benchmark specifications and lays them out as a matrix, so you can read one cluster down or one framework across.

| Framework | What it checks |
| - | - |
| CIS Kubernetes Benchmark | Control plane, kubelet, etcd and workload configuration against the CIS baseline, on a cluster that turned on the security baseline's CIS inputs (off by default, see [Security baseline](/guides/cluster-security#security-baseline)) |
| NSA/CISA Kubernetes Hardening Guidance | The NSA and CISA hardening recommendations, on a cluster that turned on the same inputs |
| Pod Security Standards - Baseline | Pod-level posture against the PSS baseline profile |
| Pod Security Standards - Restricted | Pod-level posture against the stricter PSS restricted profile |

Each cell carries pass and fail counts and a pass rate, graded into three tiers:

| Tier | Meaning |
| - | - |
| **Compliant** | No failed checks |
| **Attention** | Failures present, but the pass rate is 85% or above |
| **Poor** | Pass rate below 85% |

Configuration-audit findings are rolled up alongside the benchmarks, and a fleet scorecard summarises coverage and the failing-check count across the estate.

> [!NOTE]
>
> A cluster without the scanner installed is reported explicitly as **not reporting**, with the reason, rather than being counted as passing. That distinction is deliberate: to an assessor an unscanned cluster is a coverage gap, and a system that quietly scored it as clean would be worse than useless.

Scanning runs inside your cluster through [Trivy Operator](/guides/cluster-security) and only findings metadata reaches the platform. Ankra is the aggregation, grading and retention layer, not the scanner.

***

## Governed exceptions

Every real control set has exceptions. What separates a managed exception from an unmanaged one is that somebody owns it, justified it, and agreed to look at it again. Ankra enforces that shape rather than leaving it to convention.

Findings carry two distinct dispositions:

| Disposition | Effect |
| - | - |
| **Acknowledged** | Reviewed, but still actionable and still alerts |
| **Accepted risk** | Excluded from actionable totals and alerts, still visible in observed totals |

Accepting risk requires a reason, an actor recorded in the audit trail, and a **review deadline of at most one year**. You can also have the acceptance expire automatically the moment a fix becomes available, so an exception granted because nothing could be done ends as soon as something can.

This is the behaviour a risk register is supposed to have. The register cannot silently accumulate permanent exceptions, because the platform will not accept one without an expiry.

***

## Policy lifecycle

Accepted risks become organisation-wide policies with a lifecycle you can review, rather than one-off suppressions that are impossible to audit later.

Policies are tracked as **active**, **expiring**, **fix-available**, **mitigated**, **unmatched**, **expired** or **revoked**, and the Security overview surfaces those nearing review so the next review is prompted rather than remembered. Matching is deterministic - organisation, add-on, CVE, package type and package name - and creating a policy always shows a server-side preview of exactly which findings it will affect before you commit.

Policies are never hard-deleted. They are revoked, they expire, they mitigate when no matches remain, or they reopen if the findings return. That means the history of what was excluded, and when, stays intact.

The register is reachable without the browser: `ankra security dispositions` lists the policies by lifecycle state, `ankra security dispositions preview` and `create` write a decision after showing the server-side match preview, and `update` / `revoke` carry the lifecycle - every one against the token API, so an auditor's script and an engineer's terminal see the same record the portal does. From chat or the MCP server the tools are `list_security_dispositions`, `preview_security_disposition`, `create_security_disposition`, `update_security_disposition` and `revoke_security_disposition`; the writes are confirmed before they run and enforce the same three permissions.

> [!WARNING]
>
> Expiry or a newly available fix can make findings actionable again and may fire threshold alerts. This is the control working as intended, but plan for it: a batch of acceptances expiring in the same week produces a spike in actionable findings.

***

## Segregation of duties

Three permissions separate looking from triaging from accepting risk, so the person who grants an exception need not be the person who investigates one.

| Permission | Grants |
| - | - |
| `security.read` | View compliance, findings and posture |
| `security.triage` | Acknowledge findings |
| `security.manage` | Accept risk, and create, edit or revoke policies |

All three can be attached to [custom roles](/guides/roles-and-access). Enforcement is server-side, and every disposition change is written to the append-only audit trail in the same transaction as the change itself, so the record cannot drift from the action.

***

## The compliance report

The report is the export that carries the state above out of the platform in one document. Generate it from **Organisation** → **Security**, or pull it on a schedule:

```bash theme={null}
curl -sS \
  -H "Authorization: Bearer <your-token>" \
  "https://platform.ankra.app/api/v1/org/security/compliance-report?format=json&start_date=2026-07-01&end_date=2026-07-31" \
  -o compliance-report-july.json
```

Both `json` (default) and `csv` are supported, and the date range bounds the audit-activity section. The same download is `ankra security compliance export --format json --start-date 2026-07-01 --end-date 2026-07-31 --output-file compliance-report-july.json` from the terminal; the framework switches and reports behind it are `ankra security compliance frameworks`, `frameworks enable|disable <key>` and `frameworks report <key> --month 2026-07`.

| Section | What it proves |
| - | - |
| **Posture** | Each cluster's latest daily snapshot, so you can evidence a specific date rather than only today |
| **Findings** | Open findings by severity, with a count of severe findings that have a fix available |
| **Dispositions** | The exceptions in effect - what was accepted, by whom, and until when |
| **Audit summary** | Administrative actions over the requested window |
| **Attestation** | Whether MFA is required, SOPS is initialised, the security baseline is enabled, and which clusters have the scanner |
| **Compliance** | The live benchmark rollup per cluster |

> [!NOTE]
>
> The report requires **both** the security read and audit read permissions, and names the missing one in the `403` if you hold only one. That is deliberate: it combines posture with audit activity, so it should not be obtainable with half the access.

***

## How this maps to an ISMS

If you run a management system to ISO/IEC 27001 or an equivalent framework, the compliance layer supplies specific inputs to it. It does not replace the system.

| Your ISMS needs | What Ankra supplies |
| - | - |
| Technical controls that are monitored, not assumed | Continuous benchmark scoring per cluster, with tiers and coverage |
| A risk register with owners and review dates | Accepted-risk dispositions with actor, reason and mandatory expiry |
| Evidence that controls operated over a period | Daily posture snapshots plus the audit trail for the same window |
| Governed exceptions rather than silent suppression | Policy lifecycle states, review prompts, and no hard deletion |
| Segregation of duties | Read, triage and manage permissions on custom roles |
| Records that cannot be altered after the fact | Append-only audit written in the same transaction as the change |
| Change management (ISO/IEC 27001:2022 8.32) | A [standard-change catalogue](/security/change-management): routine changes are recorded as pre-approved with their reason, security upgrades name the advisories they fix, and everything else is a normal change approved through your own process |
| Management review inputs | Scheduled [security reports](/guides/security-reports) and the compliance report |

What remains yours: the scope statement, the risk assessment methodology, the Statement of Applicability, policy documents, internal audit, and management review. Ankra evidences a set of technical controls well; it is not the management system itself.

***

## Building an audit response

**1. Establish coverage**

Show which clusters are managed and which are reporting. Non-reporting clusters are visible in the compliance view and the attestation section. Coverage gaps are the first thing an assessor tests.

**2. Show the controls are configured**

Point at the attestation flags and the benchmark matrix. This demonstrates control design.

**3. Show they operated across the period**

Attach posture snapshots over the audit window and the [audit export](/security/audit-export) for the same window. Configuration proves design; the trail proves operation.

**4. Show exceptions were governed**

The dispositions section records what was accepted, by whom, and when it expires. A managed exception has an owner and a review date. An unexplained open finding does not.

***

## Limits worth stating up front

* **Ankra evidences the clusters it manages.** Clusters outside Ankra are outside this evidence, and an assessor will ask about them.
* **Benchmark results come from the scanner.** Ankra ingests, grades and retains Trivy Operator's output. The authority for a check is the benchmark specification, and a cluster without the scanner produces no result.
* **Benchmarks are not your whole control set.** CIS, NSA/CISA and PSS cover Kubernetes configuration. They say nothing about your application controls, your suppliers, or your people.
* **Nothing here certifies your environment.** The platform produces evidence; your assessor draws the conclusion.

***

## Ankra's own compliance posture

Everything above concerns **your** environment. A separate question comes up in procurement: what is Ankra's own certification status?

Ankra runs an internal information security management system covering the platform. The current, honest state of that work is published at [ankra.ai/trust](https://ankra.ai/trust), alongside the sub-processor and hosting list.

> [!WARNING]
>
> Take Ankra's certification status from [ankra.ai/trust](https://ankra.ai/trust) or from us directly, never from this documentation. That page is the single source of truth and it changes as the programme progresses.

For how Ankra's posture does and does not affect the scope of your own certification, see [Shared Responsibility](/security/shared-responsibility).

***

## Related

> [card] [Cluster Security](/guides/cluster-security)
>
> The Security Center interface, findings and dispositions.

> [card] [Security Reports](/guides/security-reports)
>
> Scheduled posture reports as review evidence.

> [card] [Audit Export](/security/audit-export)
>
> The administrative trail for the same period.

> [card] [Change Management](/security/change-management)
>
> Pre-approved standard changes for control 8.32.

> [card] [Shared Responsibility](/security/shared-responsibility)
>
> What Ankra is and is not accountable for.


# Verified Provenance at Deploy
Source: https://docs.ankra.ai/security/deploy-provenance

Make an application refuse any image that was not published by your organisation's pipeline gate - the three modes, the signing keys, verifying by hand with cosign, and what changes for rollbacks.

Verified provenance lets an application refuse to deploy an image unless the image carries signed proof that it passed **your organisation's** [Ankra Pipeline](/guides/ankra-pipelines) gate. An image built on a laptop, pushed by hand, or published by another organisation's pipeline carries no such proof and is not rolled out.

## How it works

When a pipeline's `publish` step pushes an image, Ankra signs a statement about it and stores the statement next to the image in your registry. The statement records:

* your organisation and the application
* the repository, commit and ref
* the pipeline run that built it
* that the gate passed for exactly this image digest
* the pipeline definition the run executed under

The statement is signed with a key that belongs to your organisation. Before an application rolls out an image, the deploy checks that the statement exists, that its signature verifies against a key your organisation trusts, and that it names this repository, this digest, this organisation and this application. Every deploy path goes through the check: the Deploy button, push-to-deploy, promotions and rollbacks.

## The three modes

| Mode | At publish | At deploy |
| - | - | - |
| `off` | No statement is signed. | Nothing is checked. |
| `warn` | A signed statement is stored. | Every image from the application's registry is checked. The deploy goes ahead whatever the result, and an image that does not verify raises a finding on the application. |
| `enforce` | A signed statement is stored. | The deploy is refused unless every image from the application's registry verifies. Each verified image is pinned to its digest in the manifest written to the cluster. |

The mode that applies is the first one set, in this order: the application's own mode, then your organisation's default, then Ankra's default. Applications created before 14 October 2026 default to `off`, so nothing changes until you choose. Applications created since default to `warn`.

Start with `warn`. Read the findings, publish through the pipeline, and move an application to `enforce` once the images you deploy, and the ones you might roll back to, were all published by a pipeline run that signed them.

## Set the mode

Setting a mode needs the `security.manage` permission. Reading needs `pipelines.read`, which every built-in role has.

> [tab] Web UI
>
> In the application's settings, the **Registry** section has a **Deploy provenance** card. It shows the mode the application deploys under and where it comes from: the application's own setting, the organisation default or Ankra's default. Change the mode from the same card. **Check now** verifies the images of the version serving in the selected environment the way a deploy would, and shows what a deploy would do. It deploys nothing.
>
> The organisation default and the signing keys are under **Organisation > Security**, in the **Deploy provenance** section.

> [tab] CLI
>
> ```bash theme={null}
> ankra application provenance get my-app
> ankra application provenance set my-app --mode enforce
> ankra application provenance set my-app --clear     # follow the organisation default again
> ankra org provenance set --mode warn                # the organisation default
> ```
>
> Turning `enforce` on asks first; `--yes` skips the question in scripts.

## Check an image before you deploy it

The dry run verifies images against an application's mode and reports what a deploy would do. It deploys nothing and changes nothing.

```bash theme={null}
ankra application provenance verify my-app --image <registry>/<repository>:<tag>
```

For each image it reports `verified`, `refused` or `unknown`, with the reason, and then the decision for the application's mode: `deploy`, `deploy_with_finding`, `refuse` or `not_checked`. `unknown` means Ankra could not ask the registry or the key store, which is different from the image failing the check. The command exits with status 1 when the decision is `refuse`, so a script can stop on it. Pass `--image` up to 32 times to check several images, and `-o json` for the full answer.

## Keys

Each organisation has its own signing keys. The newest key that is not revoked signs new images. Every key that is not revoked verifies, so rotating a key does **not** invalidate images that are already published.

```bash theme={null}
ankra org provenance keys                       # list keys and their status
ankra org provenance rotate                     # the new key signs from the next publish
ankra org provenance revoke <key-id> --reason "key exposed"
```

`ankra org provenance keys --public-keys` prints the public key of every key that is not revoked, one PEM block per key.

Rotating and revoking need `security.manage`, and both are written to the [audit log](/guides/audit-log), as is every mode change.

> [!WARNING]
>
> Revoking a key makes everything it signed stop verifying. An application in `enforce` refuses those images until they are published again. Revoking the active key makes the next publish create a successor.

An organisation can hold up to 16 key generations.

## Verify an image by hand

Anyone with read access can check a published image with [cosign](https://docs.sigstore.dev/cosign/) and the organisation's public keys.

```bash theme={null}
curl -s -H "Authorization: Bearer $ANKRA_TOKEN" https://platform.ankra.app/api/v1/org/provenance/keys > keys.json

# one file per trusted key
jq -r '.keys[] | select(.status != "revoked") | .key_id' keys.json | while read -r key_id; do
  jq -r --arg id "$key_id" '.keys[] | select(.key_id == $id) | .public_key_pem' keys.json > "provenance-$key_id.pub"
done

# cosign takes one key per check: try each until one verifies
for key in provenance-*.pub; do
  cosign verify-attestation --key "$key" --insecure-ignore-tlog=true \
    --type https://ankra.io/attestations/pipeline-gate/v1 \
    <registry>/<repository>@sha256:<digest> && break
done
```

An image verifies if any trusted key accepts it. `--insecure-ignore-tlog` is needed because these statements are not recorded in a public transparency log.

## Rollbacks under enforce

> [!WARNING]
>
> Under `enforce`, an application cannot deploy or roll back to an image that was published before its first signed publish. Older images carry no statement, so the deploy is refused with the reason `unsigned`.

Plan for this before you switch an application to `enforce`. If you need to roll back past the first signed version:

1. Set the application to `warn`: `ankra application provenance set my-app --mode warn`.
2. Deploy or roll back to the older version.
3. Set the application back to `enforce`.

You need `security.manage` for steps 1 and 3. The mode change is audited.

## What is checked

Only images from the application's own registry project are judged, because those are the images an Ankra pipeline publishes. Third-party images, such as a public database image or a chart's sidecar, are outside the check. They are listed as unchecked in the deploy output and in the dry run, and they are never refused.

The check covers deploys made through Ankra. A manifest edited by hand in your GitOps repository is not verified by it.

## When a deploy is refused

| What you see | What it means | What to do |
| - | - | - |
| Deploy fails with `application_deploy_provenance_unverified` | An image has no valid statement from your organisation's pipeline. The message names each image and the reason. | Publish through the application's pipeline, where a run that passes its gate signs the image, then deploy that. If the image is built elsewhere on purpose, set the application to `warn`. |
| Deploy fails with `application_deploy_provenance_unavailable` | The registry, its credential or the key set could not be read. | Deploy again once they answer. |
| A publish step reports `provenance_error` | The image was published but its statement was not stored. | Re-run the pipeline run. Storing the statement again is safe. Under `enforce` the image does not deploy until it is signed. |
| Deploy fails with a message that the policy could not be read | A temporary read failure. | Deploy again. |

## Related

* [Ankra Pipelines](/guides/ankra-pipelines)
* [Roles and access](/guides/roles-and-access)
* [Audit log](/guides/audit-log)


# Cluster Hardening
Source: https://docs.ankra.ai/security/hardening

The network, SSH, and control plane hardening Ankra applies when it provisions clusters, and the security add-ons you can layer on top.

When Ankra provisions a cluster, it does not just create VMs and install Kubernetes - it applies a set of infrastructure defaults that reduce the cluster's attack surface from the first boot. This page describes what those defaults are.

> [!NOTE]
>
> This page is about clusters **Ankra provisions**. Imported clusters keep the posture you built them with - Ankra manages their workloads through the agent but does not modify their infrastructure, and they have no Ankra bastion.

***

## Network posture

* **Tag-scoped cloud firewalls** - each node group and the bastion get their own firewall rules, scoped by provider tags rather than static IP lists, so rules follow nodes as they are added and removed.
* **Private networking with NAT** - where the provider supports it, nodes are placed on a private network with no public IPs; their egress is routed through the bastion or gateway.
* **Bastion jump hosts for SSH** - the bastion is the only host with a public IP, and SSH to nodes goes through it. See the [Hetzner architecture](/reference/hetzner#architecture) for a concrete example of this layout.

***

## SSH keys

Ankra generates a **4096-bit RSA key pair per cluster**. The key is held authoritatively in Ankra's secret store (HashiCorp Vault or OpenBao) and is never stored in the cluster definition - exporting, cloning, or committing a definition to Git cannot leak key material.

***

## Control plane joins

kubeadm join tokens are generated on demand when a node joins and **expire after 15 minutes**. There are no long-lived join secrets to rotate, leak, or forget about.

***

## Security add-ons

The add-on catalog covers the common security building blocks: **cert-manager**, **Kyverno**, **Trivy Operator**, **External Secrets**, **Sealed Secrets**, **Cilium**, **Istio**, and **Vault**. They install like any other [add-on](/concepts/addons) - visible in the platform, versioned, and removable - so there is no hidden security infrastructure you cannot inspect or take out.

Newly provisioned clusters start with the `ankra-security-baseline` stack profile: Trivy Operator for scanning, and Pod Security Standards enforced through the API server's own Pod Security Admission with a guard policy, so no policy engine has to sit on the admission path. Kyverno is available as the opt-in `ankra-policy-engine` profile. See [Security baseline](/guides/cluster-security#security-baseline).

***

## OS-level options

The cluster create flow has no OS-level audit or hardening options, and Ankra does not turn on OS audit logging (such as auditd) on nodes. On a cluster Ankra provisioned, two OS-level actions are available after creation from AI chat or the MCP server: `harden_bastion` applies a revertable SSH hardening set to the cluster's bastion, and `apply_node_os_policy` writes the node OS update policy to the bastion and the nodes.

***

## Related

> [card] [Security at Ankra](/security/overview)
>
> The trust model these defaults sit inside.

> [card] [Cluster Security](/guides/cluster-security)
>
> Vulnerability posture once the cluster is running.

> [card] [SOPS Encryption](/guides/sops)
>
> Encrypt sensitive values in your Stacks.

> [card] [Ankra Agent](/concepts/cluster-agent)
>
> The hardened, outbound-only agent pod.


# Identity & Access Controls
Source: https://docs.ankra.ai/security/identity-and-access

The sign-in, MFA, role and token controls behind platform access - and the evidence each one produces for an audit.

Access control is where most security questionnaires start and where most audit findings land. This page is the compliance view of Ankra's identity controls: what each control is, how to turn it on, and what evidence it produces. The step-by-step setup lives on the linked pages.

***

## Sign-in and SSO

Ankra sign-in is handled by a managed identity provider rather than by password storage in the platform. Members authenticate there, and the platform receives the resulting identity.

Each sign-in is bound to the browser that started it. The platform sends the OpenID Connect `state` and `nonce` parameters and a PKCE challenge with every authorisation request - password, social, single sign-on and invitation sign-ins alike - and completes a sign-in only when the provider's answer carries that state, the ID token carries that nonce, and the code is redeemed with the matching verifier. An answer the browser did not ask for is never completed: the sign-in restarts once, and a second unmatched answer stops on a page asking the person to sign in again. Connecting another sign-in method to an account is bound the same way, so a link started in one browser cannot be finished in another.

**Single sign-on** federates sign-in to your own identity provider, so accounts follow your joiner-mover-leaver process. An owner or admin connects an OpenID Connect provider - Microsoft Entra ID, Okta or any other - under **Organisation** → **Settings** → **Single sign-on**, with nothing for Ankra to enable first. The provider then decides who is a member and, if you map its groups, which role each member holds. Setup is in [Single Sign-On](/guides/single-sign-on).

> [!NOTE]
>
> The phrase "SSO-backed" appears throughout these docs in a second, narrower sense: [Cluster Access](/guides/cluster-access) and [kubectl access](/guides/kubeconfig) mint short-lived Kubernetes credentials tied to the member's Ankra identity, rather than distributing static kubeconfigs. That is true on every plan and is a different control from single sign-on federation.

Federating sign-in matters for two control families in particular: account provisioning and deprovisioning follows your directory, and your existing authentication policy - conditional access, device posture - applies to Ankra without Ankra needing to implement it.

Deprovisioning is not instant, and an auditor will ask how long it takes. Your provider does not notify Ankra of a removal; instead, a member the provider has not vouched for within the re-verification window is suspended, which stops their portal sessions, personal API tokens and Kubernetes access together. The window is 24 hours by default and can be set from 1 to 720 hours, so the answer to "how long does a leaver keep access" is at most one window. See [How access ends](/guides/single-sign-on#how-access-ends).

***

## Multi-factor authentication

Three second factors are supported, and an organisation can require MFA for every member.

| Factor | Notes |
| - | - |
| Authenticator app (TOTP) | Six-digit codes from any authenticator app |
| Passkeys and security keys | WebAuthn, covering platform passkeys and roaming keys - phishing-resistant |
| Recovery codes | One-time use, issued at enrolment |

When an organisation enforces MFA, a member who has not enrolled is blocked at sign-in until they do. That produces a clean binary answer to the "is MFA enforced for all users" question, and the state appears in the attestation section of the [compliance report](/security/compliance-management).

Setup and CLI equivalents are in [Account Security & 2FA](/platform/account-security).

> [!TIP]
>
> If your framework distinguishes phishing-resistant MFA - and increasingly they do - steer members to passkeys rather than TOTP. Both satisfy a generic MFA requirement; only WebAuthn satisfies a phishing-resistant one.

***

## Roles and scopes

Ankra grants permissions through **roles** assigned at a **scope**: the whole organisation, a single cluster, a cluster group, or a [project](/concepts/projects). A role can also bundle the Kubernetes access provisioned on every cluster the scope resolves to, so platform permissions and `kubectl` access are granted and revoked together rather than drifting apart.

This is the structure that lets you answer least-privilege questions concretely:

* **Scope narrowly.** An engineer who operates one team's clusters gets a role on that team's cluster group or project, not on the organisation.
* **Limit what a person can see, not only what they can do.** A **Project only** member holds no organisation role: they reach the projects they are assigned a role in and nothing else, and can never hold an organisation-level permission such as members, billing, tokens or the audit log. A project assignment of any role drops those permissions too.
* **Separate duties with custom roles.** The `audit.read` permission can be granted on its own, so a compliance function reviews and exports the trail without administrative access. The same applies to security read.
* **Use dynamic cluster groups.** A group defined by a label selector keeps access correct as clusters are created and retired, instead of relying on someone remembering to update a static list.

Roles, scopes and the CLI commands for managing them are documented in [Roles & Access](/guides/roles-and-access).

***

## Kubernetes access

Cluster access is granted through Ankra rather than by distributing credentials. Members authenticate as themselves and receive short-lived tokens minted on demand, so there are no static kubeconfigs to leak, rotate or collect on offboarding.

Requests reach the cluster through Ankra's authenticated proxy, which is why this works for private clusters with no inbound network path. See [Cluster Access](/guides/cluster-access) and [Accessing Clusters with kubectl](/guides/kubeconfig).

An [organisation access policy](/guides/cluster-access#organisation-access-policy) sets a ceiling on the role any grant can carry, what a cluster's creator is given, how long access above `view` may last, and from which role a grant needs a reason. For incident access without standing privilege, use [break-glass elevation](/guides/cluster-access#break-glass-elevation): time-boxed, reasoned access a person or service account gives itself, announced on your notification channels and recorded in the audit log.

### The identity your cluster sees

The Ankra agent re-issues every proxied request to the API server as the member, using Kubernetes impersonation. The API server, its RBAC and your admission policies see this identity:

| Field | Value |
| - | - |
| Username | `ankra:user:<ankra-user-id>` - the member's or service account's Ankra user ID, never an email address |
| Group | `system:authenticated`, which Kubernetes adds to every impersonated identity |
| Group | `ankra:users`, on every request through Ankra |
| Group | `ankra:org:<organisation-id>`, the organisation the credential belongs to |
| Group | `ankra:grant:<role>`, one per role the member holds on that cluster through a live grant (`view`, `edit`, `admin` or `cluster-admin`), whatever the grant's scope. A grant that has expired or been revoked no longer contributes its group |

The `ankra:` groups carry no permissions. Ankra binds every grant to the username, never to a group, so the groups only add names your policies can match. Do not bind a Role or ClusterRole to one of them yourself: that would grant access outside Ankra's access policy and its audit trail.

The groups are sent by agent version 2.1.1223 and later. An older agent impersonates the username alone, and so does an agent whose own service account may not impersonate groups (the agent's chart grants that permission; the agent logs a warning when it is missing). Check what a cluster sees with your Ankra kubeconfig:

```bash theme={null}
kubectl auth whoami
```

The `Groups` row lists the `ankra:` groups when they arrive.

Because the groups can be absent, write admission policies that use them to **exempt** a caller, never to deny one. This ValidatingAdmissionPolicy (Kubernetes 1.30 or newer) refuses namespace deletion through Ankra unless the member holds a `cluster-admin` grant on the cluster, such as a [break-glass elevation](/guides/cluster-access#break-glass-elevation). Requests that do not come through Ankra are left alone:

```yaml theme={null}
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: ankra-namespace-delete-needs-cluster-admin
spec:
  failurePolicy: Fail
  matchConstraints:
    resourceRules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        operations: ["DELETE"]
        resources: ["namespaces"]
  matchConditions:
    - name: through-ankra
      expression: "request.userInfo.username.startsWith('ankra:user:')"
  validations:
    - expression: "'ankra:grant:cluster-admin' in request.userInfo.groups"
      message: "Deleting a namespace through Ankra needs a cluster-admin grant on this cluster."
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: ankra-namespace-delete-needs-cluster-admin
spec:
  policyName: ankra-namespace-delete-needs-cluster-admin
  validationActions: ["Deny"]
```

On an agent older than 2.1.1223 this policy refuses every namespace deletion through Ankra, including by holders of `cluster-admin`, which fails closed. A `cluster-admin` grant scoped to a single namespace also produces `ankra:grant:cluster-admin`; if the exemption should mean cluster-wide access only, issue `cluster-admin` at cluster scope.

Ankra service accounts reach the cluster through the same gateway as people, as `ankra:user:<uuid>` with the same groups, so this policy applies to automation too. A service account that deletes namespaces needs its own `cluster-admin` grant on that cluster, or a break-glass elevation to `cluster-admin` where the organisation access policy allows it.

> [!WARNING]
>
> The Ankra audit log records who was given Kubernetes access and every credential minted against a cluster: access grants and their changes, kube-token minting (which is also how a kubeconfig is generated), and every pod terminal session, with a recording of the session. Individual Kubernetes API calls - through Ankra's proxy or any other client - are recorded only by your cluster's own audit policy. If you need a trail of in-cluster API activity, enable Kubernetes audit logging on the cluster.

***

## API tokens

Automation authenticates with API tokens rather than member credentials. For anything scheduled - evidence pulls, pipeline agents, integrations - issue a token for a member whose role grants only what the job needs, and treat the token as a credential with an owner and a review date.

See [Tokens](/reference/tokens) for issuing and revoking them.

***

## Evidence map

| Control | Where to get evidence |
| - | - |
| MFA enforced for all members | Attestation section of the [compliance report](/security/compliance-management) |
| Who holds which role, at what scope | Role assignments under **Organisation** → **Settings**, and the [audit export](/security/audit-export) for changes |
| Access changes over a period | [Audit export](/security/audit-export) filtered to access actions |
| Joiner, mover, leaver activity | Invitation, assignment and revocation entries in the audit trail; with single sign-on, the `sso_member_provisioned`, `sso_member_role_synced`, `sso_member_suspended` and `sso_member_restored` entries |
| Single sign-on configuration and who changed it | The `sso_connection_*`, `sso_policy_updated`, `sso_domain_*` and `sso_group_mappings_updated` entries in the [audit export](/security/audit-export) |
| Privileged access review | Role assignments plus the agent's cluster-admin binding, covered in [Agent Compliance Posture](/security/agent-compliance) |
| Credential handling | [Where it lives](/security/overview#where-it-lives) for how stored credentials and SOPS keys are held |

An access review usually needs two things: the current state, and the changes since the last review. The assignment views give you the first and the audit export gives you the second.

***

## Related

> [card] [Roles & Access](/guides/roles-and-access)
>
> Define roles, scopes and cluster groups.

> [card] [Account Security & 2FA](/platform/account-security)
>
> Enrol factors and enforce MFA.

> [card] [Audit Export](/security/audit-export)
>
> Export access changes for review.

> [card] [Cluster Access](/guides/cluster-access)
>
> Short-lived, identity-backed kubectl access.


# What Ankra Can See and Do
Source: https://docs.ankra.ai/security/overview

One page for a security review - the agent's permissions, the data Ankra receives and how long it keeps it, where it is hosted, who can reach it, and the settings that restrict each.

Before you connect a cluster, you need to know what Ankra can reach inside it, what it keeps, where that data lives, who can get at it, and how to limit each of those. This page answers those questions in one place. Where the honest answer is "more than you might assume", it says so, and every section links to the page with the detail.

***

## What the agent can do in your cluster

Ankra works in your cluster through the [Ankra Agent](/concepts/cluster-agent), a single pod you install with Helm. The agent's ClusterRole grants **every verb on every resource in every API group**, plus all non-resource URLs, bound cluster-wide. In practice that is cluster-admin. It needs that reach because it installs whatever Helm charts and manifests you choose, keeps them in the state you declared, and carries `kubectl` requests, logs and terminal sessions for the whole cluster. The ClusterRole cannot be narrowed through chart values today.

```mermaid theme={null}
flowchart LR
    subgraph Cluster["Your cluster"]
        Agent[Ankra Agent]
        KubeAPI[Kubernetes API server]
    end
    subgraph SaaS["Ankra control plane"]
        Platform[Platform API]
        Bus[Agent message channel]
    end
    Agent -->|"outbound only"| Platform
    Agent -->|"outbound only"| Bus
    Agent --> KubeAPI
```

What limits that power:

* **No inbound path.** The agent opens every connection, outbound, to the Ankra platform. Nothing on Ankra's side can connect into your network, and there are no ports to open. [Agent Compliance Posture](/security/agent-compliance#what-crosses-the-boundary) lists the endpoints.
* **A hardened pod.** Non-root, read-only root filesystem, all Linux capabilities dropped, `RuntimeDefault` seccomp, and no host namespaces or host paths.
* **An identity you can cut off from outside.** Each cluster has its own registration token and its own message-channel credentials. Revoking the token at the platform disconnects the agent without needing access to the cluster.
* **Changes go through a reviewable path.** Changes to your stacks are applied from a versioned definition, committed to your Git repository when one is connected. Changes the AI proposes are drafts a person approves, unless your organisation turns on [chat autonomy](/platform/ai-autonomy) for low-risk additive changes.
* **Uninstalling removes it.** `helm uninstall` and deleting the namespace remove the agent, its ServiceAccount and the ClusterRoleBinding.

For a control-by-control review of the agent, including how to record the cluster-admin binding as a justified exception, see [Agent Compliance Posture](/security/agent-compliance). To restrict its network egress and what it watches, see [Hardening the Agent](/security/agent-hardening).

***

## What leaves your cluster

Everything below travels over the agent's outbound connection, except the audit log, which Ankra writes itself when someone acts through the platform. Retention is how long Ankra keeps the data by default.

| Data | When it leaves | Stored by Ankra? | Retention |
| - | - | - | - |
| **Resource inventory** - the Kubernetes objects in the cluster (Deployments, Pods, Services, ConfigMaps, custom resources and so on), plus node and cluster metadata | Continuously, as the agent watches the cluster | Yes. **Secret values are replaced with SHA-256 digests** before they leave; key names remain | No fixed period |
| **Platform metrics** - node, namespace and workload usage for [cluster metrics](/platform/cluster-metrics) | Every 30 seconds, unless the cluster opts out | Yes | 30 days |
| **Pod logs** | Only when someone opens them in the console, the CLI or the AI Assistant | No, streamed to the person viewing them | Not kept |
| **Pod terminal and `exec` sessions** | Only when a member with `kubernetes.exec` opens one | Yes. A recording of what crossed the terminal, including anything the shell printed | Transcript 90 days; who opened it, where and when stays in the audit log |
| **Secret values revealed in the console, the CLI or the API** | Only when a member with `kubernetes.secrets_reveal` clicks **Reveal values** on one Secret, runs `ankra cluster get secrets <name> -n <namespace> --reveal`, or an API token asks for one Secret's values | Shown to that member. Each reveal is written to the audit log; the stored inventory keeps only the digests | Not kept |
| **Helm release values** | Only when someone opens a release. Passwords, tokens and keys in its values, the Secrets it renders and its notes stay hidden unless a member with `kubernetes.secrets_reveal` clicks **Reveal values** | Shown to that member. Each reveal is written to the audit log | Not kept |
| **Secrets read with `kubectl` through Ankra** | Only for a member with `kubernetes.secrets_reveal` and an access grant that allows it | Not stored. Each request is written to the audit log | Not kept |
| **Vulnerability findings** - CVE ids, severities, affected images and workloads | When [Trivy Operator](/guides/cluster-security) runs in the cluster (part of the security baseline) | Yes | No fixed period |
| **Software bill of materials** - package names, versions and licences per image | Only on clusters where SBOM generation is turned on (off by default) | Yes | No fixed period |
| **AI chat transcripts** - your questions and whatever cluster data the AI read to answer them | When a member uses the [AI Assistant](/platform/ai-assistant) | Yes, after secret redaction | Until the conversation is deleted |
| **Audit log** - actions taken in Ankra | Written by Ankra, not sent by the agent | Yes | 365 days |

Two things never leave the cluster: **container image contents**, because Trivy scans in-cluster and only its reports are read, and **values decrypted from Git**, because the agent decrypts [SOPS](/guides/sops) values at deploy time and never sends the result back. Your application traffic, volume data and database contents do not pass through the agent either. [Backups](/concepts/backup-vaults) are written straight from the cluster to a bucket you own, not to Ankra.

> [!NOTE]
>
> Browsing a cluster in Ankra shows a Secret's key names and value digests, never the values. Reading the values needs the `kubernetes.secrets_reveal` permission, which the `owner`, `admin` and `operator` roles hold and `member` and `viewer` do not. It is a separate, explicit request for one Secret, and each one is written to the audit log with who, which cluster and which Secret. Listings never return values, and the AI never sees them, whatever the member's role.
>
> The same permission covers the two other ways to read a credential through Ankra. A Helm release's values hide passwords, tokens and keys until the member reveals them. `kubectl` through Ankra refuses any request for Secrets from a member without the permission, whatever Kubernetes role their [access grant](/guides/cluster-access) gives them, and records every request it lets through.

***

## Where it lives

**The control plane.** The Ankra platform, its databases, its metrics store, the message channel agents connect to, and its secret store run in the EU, in Finland, with a warm standby in a second data centre in Finland. Database backups are kept in Germany. The providers behind these, and every other sub-processor, are listed at [ankra.ai/trust](https://ankra.ai/trust).

**[Ankra Cloud](/guides/ankra-cloud-kubernetes) clusters (closed beta).** A cluster you run on Ankra Cloud sits on infrastructure the Ankra team operates, so for that cluster Ankra is also your hosting provider. Every other cluster runs on infrastructure and accounts you control.

**Secrets you give Ankra.** Cloud, Git and registry credentials, and AI provider keys, are stored encrypted in a Vault-compatible secret store (OpenBao or HashiCorp Vault) and decrypted only when a provisioning or deployment action needs them. Removing a credential deletes it from the store. For values that live in Git, each organisation has its own [SOPS](/guides/sops) key pair: Git receives only ciphertext, and the private key is delivered only to your clusters. A value you enter in the Stack Builder is held by the control plane as entered, so that Ankra can seal it each time it writes to Git.

**The AI model provider.** When a member uses an AI feature, Ankra sends the question and the cluster data its tools read (resources, events, logs) to a model provider. Detected secret values are redacted from tool results before the model sees them, and the AI's tools read Kubernetes Secrets as key names and counts only. Which provider receives the data is your choice under **AI** → **Settings** → **Models** - see [AI Provider](/platform/ai-provider):

* **Ankra** (the default) - Ankra's own key, routed to third-party model providers.
* **Anthropic** or **OpenRouter** - your own key and your own agreement with that provider.
* **OpenAI-compatible** - any endpoint you run or choose, including a self-hosted model, so model traffic goes only where you point it.

Scheduled AI analysis of your clusters ([AI Insights](/platform/ai-insights)) is off by default. Without it, AI features send data only when a member uses them.

***

## Who can reach it

* **Sign-in.** Members sign in through a managed identity provider (Auth0); Ankra does not store passwords. Federation to your own identity provider is available on the Enterprise plan. See [Identity & Access Controls](/security/identity-and-access).
* **MFA.** Authenticator apps, passkeys and security keys, and recovery codes. An organisation can require MFA for every member. See [Account Security & 2FA](/platform/account-security).
* **Roles.** Five built-in roles - `owner`, `admin`, `operator`, `member` and `viewer` - plus custom roles, each assigned for the whole organisation, one cluster, or a cluster group. The [permission matrix](/guides/roles-and-access#permission-matrix) shows exactly what each role can do.
* **Tokens.** Scripts, CI and MCP clients use API tokens. A token carries its own scopes on top of the role of the member or service account behind it, so it can be narrower than that role but never wider. See [Service Tokens](/guides/service-tokens) and [Tokens](/reference/tokens).
* **Kubernetes access.** `kubectl` access goes through Ankra with short-lived tokens tied to the member, instead of shared kubeconfigs. See [Cluster Access](/guides/cluster-access).

***

## How to restrict it

| To limit | Do this | Where |
| - | - | - |
| What the agent watches and sends | Set `k8s_watch.dynamic_discovery: false` in the agent's Helm values, so it watches only its built-in list of resource types and not every custom resource in the cluster | [Hardening the Agent](/security/agent-hardening#turn-off-optional-egress) |
| Platform metrics | Set `metrics_collect.enabled: false` in the agent's Helm values. The cluster's built-in metrics views then stay empty | [Cluster Metrics](/platform/cluster-metrics) |
| Where the agent can connect | Apply a `NetworkPolicy` that allows the agent's namespace to reach only the Ankra endpoints and your registry | [Hardening the Agent](/security/agent-hardening#restrict-network-egress) |
| Terminal and `exec` access | Keep `kubernetes.exec` out of the roles most people hold. Among the built-in roles only `operator`, `admin` and `owner` have it | [Roles & Access](/guides/roles-and-access#permission-matrix) |
| Reading stored credentials | Keep `credentials.reveal` to the few people who need it. Among the built-in roles only `admin` and `owner` have it | [Roles & Access](/guides/roles-and-access#permission-matrix) |
| Reading Kubernetes Secret values | Keep `kubernetes.secrets_reveal` to the people who need it. Among the built-in roles `operator`, `admin` and `owner` have it. It also covers Helm release values and Secrets read with `kubectl` through Ankra. Every reveal is in the audit log. Give members who must not see credentials a `view` access grant: a grant that can open a shell in a pod can still read a Secret the pod mounts | [Roles & Access](/guides/roles-and-access#permission-matrix), [Audit Export](/security/audit-export) |
| Who can browse a cluster | Assign roles on a cluster or cluster group rather than the whole organisation | [Roles & Access](/guides/roles-and-access#scopes) |
| Which model provider sees cluster data | Switch the AI provider to your own key or your own endpoint | [AI Provider](/platform/ai-provider) |
| Scheduled AI analysis | Leave proactive AI Insights off (the default), or turn AI Insights off for one cluster | [AI Insights](/platform/ai-insights) |
| Package inventories leaving the cluster | Leave SBOM generation off (the default) | [Cluster Security](/guides/cluster-security) |

***

## Evidence and compliance

* [Shared Responsibility](/security/shared-responsibility) - where Ankra's responsibility ends and yours begins, and what that means for a SOC 2 or ISO 27001 scope.
* [Agent Compliance Posture](/security/agent-compliance) - the agent, control by control.
* [Audit Log](/guides/audit-log) and [Audit Export](/security/audit-export) - who did what in Ankra, and how to get the trail out.
* [Compliance Management](/security/compliance-management) - benchmark scores across the fleet, exceptions with owners and review dates, and an evidence report.
* [Cluster Security](/guides/cluster-security) - vulnerability findings across the fleet, ranked by what is being exploited.

[Ankra Security Center: fix what is actually exploited](https://www.youtube-nocookie.com/embed/fd4KBfPkMG0?rel=0)

To have an organisation's stored data removed when you leave Ankra, and for the offboarding timeline, [contact support](/platform/support).

> [!WARNING]
>
> Take Ankra's own certification status and its sub-processor list from [ankra.ai/trust](https://ankra.ai/trust) or from us directly, not from this documentation. That page is kept current as the programme progresses.

**Next:** if you are reviewing the agent for approval, go to [Agent Compliance Posture](/security/agent-compliance). If you are ready to connect a cluster, start with [Hardening the Agent](/security/agent-hardening) so the restrictions above are in place from the first install.


# Shared Responsibility
Source: https://docs.ankra.ai/security/shared-responsibility

Where Ankra's responsibility ends and yours begins, and what that means for the scope of your SOC 2 or ISO 27001 certification.

Ankra is a **delivery and management plane**, not a hosting provider. Your clusters run on infrastructure you own or rent, in accounts you hold, under contracts you signed. Ankra provisions, configures and reconciles them - it does not host them and does not sit in the path of your production traffic. Your application data stays in your clusters, apart from the specific paths listed under [Ankra is not in your data path](#ankra-is-not-in-your-data-path).

The exception is [Ankra Cloud](/guides/ankra-cloud-kubernetes) (closed beta): a cluster you run there sits on infrastructure the Ankra team operates, so for that cluster Ankra is also your hosting provider.

That distinction is what keeps Ankra's footprint in your compliance programme small, and it is the first thing to establish with an assessor.

***

## The boundary

```mermaid theme={null}
flowchart LR
    subgraph Yours["Your responsibility"]
        Infra["Infrastructure account<br/>and hosting contract"]
        Data["Application data<br/>and its classification"]
        Apps["Your workloads"]
    end
    subgraph Shared["Shared"]
        Cluster["Cluster configuration<br/>declared in your Git"]
    end
    subgraph Ankra["Ankra's responsibility"]
        Plane["Control plane availability<br/>and its own security"]
        Deliver["Provisioning, reconciliation,<br/>add-on delivery"]
    end
    Infra --> Cluster
    Cluster --> Deliver
    Apps --> Data
```

| Layer | You | Ankra |
| - | :-: | :-: |
| Hosting contract, cloud account, physical and virtual infrastructure | Yes | - |
| Network fabric, firewalls, DNS reachability | Yes | - |
| Your applications and the data inside them | Yes | - |
| Data classification, retention and DLP for your workloads | Yes | - |
| Who you grant access to, and at what scope | Yes | - |
| The desired state you commit to Git | Yes | Reconciled by Ankra |
| Cluster provisioning and lifecycle on your infrastructure | - | Yes |
| Add-on and Stack delivery, drift correction | - | Yes |
| The cluster agent and its behaviour | - | Yes |
| Ankra control plane security, availability and its own ISMS | - | Yes |
| Incident response for the Ankra platform | - | Yes |
| Incident response for your workloads | Yes | - |

> [!NOTE]
>
> For fully self-hosted deployments the split shifts further toward you, because the control plane itself runs on your infrastructure. Talk to us about the on-premise specification if that is your requirement.

***

## What this means for your certification

The common assumption is that adding a platform vendor drags a large new area into audit scope. For Ankra that is not the case, for three specific reasons.

### Ankra is not your hosting sub-service organisation

Your cloud or hosting provider remains the sub-service organisation for infrastructure controls - physical security, environmental controls, hypervisor isolation, hardware disposal. Ankra does not replace them, does not sit underneath them, and does not inherit their control set. Adding Ankra does not change which infrastructure provider your assessor examines, and does not add a second one. The exception is a cluster on [Ankra Cloud](/guides/ankra-cloud-kubernetes), where Ankra is the hosting provider for that cluster.

Ankra enters your programme as a **supplier providing a management service**, assessed the same way you would assess a CI/CD vendor or an infrastructure-as-code tool.

### Ankra is not in your data path

The agent is a control-plane client, not a proxy or sidecar. It does not terminate your application traffic, mount your application volumes, or connect to your databases, so your regulated data does not flow through Ankra in the normal course of things. Four paths can still surface it, which is why [Agent Compliance](/security/agent-compliance) rates this **Conditional**:

* **Pod logs and terminals** - log views and terminal sessions show whatever your workloads print, and Ankra keeps a recording of each terminal session for 90 days.
* **Secrets in the console** - anyone who can browse a cluster's resources in Ankra can open a Secret there and read its values.
* **AI features** - what the AI reads to answer a question is sent to the organisation's model provider and kept in the chat transcript, with detected secret values redacted.
* **Backups** - restore points carry volume and database contents, written to a [backup vault](/concepts/backup-vaults) bucket you own rather than to the platform.

Everything Ankra receives and keeps, with its retention, is listed in [What leaves your cluster](/security/overview#what-leaves-your-cluster).

### Ankra is not in your availability path

If the Ankra control plane is unreachable, your clusters keep running and keep serving traffic. Workloads are unaffected, the Kubernetes control plane is unaffected, and the agent buffers what it cannot send and replays it when the connection recovers. What pauses is reconciliation and platform visibility, not your service.

This matters for availability-related criteria: an Ankra outage is a **management** outage, not a production one, and it does not belong in the same category as your hosting provider going down.

***

## Where Ankra appears in your audit

Rather than a broad scope expansion, expect Ankra to surface at these specific points.

| Control area | How Ankra appears | Evidence to point at |
| - | - | - |
| Supplier and third-party risk | A supplier providing cluster management. Assess as a vendor. | Your supplier register entry, plus Ankra's published posture |
| Privileged access | The agent's cluster-admin ServiceAccount, and platform roles held by your staff | [Agent Compliance Posture](/security/agent-compliance), [Roles & Access](/guides/roles-and-access) |
| Change management | Cluster changes as attributed Git commits, plus platform actions in the audit log | [GitOps](/concepts/gitops), [Audit Export](/security/audit-export) |
| Logging and monitoring | The organisation audit trail and its retention | [Audit Export](/security/audit-export) |
| Access control and authentication | Managed sign-in (or single sign-on to your own identity provider), enforced MFA, scoped roles | [Identity & Access Controls](/security/identity-and-access) |
| Configuration and vulnerability management | Benchmark results and policy state per cluster | [Compliance Management](/security/compliance-management) |
| Data transfer | Cluster data sent to the control plane and, for AI features, to the model provider, under a processing agreement | [What leaves your cluster](/security/overview#what-leaves-your-cluster) |

> [!TIP]
>
> Most SOC 2 reports treat a management vendor like Ankra under the **carve-out method** - the vendor's controls are excluded from the report and handled through vendor management instead. That is usually the right choice here, and it is the least work for you.

***

## What Ankra does not do for your compliance

Being explicit about the limits is more useful than a long list of claims.

* **Ankra does not certify your environment.** The platform produces evidence about your clusters. An assessor still decides whether your controls are effective.
* **Ankra does not make your workloads compliant.** Application-layer controls, data handling inside your services, and your own SDLC remain yours.
* **Ankra does not replace your hosting provider's attestations.** You still collect those separately.
* **Ankra is not a substitute for your ISMS.** The platform is one control among many, and the compliance report is input to your programme, not the programme itself.
* **Using Ankra does not by itself satisfy any control.** It gives you the mechanism and the evidence; you still need the policy and the review cadence around them.

***

## Ankra's own security programme

Ankra runs its own information security management system, and the honest status of that work - certifications held, controls implemented, and what is still in progress - is published and kept current at [ankra.ai/trust](https://ankra.ai/trust). Sub-processors and hosting providers are listed there too.

> [!WARNING]
>
> Do not treat this documentation as an attestation of Ankra's certification status. Where your procurement process needs a current statement, take it from [ankra.ai/trust](https://ankra.ai/trust) or ask us directly - that page is the single source of truth and it changes as the programme progresses.

***

## Related

> [card] [What Ankra Can See and Do](/security/overview)
>
> What leaves your cluster, where it is stored, and how to restrict it.

> [card] [Agent Compliance Posture](/security/agent-compliance)
>
> Control-by-control scope determination for the cluster agent.

> [card] [Roles & Access](/guides/roles-and-access)
>
> The permission matrix for every built-in role.

> [card] [Compliance Management](/security/compliance-management)
>
> Generate the evidence an assessor asks for.


# Claude Code to Two Clusters
Source: https://docs.ankra.ai/use-cases/claude-code-to-two-clusters

Build a codebase with Claude Code, hand the repository to Ankra, and run it on a development and a production cluster - what Ankra generates for you (Dockerfile, manifests, pipeline, scans, fixes), who is responsible for which part once it is live, security in every Stack, CVE handling and the security email, SOPS encryption, and the Ankra automations and AI agents that fix and maintain it on day 2.

Claude Code writes the application. Ankra writes everything that turns a repository into a running, scanned, promotable service, and runs it on your clusters. You decide what ships to production.

This page follows one codebase from an empty folder to two environments: a **development** cluster that follows every merge, and a **production** cluster that only moves when a person promotes a tag that development has already proved.

![Claude Code, with the Ankra skills installed, writes the code and tests and pushes to GitHub. Ankra writes a setup pull request with the Dockerfile, Kubernetes manifests, .ankra/ankra.yaml, .ankra/pipeline.yaml and Postgres when needed, and fixes its own checks. Ankra Pipelines tests, builds, scans, gates and publishes an immutable sha tag in your cluster. Every pull request gets an Ankra AI review, a preview URL and fix pull requests. Every merge deploys to the development cluster; a person promotes the tag that passed to the production cluster, which runs the same image. On day 2 Ankra watches both clusters with AI review, alerts, backups, CVEs ranked by exploitation, Kubernetes upgrades and rollback, and the next change goes back through Claude Code.](https://mintcdn.com/ankra/E9P8YZqZtdVwPrtf/images/use-cases/claude-code-to-two-clusters.svg?fit=max\&auto=format\&n=E9P8YZqZtdVwPrtf\&q=85\&s=00a80dce76db321e55f5cec93ed0275f)

Claude Code writes, Ankra generates and runs, a person promotes

***

## What you need

* [Claude Code](https://claude.com/claude-code) and the [Ankra CLI](/integrations/ankra-cli), logged in with `ankra login`.
* An empty GitHub repository, and a [GitHub credential](/integrations/github) in your organisation that can reach it.
* Two clusters in the same organisation: one for development and one for production. They can be clusters Ankra builds for you ([Ankra Managed](/guides/operate-ankra-managed-clusters)), clusters your cloud runs ([Managed Kubernetes](/guides/managed-kubernetes)), or clusters you [import](/guides/import-cluster).
* A cluster your organisation runs CI on, for [Ankra Pipelines](/guides/ankra-pipelines#before-your-first-run). The development cluster is a good choice.

***

## Build it and hand it over

**1. Give Claude Code the Ankra skills**

Install Ankra's [Agent Skills](/integrations/agent-skills) into Claude Code. They teach it to use the Ankra CLI and the Ankra workflow instead of writing raw Kubernetes and CI files by hand:

```bash theme={null}
ankra skills install --client claude-code --with-hooks
```

Optionally add the [Ankra MCP server](/platform/mcp-server), so Claude Code can read clusters, pipeline runs and logs directly.

**2. Build the codebase**

Work with Claude Code the way you normally would. Two things make the hand-over clean: write down the standards it must follow, and tell it which files are Ankra's job.

```
Build <one paragraph describing the app> in this repository.

Standards: <your language, framework, database and migration tool>.
Every module has unit tests, and `<test command>` runs them all.
The app reads its configuration from environment variables, listens on one
port, and answers GET /healthz without touching the database.

Do not write Kubernetes manifests or CI workflows: Ankra generates them.
Commit in small steps and push to main when the tests pass.
```

For a longer build, split it into planned stages as described in [Prompt to Production](/use-cases/prompt-to-production).

> [!TIP]
>
> A `/healthz` endpoint, configuration from environment variables and a test script that exits non-zero on failure are the three things that make the generated packaging work first time. Ankra's pipeline runs your tests only when the repository declares a test command.

**3. Hand the repository to Ankra**

From the checkout, with the development cluster:

```bash theme={null}
ankra application ship . --cluster <dev-cluster-id>
```

Or ask Claude Code to do it with the `/ankra-ship-service` command the skills installed. `ship` registers the application, waits for Ankra's analysis and setup pull request, waits for the first build, deploys, and prints:

```
Live: https://<app>.<cluster-domain>
```

[Ship from your checkout](/guides/deliver-your-app#ship-from-your-checkout) explains each step it waits on. Re-running it is always safe.

***

## What Ankra generates for you

When the repository is registered, Ankra's AI reads it, detects the language and framework, and works out what it needs to run. It writes the result as one **setup pull request** in your repository, so every generated file is something you can read and review.

| Generated | What it is | Notes |
| - | - | - |
| `Dockerfile` | The image build for the detected framework | Only when the repository has none. A Dockerfile Claude Code or you commit is used as-is and never overwritten |
| Kubernetes manifests | Deployment, Service, and the Ingress for the public address | Sized by the deploy mode: one replica for quick, more for high availability |
| `.ankra/ankra.yaml` | The deploy options: port, replicas, ingress, namespace | The values `--set` overrides at deploy time |
| `.ankra/pipeline.yaml` | The CI definition, run as Jobs in your own cluster | Test (when a test command exists), rootless build, scan, gate, publish |
| A Postgres database | A CloudNativePG cluster, with `DATABASE_URL` wired to the app | Only when the analysis finds the app needs Postgres. No password is ever copied by hand |

From then on, Ankra does these on every change without being asked:

* **Builds and scans.** Each push is built rootless in your cluster, scanned with Semgrep over the source, Checkov over the manifests and Trivy over the image, and judged against your organisation's security gate before anything is published.
* **Publishes an immutable tag.** A passing build on the tracked branch is published as `sha-<7>`. No tag is ever overwritten, so the tag you tested is byte-for-byte the tag you promote.
* **Fixes its own setup pull request.** If the setup pull request fails its checks, usually on a vulnerable dependency the repository already had, Ankra AI commits a fix to the same pull request and explains it in a status comment. See [When the setup pull request does not pass its checks](/concepts/applications#when-the-setup-pull-request-does-not-pass-its-checks).
* **Investigates failed builds.** A failed build on the tracked branch dispatches an agent that proposes a fix, or opens a fix pull request if you allow it. See [When a build on your branch fails](/concepts/applications#when-a-build-on-your-branch-fails).
* **Reviews pull requests.** Ankra AI reviews every pull request against your organisation's skills, and can post a live preview URL for each one. See [Application AI settings](/platform/application-ai) and [Pull request preview environments](/guides/pr-preview-environments).
* **Gives it an address.** The app gets a hostname under the cluster's domain with a TLS certificate, or your own domain. See [Domains and DNS](/guides/avura-domains).

> [!NOTE]
>
> The generated pipeline needs a person to approve it once. Creating the application in the portal approves it in your name. An application added from the CLI, an API token or Claude Code leaves that approval to an administrator: `ankra pipeline get --application <name> --latest` prints the exact approve command. This is deliberate: an agent can propose a pipeline, but only a person can authorise what runs in your cluster.

***

## Deploy to two clusters

One application deploys to as many environments as you give it. Each environment is a cluster and a namespace with its own deploy options, its own database and its own push-to-deploy switch.

**1. Development follows every merge**

The first `ship` already deployed to development. Push to deploy is on from registration, so every successful build of the tracked branch now rolls out there automatically. Give development its own namespace and address if you want them explicit:

```bash theme={null}
ankra application deploy <application-id> --cluster <dev-cluster-id> --namespace shop-dev \
  --set ingress_enabled=true --set ingress_host=shop.example.dev
```

**2. Set the secrets**

Application secrets are stored in Ankra, never committed. Pipe them in so they never land in your shell history:

```bash theme={null}
printf '%s' "$STRIPE_KEY" | ankra application env-secrets set <application-id> STRIPE_KEY
ankra application env-secrets apply <application-id>
```

These secrets belong to the application, and `apply` seals them into every deployment of it, in development and production alike. A value that must differ between the two, such as a test and a live payment key, belongs in each cluster's own configuration instead: encrypt it with SOPS in that cluster's Stack, as described in [Encryption and SOPS](#encryption-and-sops). The generated database is already separate per environment. To reuse a database, registry or API the organisation already has, see [Connect to a managed service](/guides/connect-to-a-managed-service).

**3. Production moves only when a person promotes**

In the portal, open the application's **Settings** → **Push to deploy**. Under **What follows pushes**, leave development on and turn production off. Then promote the exact tag development proved:

```bash theme={null}
ankra application deploy <application-id> --cluster <prod-cluster-id> --namespace shop \
  --set image_tag=sha-<the-tag-that-passed> \
  --set replicas=3 --mode high_availability \
  --set ingress_enabled=true --set ingress_host=shop.example.com
```

Promotion moves the image tag only: never a rebuild. You can also promote from the application's **Environments** page, or ask Claude Code with `/ankra-promote`, which promotes a verified tag without rebuilding it and stops for your confirmation.

> [!WARNING]
>
> `ankra application auto-deploy set <application-id> --enabled=false` turns push to deploy off for **every** environment of the application. Use the per-environment switch in **What follows pushes** when development should keep following merges.

***

## Who is responsible for what

Ankra automates a lot, so it matters to be explicit about what it does not do. The rule of thumb: **Ankra generates and runs; you decide and own.** Anything Ankra generates lands as a pull request or a file in your repository, and once you merge it, it is yours.

| Area | Claude Code / you | Ankra |
| - | - | - |
| **Application code and tests** | Writes and owns them. Ankra never rewrites application logic | Runs the tests on every push when a test command exists |
| **Dependencies** | Chooses them and keeps them current | Scans them on every build, flags known exploited CVEs first, and proposes fixes when a build fails |
| **Dockerfile and manifests** | Reviews the setup pull request. After merge, they are your files to change | Generates them once, when missing. Never overwrites a file you committed |
| **Pipeline definition** | A person approves it once, and approves any change to what it may do | Generates `.ankra/pipeline.yaml` and runs it in your cluster |
| **Build, scan, publish** | Sets the organisation's security gate threshold | Builds rootless, scans, applies the gate, publishes an immutable tag |
| **Secrets** | Owns the values and rotates them | Stores application secrets, seals them into every deployment, rolls pods on apply. Decrypts SOPS values per cluster at deploy time |
| **Encryption keys** | Initialises encryption once and lists which keys are sealed | Holds the organisation's AGE private key, seals listed keys on every push to Git, refuses a push it cannot seal |
| **Cluster security baseline** | Chooses Audit or Enforce per cluster, and the exempt namespaces | Installs the baseline, scans every running image, labels namespaces for Pod Security Admission |
| **CVEs on running images** | Fixes, or accepts the risk with a reason and a review date | Finds them, ranks them by real-world exploitation, emails the summary, alerts on new known-exploited ones |
| **Development deploys** | Decides that development follows merges | Rolls out every passing build of the tracked branch |
| **Production deploys** | **A person promotes a tag.** Keep agents that can reach production at **Propose**, so they suggest and you decide | Deploys the tag you chose, tracks the rollout, keeps the history for rollback |
| **AI actions** | Chooses Ask or Agent per lane, can pause autonomous actions, and reviews every fix PR | Investigates and explains. Commits fixes to the branch of a failing pull request from your repository, never to a fork's, and fixes the tracked branch only through pull requests you merge |
| **Clusters it builds** (Ankra Managed) | Chooses provider, size, and when to move to a new Kubernetes minor version | Provisions nodes and control plane, scales node groups, runs upgrades node by node with an etcd snapshot first, and applies patch versions on its own if you turn on auto upgrade |
| **Clusters your cloud runs** (EKS, GKE, AKS and others) | Owns the account and the provider's lifecycle | Runs the Stacks and applications on top, and node pool operations through the provider |
| **Imported clusters** | Owns the cluster and its upgrades | Runs the Stacks and applications on top |
| **Platform add-ons** (ingress, cert-manager, monitoring) | Chooses them and pins their versions in Git | Reconciles the cluster to what Git says |
| **Data** | Decides which Stacks hold data and how long to keep it | Takes restore points into your vault on the schedule you set, and restores on request |
| **Alerts** | Decides who gets paged for what | Raises the notifications and delivers them where you route them |

Two lines in that table are the ones to hold on to: Claude Code can do almost everything up to a production deploy, and **production is a decision a person makes**. In Agent mode, every write the AI proposes stops at a confirmation card, and the pipeline approval is never something an agent can grant itself.

For the platform-wide boundary, including what this means for your own audits and certifications, see [Shared responsibility](/security/shared-responsibility).

***

## Security, CVEs and encryption

Security is not a stage you add at the end. Each cluster carries a security baseline, every Stack shows what its containers are exposed to, every CVE is ranked by whether it is actually being exploited, and every secret in Git is encrypted.

### Security in every Stack

**The baseline.** Clusters Ankra builds get the `ankra-security-baseline` Stack profile at create time, unless your organisation opted out. On an imported or cloud-run cluster, open the cluster's **Security** page and choose **Enable security baseline**. The baseline carries:

* **Trivy Operator**, which scans every running image, audits configuration and runs the CIS benchmark.
* **Pod Security Standards enforced by Kubernetes itself.** The Ankra agent labels namespaces for Pod Security Admission, which is built into the API server, so no policy engine has to run. Start both clusters in **Audit**, fix what development reports, and switch production to **Enforce** once it is clean.
* **A guard on the enforce label**, so nobody can switch enforcement off with a namespace edit.

If you need image-signature verification or policies of your own, add the opt-in `ankra-policy-engine` profile, which runs Kyverno.

**The Stack Security tab.** Every Stack's detail page has a **Security** tab that lists the running pods under the add-on or manifest that deploys them. Each container has its own **CVE**, **SBOM** and **KEV** report, so "is the Postgres in this Stack exposed?" is one click, or one command:

```bash theme={null}
ankra security stacks --cluster <prod-cluster-id>
ankra security stack <stack-name> --cluster <prod-cluster-id>
ankra security addon <addon-name> --cluster <prod-cluster-id>
```

A container the scanner has not reached reads **Not scanned**, never zero. See [Stack security](/guides/cluster-security#stack-security).

### Dealing with CVEs

CVEs arrive at two points, and Ankra handles each one differently:

* **Before an image ships.** The pipeline scans every build with Semgrep, Checkov and Trivy, and your organisation's gate refuses to publish anything above its threshold. `ankra pipeline findings <run-id> --application <name>` lists what stopped a build, worst first.
* **After an image is running.** A CVE published next month lands on the image already in production. Trivy Operator finds it, and the Security Center cross-references it with the CISA Known Exploited Vulnerabilities (KEV) catalogue and FIRST EPSS scores, so the top of the list is what attackers are actually using.

When a CVE turns up in production:

**1. Look at what is exploited first**

```bash theme={null}
ankra security findings --known-exploited --cluster <prod-cluster-id>
ankra security advisory <cve-id>
```

The advisory gives the affected versions, CISA's required action and remediation deadline, and every place in your organisation the vulnerable package runs.

**2. Fix it through the same pipeline**

Hand the fix to Claude Code. It is a normal change: a pull request, scanned again, deployed to development, then promoted.

```
Fix <cve-id> in this app. Run `ankra security advisory <cve-id>`, bump the
dependency or base image to the first fixed version, open a pull request, and
confirm the Ankra pipeline scan no longer reports it.
```

**Fix with AI** on the exploited-in-the-wild banner starts the same work from the portal.

**3. Or decide, on the record**

If there is no fix yet, or the vulnerable code path is never reached, record a decision instead of ignoring the finding. **Acknowledged** keeps it actionable and alerting. **Accepted risk** removes it from actionable counts and alerts, and needs a reason, a review date at most a year out and the `security.manage` permission. Every disposition is audited. An image-scoped acceptance follows the image digest, so the next rebuild brings the finding back for a fresh decision. See [Acknowledge vs accept risk](/guides/cluster-security#acknowledge-vs-accept-risk).

To hear about a new exploited CVE before anyone asks, route the `security_findings` alerts (`kev` and `new_kev_cves`) to the team that owns the app. See [Alerts](/guides/alerts).

### The security email

Each cluster can email a security report weekly or monthly, for example to your security team or an auditor. Recipients do not need an Ankra account. The report shows actionable findings by severity and how they moved since the last report, puts known-exploited CVEs in their own banner, and lists the package upgrades that clear them under **Fix these first**. Accepted risk is left out, so the report only shows what still needs work.

```bash theme={null}
ankra security report-schedule set --cluster <prod-cluster-id> --frequency weekly \
  --recipient security@example.com --recipient team@example.com
ankra security report-schedule send --cluster <prod-cluster-id>
```

`send` emails the current report right away, so you can check delivery before the first scheduled one. The same schedule is under the cluster's **Settings** → **Integrations**. The report needs Trivy Operator, which the security baseline installs. See [Security reports](/guides/security-reports).

### Encryption and SOPS

Everything about a cluster lives in Git, and Git must never see a plaintext secret. Ankra encrypts values with [SOPS](/guides/sops) and an AGE key that belongs to your organisation:

**1. Initialise encryption once**

In **Organisation Settings** → **Encryption**, choose **Initialize Encryption**. Ankra generates the AGE key pair: the public key seals values, and the private key stays in Ankra's secret store. Decryption on each cluster is automatic, so there is nothing to configure per cluster.

**2. Mark which keys are sealed**

In the Stack Builder, list a manifest's or add-on's sensitive keys under **Encrypted Keys (SOPS)**. Or from the CLI, where a `glob:` pattern also covers keys you add later:

```bash theme={null}
ankra cluster encrypt manifest shop-secrets --key 'glob:stringData.*' --cluster <prod-cluster-id>
ankra cluster encrypt addon --name grafana --key adminPassword --cluster <prod-cluster-id>
```

Ankra seals the listed keys on every push to Git, so the repository only ever holds `ENC[AES256_GCM,...]` for them. A push that cannot seal a listed key is refused, not committed. The agent decrypts inside the cluster at deploy time.

**3. Check Git, not the editor**

The Stack Builder shows the value you typed, because sealing happens at the push. To confirm a value is encrypted, open the file in the Git repository.

Put each secret where it belongs:

| Secret | Where it lives |
| - | - |
| The same for every environment | An application secret: `ankra application env-secrets set`, sealed into every deployment |
| Different per cluster, such as a test and a live payment key | A SOPS-encrypted Secret manifest in each cluster's Stack |
| A credential for a database, registry or API the organisation already runs | The existing credential, connected rather than copied. See [Connect to a managed service](/guides/connect-to-a-managed-service) |

Add one line to Claude Code's standing instructions so it never breaks the rule: "Never commit a plaintext secret. Seal sensitive keys with `ankra cluster encrypt`." Rotating the organisation key is not self-service yet; see [Key rotation](/guides/sops#key-rotation).

***

## Day 2

The app is live in two places. Most of day 2 is the same loop you used to build it, with Ankra doing the watching.

### Changing the app

Keep working in Claude Code. Every pull request is built, scanned and reviewed by Ankra AI, and can get its own throwaway preview URL. Previews deploy to the organisation's staging cluster, which an admin sets under **AI** → **Settings** → **Workspaces**; the development cluster works well for it, so no third cluster is needed. See [Pull request preview environments](/guides/pr-preview-environments#prerequisites). When it merges, development redeploys on its own:

```
Add <feature>. Open a pull request, wait for the Ankra pipeline and review,
fix what they find, and tell me the preview URL when it is green.
```

### Promoting and rolling back

Promote the same way every time: the tag that passed in development, to production, by a person. To roll back, deploy the previous tag:

```bash theme={null}
ankra application deployments <application-id>
ankra application deploy <application-id> --cluster <prod-cluster-id> --namespace shop \
  --set image_tag=sha-<previous-tag>
```

The previous tags are listed on the application's **Environments** page. Configuration that differs between environments stays in each environment's deploy options and cluster configuration, so a promotion never carries development settings into production.

### When something breaks

Ask Claude Code to investigate with `/ankra-triage`. It reads logs, events, metrics and Ankra's operation history through the CLI, read-only until it has a diagnosis:

```bash theme={null}
ankra cluster logs <pod> -n shop --cluster <prod-cluster-id>
ankra cluster get events -n shop --cluster <prod-cluster-id>
ankra cluster operations list --cluster <prod-cluster-id>
```

See [Logs](/platform/logs), [Operations](/platform/operations) and [Cluster metrics](/platform/cluster-metrics).

### Keeping both clusters healthy

* **Alerts.** Route pipeline failures, blocked images and cluster events to the channel that owns the app. See [Notification routing](/guides/notification-routing).
* **Backups.** Protect every Stack that holds data, starting with the generated database, so production can be restored. See [Backups and restore points](/guides/backups).
* **Security.** New CVEs land on images that are already running. Work the known-exploited ones first, read the weekly security email, and run `/ankra-harden` now and then for a ranked security pass over the organisation. See [Dealing with CVEs](#dealing-with-cves).
* **Dependencies.** Ask Claude Code to update them in a pull request. The pipeline scans the result before it can publish.
* **Kubernetes upgrades.** Upgrade development first, run the app there, then upgrade production. For clusters Ankra builds, see [Upgrade Kubernetes](/guides/operate-ankra-managed-clusters#upgrade-kubernetes). For cloud-run clusters, see [Managed Kubernetes](/guides/managed-kubernetes#day-2-operations).
* **Platform add-ons.** Change versions in the GitOps repository, let development reconcile first, and promote the same change to production. See [GitOps](/concepts/gitops).

***

## Let Ankra fix and maintain it

Claude Code works in your repository while you are at the keyboard. Ankra's AI agents work in the platform when you are not: on a schedule, when an alert fires, or when a ticket lands on the board. You decide how far each one may go.

### What already runs on its own

Without any setup, Ankra AI fixes a failing setup pull request, investigates every failed build on the tracked branch, and reviews every pull request. These are covered in [What Ankra generates for you](#what-ankra-generates-for-you). Everything below is something you switch on.

### The DevSecOps agent: CVEs to pull requests

The DevSecOps agent, one of the six default agents under **AI** → **Agents**, turns a cluster's security report into fixes:

1. It reads the critical and high findings, known-exploited CVEs first, production clusters before the rest.
2. It maps each vulnerable image to the application or add-on that deployed it.
3. For an application, it bumps the base image or package in the repository and opens **one pull request** listing every CVE it clears. For an add-on, it proposes the chart version that ships the fix, with the current version as the rollback.
4. Once the fix is merged and rebuilt, it re-reads the report and quotes the before-and-after counts.

Its autonomy is **Propose**: the pull request is the review gate, cluster writes wait for your approval, and accepting a risk stays a human decision. It can never delete a resource to make a finding go away. Ask it from the cluster's chat to "clear the critical and high findings", or file a board ticket for it. See [The DevSecOps agent](/platform/ai-agents#the-devsecops-agent).

### Auto-remediation: alerts that fix themselves

Under **AI** → **Settings** → **Autonomy**, the **Auto-Remediation Policy** hands firing alerts to a remediation agent. It is off until an admin turns it on. Choose:

* **The level.** **Observe only** diagnoses and reports. **Propose** sends every corrective action to Slack for approval, and is the default. **Autonomous** runs low-risk reversible actions itself and asks for the rest.
* **The scope.** All clusters, or an allow-list. Start with the development cluster.
* **Per-action rules.** For example, let `restart_deployment` run automatically, make `delete_pod` ask on Slack, and never run anything else.
* **The limits.** A cap on actions per incident and a cooldown before the same alert on the same cluster is picked up again.

See [AI Autonomy](/platform/ai-autonomy).

### Automations: maintenance on a schedule

**AI** → **Automations** is a canvas for workflows with stages. A **trigger** (a schedule, an alert, a webhook or a manual run) starts the workflow. **Agent** steps do the work, **conditions** route on what they found, an **approval** gate pauses for an administrator, and an **output** posts the result. Start from a template: **Nightly cluster fix plans**, **Daily insight digest** or **On alert: diagnose**.

A weekly maintenance workflow for this app could look like:

| Node | Setting |
| - | - |
| Trigger | Schedule, Mondays at 06:00 |
| Agent | "Find known-exploited and critical CVEs and outdated add-on charts on the production cluster. Draft the fixes as pull requests and upgrade proposals." |
| Condition | Continue only if the agent found something to change |
| Approval | An administrator approves before anything is applied |
| Output | Post the summary and the pull request links to the team's channel |

The approval gate is what makes a scheduled workflow safe: the agent prepares the work overnight, and nothing irreversible happens until a person signs off. See [AI Automations](/platform/ai-automations).

### Configure your own agent

When one goal on one trigger is enough, create an agent instead of a workflow:

**1. Create it with the wizard**

**AI** → **Agents** → **New agent** starts a short interview. Give it a role, its focus areas, the clusters it may touch, a communication style and its guardrails, and the wizard writes its persona. For example: a dependency agent scoped to the development and production clusters of this app, told to open pull requests and never touch production directly.

**2. Set how far it may go**

Pick an autonomy level: **Observe** (read-only), **Propose** (suggests, you approve) or **Autonomous** (runs low-risk, reversible actions itself). Set its budgets for tool calls, turns and runtime, its model, and a daily token limit. Start at **Propose**, and raise it only once you have read a few of its runs.

**3. Give it a trigger**

Run it on a schedule, from an alert, from board tickets, or with **Run now**. To have tickets that Ankra files from its own insights worked automatically, designate the agent under **Settings** → **Autonomy** → **Board staffing**.

**4. Watch what it does**

Every dispatch is recorded as a run with a full transcript:

```bash theme={null}
ankra agents runs --status awaiting_user
ankra agents transcript <run-id>
ankra agents cancel <run-id>
```

The **Agents** page sorts agents that need your input to the top, and the sidebar badge counts them.

See [AI Agents](/platform/ai-agents).

### Keep a hand on the switch

Two stops apply to the whole organisation at once. `ankra ai autonomy pause` stops every autonomous action, and the AI keeps diagnosing but changes nothing without approval. `ankra ai autonomy stop-all` is the emergency stop for an incident. `resume` and `start-all` undo them. Whatever the settings, the lines from [Who is responsible for what](#who-is-responsible-for-what) hold: an agent cannot approve its own pipeline or accept a risk on your behalf, and promoting to production stays a decision you keep for people: leave it out of every agent's goals and set agents that can reach production to **Propose**.

***

## Verify

```bash theme={null}
curl -fsS https://shop.example.dev/healthz
curl -fsS https://shop.example.com/healthz
ankra application deployments <application-id>
ankra cluster get pods -n shop --cluster <prod-cluster-id>
```

Both addresses answer, the application has a deployment on each cluster, the **Environments** page shows the same `sha-` tag in development and production after a promotion, and the production pods are running. Then open production in a browser and walk one real journey, such as signing up and signing in. A green deployment is not a working app; the journey is the check.

***

## Next steps

> [card] [Prompt to Production](/use-cases/prompt-to-production)
>
> Plan, storyboard, build and verify a larger app with agents, one stage per session.

> [card] [Applications](/concepts/applications)
>
> How Ankra analyses a repository and what the setup pull request contains.

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> Every stage the generated pipeline runs, and how the gate decides what may publish.

> [card] [Agent Skills](/integrations/agent-skills-catalogue)
>
> Every skill and slash command Claude Code gets from Ankra.


# Lovable to Ankra
Source: https://docs.ankra.ai/use-cases/lovable-to-ankra

Move an app you built in Lovable onto your own Kubernetes cluster with open-source components - add the repository in Ankra's add-application wizard, let Ankra's AI analyse it and open the setup pull request, run the front end from one Dockerfile, and run the backend as Postgres and object storage on your own cluster instead of a hosted service.

Lovable builds the app. Ankra runs it on your cluster, with open-source software you control, behind HTTPS, with every change built and scanned first.

You keep prompting in Lovable. Lovable commits to your GitHub repository, and Ankra builds every commit.

![An app built in Lovable is synced to your GitHub repository. Ankra's add-application wizard analyses it and opens a setup pull request. Ankra builds, scans and deploys it to your cluster, where it runs next to open-source Postgres and object storage that Ankra also runs. A live HTTPS address is printed, and every later edit in Lovable is rebuilt and redeployed.](https://mintcdn.com/ankra/-7zb4asxjhThngoc/images/use-cases/lovable-to-ankra.svg?fit=max\&auto=format\&n=-7zb4asxjhThngoc\&q=85\&s=3886e1805c8c000ce5b6b757988401fb)

From a Lovable repository to your own cluster

***

## What Ankra does for you

Adding an application is a wizard, and the work is done by Ankra's AI, not by you.

| You | Ankra's wizard and AI agent |
| - | - |
| Pick the repository and branch | Reads the repository, detects the framework, and works out what it needs: port, secrets, database |
| Review one pull request | Opens a setup pull request with the Kubernetes manifests, the deploy options (`.ankra/ankra.yaml`) and the build pipeline (`.ankra/pipeline.yaml`) |
| Press Deploy | Builds the image in your cluster, scans it with Semgrep, Checkov and Trivy, applies your image gate, deploys, requests the certificate and prints the live address |
| Approve the plan | If the app needs Postgres, generates a CloudNativePG database in your cluster and wires `DATABASE_URL` to it, so you never copy a password |

You can drive the same flow from chat, which is useful when you want the AI to explain or change the plan before anything is written:

```bash theme={null}
ankra chat "add my repository <owner>/<repo> as an application and show me the setup plan" --mode agent
ankra chat "revise the setup: high availability, 3 replicas" --mode agent
```

Agent mode stops at a confirmation card before every write. See [Applications](/concepts/applications) and [AI Assistant](/platform/ai-assistant).

***

## Chat and deploy from inside Lovable

The Ankra — Chat & Deploy extension for Chrome puts an **Ask Ankra** button on your Lovable project. From that panel you can chat with Ankra AI, connect the project's GitHub repository and deploy it to your cluster, without switching to the portal.

**1. Install and connect**

The Chrome Web Store listing is in review, so for now [install the extension manually](#install-the-extension-without-the-chrome-web-store). Open a project on `lovable.dev` and click **Ask Ankra**. Choose **Connect to Ankra**, sign in, and approve the extension in the browser sign-in screen the CLI also uses. An Ankra API token works too.

**2. Pick where it deploys**

In the panel's settings, choose your organisation, the target cluster and the GitHub credential Ankra should use. Chat needs only the organisation. If your organisation has no usable cluster, **Create demo cluster** requests a temporary [Playground](/platform/billing#playground-environments) and selects it once it is ready.

**3. Connect GitHub and deploy**

Choose **Deploy project**, then **Connect GitHub**. The extension opens Lovable's Git settings and reads the repository and branch from there. If the project is not connected yet, you finish account choice and GitHub authorisation in Lovable. Check the repository and branch, then click **Deploy to Ankra**.

The extension reuses an application with the same repository and branch, or registers a new one, so the first deploy runs the same setup pull request, pipeline and scans described below. If Ankra is not ready yet, for example while the setup pull request or the first build is pending, the request waits and is sent once Ankra accepts it, for up to 24 hours, even if you close the panel.

> [!NOTE]
>
> **Deployment requested** means Ankra accepted the request, not that the app is live. Open the application in Ankra to follow the build and get the address. The extension does not move database contents, Lovable Cloud data or Supabase secrets.

The extension runs only on `lovable.dev` and talks only to `platform.ankra.app`. It reads the project's address and title and the repository and branch Lovable shows in its Git settings, never cookies, passwords or page contents. Your sign-in and recent chats are kept in local extension storage, and **Disconnect** clears them. Chat in the panel uses Ask mode; continue writes that need approval in the portal.

### Install the extension without the Chrome Web Store

The Chrome Web Store listing is in review. Until it is live, load the same package into Chrome yourself:

1. Download [ankra-chrome-extension.zip](https://ankra.ai/downloads/ankra-chrome-extension.zip) and unzip it into a folder you will keep. Chrome loads the extension from that folder, so do not delete it.
2. Open `chrome://extensions` and turn on **Developer mode** in the top-right corner.
3. Choose **Load unpacked** and select the unzipped folder.
4. Reload any open Lovable tab, then click **Ask Ankra**.

A manually loaded extension does not update itself. When the store listing is live, remove this copy from `chrome://extensions` and install the extension from the store to get updates. The same steps work in other Chromium browsers such as Edge and Brave, from that browser's own extensions page.

***

## Add the app with the wizard

**1. Connect Lovable to GitHub**

In Lovable, open the project's GitHub settings and connect a repository. Lovable commits every change to it from then on. This is the only link between the two.

**2. Add the repository in Ankra**

In the portal, open **Applications** and choose **Add application** (**What are you shipping?** in the new portal). Pick your GitHub credential, the repository and the branch Lovable tracks. Ankra analyses it in the background.

Without the portal, from a clone of the repository:

```bash theme={null}
ankra application add . --name shop --branch main --wait
```

**3. Let Ankra write the Dockerfile**

A Lovable project is a Vite single-page app: it builds static files and starts no process. Ankra recognises that shape from `package.json` (Vite, a `build` script, no `start` script) and writes the Dockerfile for it. You add nothing to the repository.

The Dockerfile builds the app with Vite and serves the result from an unprivileged nginx on port 8080, running as a non-root user:

* A refresh on `/dashboard/settings` returns the app instead of a 404, while a missing file under `/assets/` is still a 404.
* Hashed assets are cached for a year and `index.html` never is, so a new release is picked up on the next load.
* `/healthz` answers without touching anything, so the cluster has something to probe.

**4. Review the setup pull request and ship**

Read the pull request Ankra opened: the Dockerfile, the manifests, the deploy options and the pipeline. It is a proposal, and builds run from the next push whether or not you merge it. Then deploy from the wizard, or in one command:

```bash theme={null}
ankra application ship . --cluster <cluster-id>
```

Ankra waits for the build, deploys, waits until the pods run and prints:

```
Live: https://<app>.<cluster-domain>
```

> [!NOTE]
>
> The first pipeline definition needs a person to approve it once. If the build stops with a refused step, run `ankra pipeline get --application shop --latest`, which prints the exact approve command, and run it as yourself.

***

## Run the backend on your cluster

A Lovable app is a front end plus a backend, and the backend is usually a hosted service. On Ankra the backend is open-source software on your own cluster, run by Ankra.

**What Ankra runs for you today**

| Need | Open-source component | How you get it |
| - | - | - |
| Relational database | PostgreSQL, run by the CloudNativePG operator | The wizard generates it when the app needs Postgres and wires `DATABASE_URL`. Or add it as a [managed service](/guides/set-up-a-managed-service) |
| File storage (S3 API) | SeaweedFS | [Managed service](/guides/set-up-a-managed-service) |
| Cache | Valkey | [Managed service](/guides/set-up-a-managed-service) |
| Queue | NATS with JetStream | [Managed service](/guides/set-up-a-managed-service) |
| Search | OpenSearch | [Managed service](/guides/set-up-a-managed-service) |

The database is a Kubernetes resource in your repository, so it is reviewed in the same pull request as the app, sized by the deploy mode (one instance for quick, three for high availability), and protected like any other data with [backups and restore points](/guides/backups). Managed services are in closed beta and enabled per organisation; [contact support](/platform/support) to turn them on.

### The part to be honest about: the data layer

Lovable generates apps that talk to **Supabase** with `supabase-js`: sign-in, tables, storage and functions all go through Supabase's own API. Ankra does not recognise Supabase, and its wizard does not rewrite application code, so a repository that calls Supabase keeps calling Supabase unless the data layer changes. There are two ways to get fully onto your cluster:

1. **Replace the data layer in the code.** Move tables to the Postgres Ankra generated, files to the S3 service, and sign-in to an open-source identity provider such as [Ory Kratos](/use-cases/production-multi-cluster-platform#step-6-infrastructure-cluster-a-staff-sign-in-realm-with-kratos-and-hydra), Keycloak or authentik. This is a code change, and it is the right job for an AI coding assistant working in the repository, with the Ankra skills installed so it knows where the pieces live:

   ```
   Replace Supabase in this app with the open-source stack on my Ankra cluster.
   Use the Postgres the setup PR generated (DATABASE_URL), keep schema changes in
   versioned migrations, and put files in the S3 service. Show me the plan and the
   diff before you commit.
   ```

2. **Run Supabase's open-source stack on your cluster.** Supabase is open source and can be self-hosted, which keeps the app's code unchanged because only its address changes. Ankra can convert a Supabase self-host Docker Compose file with [`ankra migrate`](/guides/migrate-from-docker) and restore its Postgres through a backup vault, but there is no one-step Supabase package yet, and the compose file's mounted configuration needs care. Treat this as an advanced route.

> [!WARNING]
>
> Whichever you choose, never ship the Supabase **service role** key in the repository or in any `VITE_` variable, and review Row Level Security or its replacement before real users arrive. Do not switch the data layer in production first: prove it in development.

***

## Use your own domain

Add two options to the deploy:

```bash theme={null}
ankra application ship . --cluster <cluster-id> \
  --set ingress_enabled=true \
  --set ingress_host=app.example.com
```

Ankra's DNS automation covers the generated subdomain. For a zone of your own, store a DNS credential and serve the zone from the cluster once:

```bash theme={null}
ankra org dns credentials create --name example-dns
ankra cluster custom-dns-zones add <cluster> --zone example.com --credential example-dns
```

If the name points at Lovable's hosting today, remove it there first. See [Domains and DNS](/guides/avura-domains).

***

## Development, then production

Add a second cluster so each change is proved before production sees it. An application deploys to as many environments as you give it, and each environment is a cluster and namespace with its own database and secrets.

![An app built in Lovable is committed to GitHub. An Ankra pipeline tests, builds, scans and gates it and publishes an immutable tag. The tag is deployed to a development cluster and proved there, then promoted unchanged to a production cluster. Each environment talks to its own backend, and one image serves both because the backend address is injected when the container starts.](https://mintcdn.com/ankra/-7zb4asxjhThngoc/images/use-cases/lovable-to-ankra-environments.svg?fit=max\&auto=format\&n=-7zb4asxjhThngoc\&q=85\&s=8f050ba2316cfd9a554eeaa5bb814db1)

One image, two environments: the backend address is injected when the container starts

**1. Deploy to development**

```bash theme={null}
ankra application ship . --cluster <dev-cluster-id> --namespace shop-dev \
  --set ingress_enabled=true --set ingress_host=app.example.dev
```

Each environment gets its own database, so development data never reaches production.

**2. Promote the tag that passed**

In the portal, open the application's **Settings** → **Push to deploy**. Under **What follows pushes**, leave development on and turn production off, so production never follows a push. Then promote the exact tag you tested. Promotion moves the image tag only: never a rebuild, never configuration.

```bash theme={null}
ankra application deploy <application-id> --cluster <prod-cluster-id> --namespace shop \
  --set image_tag=sha-<the-tag-that-passed> \
  --set replicas=2 --mode high_availability \
  --set ingress_enabled=true --set ingress_host=app.example.com
```

You can also promote from the application's **Environments** page in the portal, or from chat with `promote_application`. To roll back, deploy an earlier tag the same way.

Anything that differs per environment and is baked into a Vite build, such as a public API address, can be filled in when the container starts instead of at build time:

> [accordion] Dockerfile that reads its backend address at start
>
> ```dockerfile theme={null}
> # Dockerfile
> FROM node:22-alpine AS build
> WORKDIR /app
> COPY package.json package-lock.json* ./
> RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
> COPY . .
> ARG VITE_SUPABASE_URL=__SUPABASE_URL__
> ARG VITE_SUPABASE_PUBLISHABLE_KEY=__SUPABASE_PUBLISHABLE_KEY__
> ENV VITE_SUPABASE_URL=$VITE_SUPABASE_URL \
>     VITE_SUPABASE_PUBLISHABLE_KEY=$VITE_SUPABASE_PUBLISHABLE_KEY
> RUN npm run build
>
> FROM nginxinc/nginx-unprivileged:1.27-alpine
> COPY --from=build /app/dist /usr/share/nginx/html
> COPY <<'EOF' /etc/nginx/conf.d/default.conf
> server {
>   listen 8080;
>   root /tmp/site;
>   location = /healthz { return 200 "ok\n"; }
>   location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; try_files $uri =404; }
>   location / { add_header Cache-Control "no-cache"; try_files $uri /index.html; }
> }
> EOF
> COPY --chmod=755 <<'EOF' /docker-entrypoint.d/40-runtime-config.sh
> #!/bin/sh
> set -eu
> rm -rf /tmp/site && mkdir -p /tmp/site && cp -R /usr/share/nginx/html/. /tmp/site/
> swap() {
>   value="$(printenv "$1" || true)"
>   [ -n "$value" ] || { echo "runtime-config: $1 is not set" >&2; exit 1; }
>   escaped="$(printf '%s' "$value" | sed -e 's/[\\&|]/\\&/g')"
>   find /tmp/site -type f \( -name '*.js' -o -name '*.html' \) -exec sed -i "s|$2|$escaped|g" {} +
> }
> swap SUPABASE_URL __SUPABASE_URL__
> swap SUPABASE_PUBLISHABLE_KEY __SUPABASE_PUBLISHABLE_KEY__
> EOF
> EXPOSE 8080
> ```
>
> The same image serves any backend whose address you pass as `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` (the names follow Lovable's; rename them to match your `.env`), including a self-hosted one. Give each environment its values with an environment secret, which is stored per application, sealed into the workloads and rolled on apply:
>
> ```bash theme={null}
> printf '%s' "$BACKEND_URL" | ankra application env-secrets set <application-id> SUPABASE_URL
> printf '%s' "$BACKEND_KEY" | ankra application env-secrets set <application-id> SUPABASE_PUBLISHABLE_KEY
> ankra application env-secrets apply <application-id>
> ```
>
> Variables in the environment take priority over the `.env` Lovable commits, so the committed address never reaches the bundle. A container started without a variable exits at once and names it.

***

## What you get without asking

* **Scans on every change.** Semgrep over the source, Checkov over the manifests and Trivy over the image, judged against your organisation's gate before anything is published. A generated app is mostly code you did not write, so this is where an unsafe pattern or a leaked key shows up.
* **An immutable tag per commit.** Every deployment is a `sha-` tag.
* **Tests when you add them.** The pipeline has a test stage only when `package.json` has a `test` script, and Lovable projects usually have none.
* **An AI review and a watcher.** Ankra reads every pull request, watches every run, and opens a fix when a build breaks.
* **Pull request previews.** A live preview of each branch, with its own throwaway Postgres if you ask for one. See [Pull request preview environments](/guides/pr-preview-environments).

***

## Verify

```bash theme={null}
curl -fsS https://app.example.com/healthz
ankra application deployments <application-id>
ankra cluster get pods -n shop --cluster <cluster-id>
ankra pipeline findings <run-id> --application shop
```

Then open the address, reload a nested page, and sign up and sign in once. A green deployment is not a working app; the sign-in is the check.

***

## Troubleshooting

> [accordion] Ankra says it wrote no Dockerfile, or the build cannot find the app
>
> Ankra writes the Dockerfile for a Vite app that builds static files and names no server of its own. If `package.json` has a `start` script or a `main` file, or a `server.js` sits beside the app, Ankra treats the repository as a Node server instead. If `vite.config` moves the build output out of `dist/`, the generated image cannot find it. In either case add your own `Dockerfile` at the repository root and commit it to the branch Lovable tracks: Ankra builds whatever Dockerfile it finds and never overwrites it.

> [accordion] The page loads but refreshing a nested route shows a 404
>
> The `try_files $uri /index.html;` line is missing from the nginx config, or the config was not copied into the image.

> [accordion] Sign-in redirects to localhost or the old address
>
> The identity provider's allowed redirect list does not include the new address. Add it for each environment.

> [accordion] The app still talks to the hosted Supabase
>
> The code still calls Supabase, which Ankra does not rewrite. Change the data layer as described above, or inject a self-hosted backend's address.

> [accordion] The build stops at the image gate
>
> A scanner found something above your threshold. `ankra pipeline findings <run-id> --application shop` lists it, worst first. Fix it, or accept it deliberately and write down why.

> [accordion] The pod restarts and its log says a variable is not set
>
> Only the runtime-config Dockerfile does this, on purpose. Set the environment secret and run `ankra application env-secrets apply <application-id>`.

> [accordion] My own domain shows no certificate or does not resolve
>
> The zone was not declared for that cluster. Run `ankra cluster custom-dns-zones list <cluster>` and add it with its credential.

***

## Next steps

> [card] [Applications](/concepts/applications)
>
> How Ankra analyses a repository, what the setup pull request contains and how deployments work.

> [card] [Managed services](/concepts/managed-services)
>
> PostgreSQL, Valkey, NATS, OpenSearch and S3-compatible storage, run on your cluster.

> [card] [Backups and restore points](/guides/backups)
>
> Protect the database and the files the app depends on.

> [card] [Prompt to Production](/use-cases/prompt-to-production)
>
> The same development-then-production discipline for apps you build from a written plan.


# Production Multi-Cluster Platform
Source: https://docs.ankra.ai/use-cases/production-multi-cluster-platform

Build a hub-and-spoke estate on Ankra - one infrastructure cluster that holds central Prometheus, Grafana, Tempo, OpenSearch, Harbor, uptime monitoring and a staff single sign-on realm on Ory Kratos and Hydra, with production and development clusters that ship their metrics and logs to it, backed up on a schedule and alerting to your on-call channel.

This use case is the shape of a real estate Ankra operates: one **infrastructure cluster** that every other cluster leans on, and a **production** and a **development** cluster that run the applications. Everything lives in one GitOps repository, every secret is sealed with SOPS, every stateful stack is protected into a backup vault, and every alert reaches one on-call channel.

It is long because it is complete. Each step is one stack in one cluster file, so you can take the parts you need and leave the rest.

> [!NOTE]
>
> **Start small.** You do not need all of it on day one. The three pieces that pay back first are central metrics and alerts (Step 4), scheduled backups for every stack that holds data (Step 9), and one place to sign in (Step 6). Build the hub with Steps 1 to 4, add one spoke, and grow from there. If you only want one app running, [Ship your app](/guides/deliver-your-app) is shorter.

***

## Build it with your AI coding assistant

This guide is written so an assistant that has the Ankra CLI and Ankra's agent skills can carry it out for you, one step at a time, while you review. The example below uses Claude Code; the same steps work for Cursor, Codex, Copilot, Windsurf and Gemini CLI, see [Agent Skills](/integrations/agent-skills).

**1. Install the CLI and sign in**

```bash theme={null}
brew install ankraio/tap/ankra
ankra login
ankra org list
```

Pick the organisation the clusters will live in. The [CLI page](/integrations/ankra-cli) has the installer for machines without Homebrew.

**2. Give the assistant the Ankra skills**

```bash theme={null}
ankra skills install --client claude-code --with-hooks
```

This installs the `ankra-*` skills - platform principles, cloud clusters, stacks and add-ons, SOPS, backups, alerts, observability, domains and DNS, security - so the assistant knows the CLI, the YAML shapes and the order of operations in this guide. The hook pauses it before destructive commands and keeps it on `ankra` instead of `kubectl` or `helm`.

**3. Hand it this page**

Start the assistant in the GitOps repository and give it the page and your inputs. A prompt that works:

```
Read https://docs.ankra.ai/use-cases/production-multi-cluster-platform and build it for my organisation with the Ankra CLI.

- Provider: UpCloud, zone fi-hel1, credentials upcloud-main and platform-ssh
- Domain: example.com, DNS credential example-dns
- Staff sign-in: Microsoft 365, tenant <entra-tenant-id>
- On-call: a Microsoft Teams webhook, I will paste it when you ask
- Repository: my-org/platform-gitops, credential github-platform

Work one step of the guide at a time, in order. Write every stack to the
cluster files, validate with `ankra cluster validate`, stage with
`ankra cluster draft`, and stop for my review before anything is applied.
Seal every secret with `ankra cluster encrypt` before you commit. Never use
kubectl or helm.
```

Smaller asks work too: "Do Step 4 only, the central metrics stack" or "Protect every stack with data on the production cluster into production-backups".

**4. Review, then let it continue**

Each step ends with something you can check: a draft to open in the portal, an `ankra cluster operations list` that reads `up`, a `curl` that returns the right status. Approve the draft, tell the assistant to go on, and finish with the [Verify](#verify) list at the end of this page.

Two things it must never do on its own, and the skills tell it so: apply to the production cluster without a draft you have seen, and commit a secret in plaintext.

***

![The production and development clusters send metrics by remote\_write and logs by \_bulk into the infrastructure cluster's ingest endpoints and restore points into a backup vault per environment. Inside the infrastructure cluster, Prometheus with Alertmanager and OpenSearch with Dashboards receive the data, Grafana reads Prometheus and Tempo, Harbor and OneUptime sit beside them, and a staff sign-in realm on Kratos, Hydra and oauth2-proxy signs people into all four tools. Alertmanager and Ankra notifications deliver to one on-call channel.](https://mintcdn.com/ankra/8M27IQBtyHQrd0pj/images/use-cases/production-multi-cluster-platform.svg?fit=max\&auto=format\&n=8M27IQBtyHQrd0pj\&q=85\&s=dacf84f17826aed17186ca52a3b02a66)

Hub and spokes: the infrastructure cluster receives, the application clusters send

***

## What you build

| Where | Stack | What it carries |
| - | - | - |
| Organisation | DNS zone, alert destination and routes, backup vaults, Helm registries | Shared by every cluster, including ones created later |
| Infrastructure | `networking` | Traefik, cert-manager, external-dns and a Let's Encrypt ClusterIssuer - installed by Ankra at create time |
| Infrastructure | `storage` | A `Retain` StorageClass and VolumeSnapshotClass so a deleted stack never takes its disks with it |
| Infrastructure | `infra-secrets` | Every pre-created Secret the other stacks read, sealed with SOPS |
| Infrastructure | `monitoring` | kube-prometheus-stack with a remote-write receiver, Alertmanager to your chat channel, Grafana with multi-cluster dashboards, Tempo for traces, and the `metrics-ingest` endpoint the spokes write to |
| Infrastructure | `logs` | OpenSearch operator, a three-node OpenSearch cluster with Dashboards, retention policies, per-cluster shipper users, and the `logs-ingest` endpoint the spokes write to |
| Infrastructure | `sso-gateway` | Ory Kratos and Hydra as a staff identity realm pinned to your Microsoft 365 tenant, and oauth2-proxy as a forward-auth gate any Ingress can opt into |
| Infrastructure | `registry` | Harbor on CloudNativePG and Redis, signed in through the staff realm |
| Infrastructure | `uptime` | OneUptime for external probes, incidents and status pages, behind the gate |
| Production and development | `metrics-agent` | Prometheus in agent mode, remote-writing every series to the hub with a `cluster` label |
| Production and development | `log-shipping` | Fluent Bit reading the application namespaces and shipping to the hub with a per-cluster user |
| Production and development | `ankra-security-baseline` | Trivy Operator and Pod Security Standards - installed by Ankra at create time |
| Production and development | application stacks | Your workloads, CloudNativePG databases, protected into the environment's vault |

> [!NOTE]
>
> Nothing here is specific to one cloud. The example creates the clusters on UpCloud because that is where this layout runs today; swap the `create` command for [Hetzner](/guides/hetzner-clusters), [Scaleway](/guides/scaleway-clusters) or any other [Ankra Managed](/guides/operate-ankra-managed-clusters) provider and the stacks are unchanged, apart from the storage class names.

***

## Prerequisites

* An Ankra organisation where you are an admin, and the [CLI](/integrations/ankra-cli) logged in.
* A cloud credential and an SSH key credential for the provider you build on ([UpCloud credentials](/platform/credentials/upcloud)).
* A Git credential with write access to the GitOps repository ([Git credentials](/platform/credentials/git)).
* A domain you control, for example `example.com`, and a DNS credential Ankra can publish records with (`ankra org dns credentials create` stores an external-dns webhook credential for any provider - see [serving a zone in your own DNS account](/concepts/applications#serving-a-zone-in-your-own-dns-account-from-every-cluster); a domain held in Avura follows [the Avura route](/guides/avura-domains) instead).
* A Microsoft 365 (Entra ID) tenant for staff sign-in. Any OpenID Connect provider Kratos supports works the same way.
* A Microsoft Teams or Slack webhook for the on-call channel.
* The charts come from registries Ankra already ships in its [catalogue](/platform/addon-catalog) for every organisation: `prometheus-community`, `grafana`, `opensearch-k8s-operator`, `fluent`, `oauth2-proxy`, `cloudnative-pg`, `harbor` and `oneuptime`. The one exception is Ory's chart repository for Kratos and Hydra, connected once:

```bash theme={null}
ankra helm registries create --name ory --url https://k8s.ory.sh/helm/charts
```

> [!TIP]
>
> Write the cluster files by hand in the layout below and apply them with `ankra cluster apply`, or build the stacks in the portal and let Ankra write them to Git. Both end in the same repository. This page shows the files, because they are what you review, diff and roll back.

***

## Step 1: Create the clusters

Three clusters, created with the GitOps flags so Ankra commits their generated stacks to your repository from the first minute. Choose the control plane count for what each cluster must survive: three for anything that must survive losing a node. You can change it later with `ankra cluster <provider> control-plane set-count`; see [Control plane](/guides/operate-ankra-managed-clusters#control-plane).

**1. Store the credentials**

```bash theme={null}
ankra credentials upcloud create --name upcloud-main          # prompts for the token
ankra credentials ssh-key create --name platform-ssh --generate --private-key-file ./platform-ssh.pem
```

**2. Create the infrastructure cluster**

Three control planes, three workers. The OpenSearch nodes, Prometheus and Harbor all want memory, so size the workers for them.

```bash theme={null}
ankra cluster upcloud create \
  --name infrastructure \
  --credential-id <upcloud-credential-id> \
  --ssh-key-credential-id <ssh-key-credential-id> \
  --zone fi-hel1 \
  --control-plane-count 3 \
  --control-plane-plan 2xCPU-4GB \
  --worker-count 3 \
  --worker-plan 4xCPU-16GB \
  --bastion-allowed-ips <office-ip>/32 \
  --gitops-repository my-org/platform-gitops \
  --gitops-credential-name github-platform \
  --gitops-branch main
```

`--include-networking` and `--include-dns` are on by default: the cluster arrives with Traefik behind a cloud load balancer, cert-manager, a `letsencrypt-prod` ClusterIssuer and external-dns for its generated subdomain under `ankra.cc`.

**3. Create the production cluster**

Same shape, sized for the applications. Keep the control plane at three.

```bash theme={null}
ankra cluster upcloud create \
  --name production \
  --credential-id <upcloud-credential-id> \
  --ssh-key-credential-id <ssh-key-credential-id> \
  --zone fi-hel1 \
  --control-plane-count 3 \
  --control-plane-plan 2xCPU-4GB \
  --worker-count 3 \
  --worker-plan 4xCPU-8GB \
  --bastion-allowed-ips <office-ip>/32 \
  --gitops-repository my-org/platform-gitops \
  --gitops-credential-name github-platform \
  --gitops-branch main
```

**4. Create the development cluster**

One control plane is fine here: losing it loses nothing you cannot rebuild from Git.

```bash theme={null}
ankra cluster upcloud create \
  --name development \
  --credential-id <upcloud-credential-id> \
  --ssh-key-credential-id <ssh-key-credential-id> \
  --zone fi-hel1 \
  --control-plane-count 1 \
  --worker-count 2 \
  --worker-plan 4xCPU-8GB \
  --gitops-repository my-org/platform-gitops \
  --gitops-credential-name github-platform \
  --gitops-branch main
```

**5. Wait for online, then look at the repository**

`create` submits and returns. Watch the cluster list until all three read **online**, then pull the repository. Ankra has written one directory per cluster:

```
platform-gitops/
  clusters/
    infrastructure-<short-id>/
      infrastructure.yaml          # the ImportCluster definition
      .ankra-owned.json            # what Ankra last wrote - never edit or delete
      .sops.yaml                   # the AGE rule for this directory
      stacks/
        networking/
          add-ons/traefik/values.yaml
          add-ons/cert-manager/values.yaml
          manifests/letsencrypt-prod.yaml
          manifests/external-dns.yaml
        ankra-security-baseline/
        upcloud-cloud-provider/
    production-<short-id>/
    development-<short-id>/
```

Every stack you add below is another entry under `spec.stacks` in that cluster's YAML, with its values and manifests next to it. See [GitOps](/concepts/gitops) for how Ankra and your commits share the directory.

> [!WARNING]
>
> The CNI, the etcd topology and the network mode are fixed at creation. Everything else - the control plane count, node groups, plans, Kubernetes version, autoscaling - changes later. See [Choices fixed at create time](/guides/operate-ankra-managed-clusters#choices-fixed-at-create-time).

***

## Step 2: Organisation-wide DNS, alerting and vaults

These are declared once and inherited by every cluster, including clusters you create next year.

**1. Serve your own zone from every cluster**

The external-dns Ankra installs publishes only under the generated `ankra.cc` subdomain. For `example.com`, store a DNS credential and declare the zone for the organisation. Ankra renders a second external-dns per cluster, scoped to exactly that zone, with its own record ownership.

```bash theme={null}
ankra org dns credentials create --name example-dns \
  --webhook-provider-url '<external-dns-webhook-url-with-token>'
ankra org custom-dns-zones add --zone example.com --credential example-dns
ankra org custom-dns-zones list
```

From here on, an Ingress with `external-dns.alpha.kubernetes.io/hostname: metrics.example.com` gets its record, and `cert-manager.io/cluster-issuer: letsencrypt-prod` gets its certificate.

**2. One destination, two routes**

Ankra's own notifications - a failed deployment, a cluster whose agent went offline, a GitOps sync that stopped, new severe CVEs - go to the same channel as Alertmanager will.

```bash theme={null}
ankra alerts destinations create --name ops-teams --type teams --url https://<your-teams-workflow-webhook>
ankra alerts destinations test <destination-id>

# critical first, and stop there
ankra alerts routes create --destination-id <destination-id> --severity critical --priority 10 --stop-on-match
# everything else that is not noise
ankra alerts routes create --destination-id <destination-id> \
  --kinds execution_failed,resource_deployment_failed,resource_health_degraded,gitops_sync_failed,agent_offline,security_new_severe_cves
```

`ankra alerts routes preview --kind gitops_sync_failed --severity warning --cluster-id <cluster-id>` shows which destinations a notification would reach before one happens. [Notification routing](/guides/notification-routing) explains the evaluation order.

**3. One backup vault per environment**

A vault is an S3-compatible bucket Ankra verifies and keeps the keys for. Let Ankra create the buckets on the same provider credential; keep production and development apart so a retention mistake in one cannot touch the other.

```bash theme={null}
ankra backup vaults provision production-backups --credential upcloud-main --region europe-1 --wait
ankra backup vaults provision development-backups --credential upcloud-main --region europe-1 --wait
ankra backup vaults list
```

Both should read **ready**. Nothing is backed up yet; Step 9 attaches stacks to them.

***

## Step 3: Infrastructure cluster - storage and secrets

Two small stacks that everything else depends on. They go into `clusters/infrastructure-<short-id>/infrastructure.yaml` under `spec.stacks`.

**1. A storage class that keeps its disks**

The provider's default StorageClass reclaims a volume the moment its claim is deleted. Prometheus, OpenSearch, Harbor and the identity database all get a class with `reclaimPolicy: Retain`, and a snapshot class the backup data plane can use.

```yaml theme={null}
# stacks/storage/manifests/retain-storageclass.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: block-storage-retain
provisioner: storage.csi.upcloud.com
parameters:
  tier: maxiops
reclaimPolicy: Retain
allowVolumeExpansion: true
volumeBindingMode: Immediate
```

```yaml theme={null}
# stacks/storage/manifests/retain-volumesnapshotclass.yaml
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: block-storage-snapshot-retain
driver: storage.csi.upcloud.com
deletionPolicy: Retain
```

```yaml theme={null}
stacks:
  - name: storage
    manifests:
      - name: retain-storageclass
        from_file: stacks/storage/manifests/retain-storageclass.yaml
      - name: retain-volumesnapshotclass
        from_file: stacks/storage/manifests/retain-volumesnapshotclass.yaml
```

On another provider, change `provisioner`, `driver` and `parameters` to that CSI driver's values.

**2. Pre-created Secrets, sealed**

The passwords Grafana, OpenSearch, the log shippers and Harbor read are created in one stack that the consumers list as a parent, so a Secret always exists before the chart that mounts it. Write them in plaintext, then seal them before committing.

```yaml theme={null}
# stacks/infra-secrets/manifests/grafana-admin.yaml
apiVersion: v1
kind: Secret
metadata:
  name: grafana-admin
  namespace: grafana
type: Opaque
stringData:
  admin-user: admin
  admin-password: <generate-a-long-random-value>
```

```yaml theme={null}
stacks:
  - name: infra-secrets
    manifests:
      - name: grafana-namespace
        from_file: stacks/infra-secrets/manifests/grafana-namespace.yaml
      - name: grafana-admin
        from_file: stacks/infra-secrets/manifests/grafana-admin.yaml
        parents:
          - kind: manifest
            name: grafana-namespace
        encrypted_paths:
          - admin-password
      - name: opensearch-admin
        from_file: stacks/infra-secrets/manifests/opensearch-admin.yaml
        encrypted_paths:
          - password
      - name: opensearch-log-shipper-production
        from_file: stacks/infra-secrets/manifests/opensearch-log-shipper-production.yaml
        encrypted_paths:
          - password
      - name: opensearch-log-shipper-development
        from_file: stacks/infra-secrets/manifests/opensearch-log-shipper-development.yaml
        encrypted_paths:
          - password
```

Seal every Secret in file mode before the commit; the CLI rewrites the file in place and verifies each listed value is `ENC[...]`:

```bash theme={null}
ankra cluster encrypt manifest grafana-admin --all-data -f clusters/infrastructure-<short-id>/infrastructure.yaml
ankra cluster encrypt manifest opensearch-admin --all-data -f clusters/infrastructure-<short-id>/infrastructure.yaml
```

`--all-data` seals every key under `data` and `stringData` of a Secret. For a value inside Helm values, `ankra cluster encrypt addon <name> --key <key> -f <cluster.yaml>` does the same. [SOPS Encryption](/guides/sops) covers rotation and glob keys.

> [!WARNING]
>
> Ankra identifies a manifest by its `name`. Renaming the manifest that holds a namespace, a PersistentVolumeClaim or a database deletes those objects and creates new ones. Keep the names of stateful manifests fixed from the first commit. See [Protect Persistent Data](/guides/protect-persistent-data).

***

## Step 4: Infrastructure cluster - central metrics with Prometheus, Grafana and Tempo

One Prometheus holds every cluster's series. The hub scrapes itself; the spokes remote-write into it through a public endpoint that accepts exactly one path from exactly their addresses. Grafana queries only this Prometheus, so a dashboard with a `cluster` drop-down shows the whole estate.

**1. kube-prometheus-stack as the receiver**

```yaml theme={null}
# stacks/monitoring/add-ons/kube-prometheus-stack/values.yaml
nameOverride: prometheus-stack
crds:
  enabled: false              # the prometheus-operator-crds add-on owns them
grafana:
  enabled: false              # Grafana is its own add-on below
  forceDeployDashboards: true # ... but the mixin dashboards still render, into its namespace
  namespaceOverride: grafana
  sidecar:
    dashboards:
      multicluster:
        global:
          enabled: true       # every dashboard gets the cluster drop-down
kubeControllerManager:
  enabled: false
kubeScheduler:
  enabled: false
kubeEtcd:
  enabled: false
kubeProxy:
  enabled: false
defaultRules:
  rules:
    kubeProxy: false
prometheus:
  prometheusSpec:
    enableRemoteWriteReceiver: true
    retention: 30d
    retentionSize: 180GB
    scrapeClasses:
      - name: default
        default: true
        relabelings:
          - action: replace
            targetLabel: cluster
            replacement: infrastructure
    ruleSelectorNilUsesHelmValues: false
    serviceMonitorSelectorNilUsesHelmValues: false
    podMonitorSelectorNilUsesHelmValues: false
    probeSelectorNilUsesHelmValues: false
    storageSpec:
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          storageClassName: block-storage-retain
          resources:
            requests:
              storage: 200Gi
    resources:
      requests:
        cpu: 250m
        memory: 3Gi
      limits:
        memory: 6Gi
alertmanager:
  alertmanagerSpec:
    storage:
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          storageClassName: block-storage-retain
          resources:
            requests:
              storage: 5Gi
  config:
    route:
      receiver: teams
      group_by:
        - alertname
        - namespace
        - cluster
      group_wait: 30s
      group_interval: 5m
      repeat_interval: 4h
      routes:
        - receiver: 'null'
          matchers:
            - alertname = "Watchdog"
        - receiver: teams
          continue: true
          matchers:
            - severity =~ "critical|warning"
    receivers:
      - name: 'null'
      - name: teams
        msteamsv2_configs:
          - webhook_url: https://<your-teams-workflow-webhook>
            send_resolved: true
prometheus-node-exporter:
  priorityClassName: system-node-critical
```

Three lines do the multi-cluster work. `enableRemoteWriteReceiver` opens `/api/v1/write`. The default `scrapeClass` stamps `cluster=infrastructure` on the hub's own scrapes so they sit next to the spokes' series, which carry their own `cluster` external label. `group_by` includes `cluster` so one noisy spoke does not fold into another's alert. Every rule in this Prometheus now evaluates the spokes' series too, so their alerts reach the channel without any Alertmanager on the spokes.

Seal the webhook before committing: `ankra cluster encrypt addon kube-prometheus-stack --key webhook_url -f <cluster.yaml>`. Alertmanager is the one place a Slack receiver is `slack_configs` with `api_url` instead; everything else is identical.

**2. Grafana with Prometheus and Tempo data sources**

Grafana is a separate add-on so it can be upgraded, restarted and gated independently of Prometheus. The sign-in block refers to the gate from Step 6; leave `auth.proxy` out until that stack exists, and the local admin from `grafana-admin` is the only account.

```yaml theme={null}
# stacks/monitoring/add-ons/grafana/values.yaml
replicaCount: 1
deploymentStrategy:
  type: Recreate
persistence:
  enabled: true
  size: 5Gi
  storageClassName: block-storage-retain
admin:
  existingSecret: grafana-admin
sidecar:
  dashboards:
    enabled: true
datasources:
  datasources.yaml:
    apiVersion: 1
    datasources:
      - name: Prometheus
        type: prometheus
        uid: prometheus
        isDefault: true
        url: http://kube-prometheus-stack-prometheus.prometheus-stack.svc.cluster.local:9090
      - name: Tempo
        type: tempo
        uid: tempo
        url: http://tempo.tempo.svc.cluster.local:3200
        jsonData:
          tracesToMetrics:
            datasourceUid: prometheus
          serviceMap:
            datasourceUid: prometheus
          nodeGraph:
            enabled: true
grafana.ini:
  server:
    root_url: https://metrics.example.com
  analytics:
    reporting_enabled: false
    check_for_updates: false
  auth:
    signout_redirect_url: https://oauth.example.com/oauth2/sign_out
  auth.proxy:
    enabled: true
    header_name: X-Auth-Request-Email
    header_property: email
    auto_sign_up: true
    sync_ttl: 60
    enable_login_token: false
    whitelist: 10.244.0.0/16        # the pod network: only Traefik may present the header
ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    external-dns.alpha.kubernetes.io/hostname: metrics.example.com
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
    traefik.ingress.kubernetes.io/router.middlewares: sso-gateway-sso@kubernetescrd
  hosts:
    - metrics.example.com
  tls:
    - secretName: grafana-tls
      hosts:
        - metrics.example.com
```

**3. Tempo for traces**

Tempo's metrics generator writes service-graph and span metrics back into the same Prometheus, which is what makes the Grafana service map work across clusters.

```yaml theme={null}
# stacks/monitoring/add-ons/tempo/values.yaml
fullnameOverride: tempo
tempo:
  reportingEnabled: false
  metricsGenerator:
    enabled: true
    remoteWriteUrl: http://kube-prometheus-stack-prometheus.prometheus-stack.svc.cluster.local:9090/api/v1/write
persistence:
  enabled: true
  size: 50Gi
  storageClassName: block-storage-retain
```

Applications send OTLP to `tempo.tempo.svc.cluster.local:4317` from inside the hub, or through an Ingress on `traces-ingest.example.com` built the same way as the metrics endpoint below.

**4. The metrics-ingest endpoint**

This is the only way into the hub's Prometheus from outside the cluster: one exact path, TLS from Let's Encrypt, and an IP allow-list of the spokes' egress addresses. No credential is needed because the endpoint can only append samples, never read them.

```yaml theme={null}
# stacks/monitoring/manifests/metrics-ingest.yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: metrics-ingest-allowlist
  namespace: prometheus-stack
spec:
  ipAllowList:
    sourceRange:
      - <production-egress-ip>/32
      - <development-egress-ip>/32
```

```yaml theme={null}
# stacks/monitoring/manifests/metrics-ingest.yaml (continued)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: metrics-ingest
  namespace: prometheus-stack
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    external-dns.alpha.kubernetes.io/hostname: metrics-ingest.example.com
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
    traefik.ingress.kubernetes.io/router.middlewares: prometheus-stack-metrics-ingest-allowlist@kubernetescrd
spec:
  ingressClassName: traefik
  rules:
    - host: metrics-ingest.example.com
      http:
        paths:
          - path: /api/v1/write
            pathType: Exact
            backend:
              service:
                name: kube-prometheus-stack-prometheus
                port:
                  number: 9090
  tls:
    - hosts:
        - metrics-ingest.example.com
      secretName: metrics-ingest-tls
```

The allow-list only works if Traefik sees the real client address. The networking stack Ankra generates on UpCloud already trusts PROXY protocol v2 from the load balancer (`ports.websecure.proxyProtocol.trustedIPs`); on a provider whose load balancer passes `X-Forwarded-For` instead, the equivalent is `forwardedHeaders.trustedIPs`.

A spoke's egress address is its NAT gateway. Read it from inside the spoke with `ankra cluster exec <any-pod> -n <namespace> -- curl -s https://ifconfig.me`, and expect to update the list when a cluster's network is recreated.

**5. Declare the stack**

```yaml theme={null}
stacks:
  - name: monitoring
    description: Central Prometheus, Alertmanager, Grafana and Tempo for every cluster.
    manifests:
      - name: prometheus-stack-namespace
        from_file: stacks/monitoring/manifests/prometheus-stack-namespace.yaml
      - name: tempo-namespace
        from_file: stacks/monitoring/manifests/tempo-namespace.yaml
      - name: metrics-ingest
        from_file: stacks/monitoring/manifests/metrics-ingest.yaml
        parents:
          - kind: addon
            name: kube-prometheus-stack
    addons:
      - name: prometheus-operator-crds
        chart_name: prometheus-operator-crds
        chart_version: 30.0.1
        registry_name: prometheus-community
        registry_url: https://prometheus-community.github.io/helm-charts
        namespace: prometheus-stack
        parents:
          - kind: manifest
            name: prometheus-stack-namespace
      - name: kube-prometheus-stack
        chart_name: kube-prometheus-stack
        chart_version: 83.4.0
        registry_name: prometheus-community
        registry_url: https://prometheus-community.github.io/helm-charts
        namespace: prometheus-stack
        parents:
          - kind: addon
            name: prometheus-operator-crds
          - kind: manifest
            name: prometheus-stack-namespace
        configuration:
          from_file: stacks/monitoring/add-ons/kube-prometheus-stack/values.yaml
          encrypted_paths:
            - webhook_url
      - name: tempo
        chart_name: tempo
        chart_version: 2.0.0
        registry_name: grafana
        registry_url: https://grafana.github.io/helm-charts
        namespace: tempo
        parents:
          - kind: addon
            name: kube-prometheus-stack
          - kind: manifest
            name: tempo-namespace
        configuration:
          from_file: stacks/monitoring/add-ons/tempo/values.yaml
      - name: grafana
        chart_name: grafana
        chart_version: 10.5.15
        registry_name: grafana
        registry_url: https://grafana.github.io/helm-charts
        namespace: grafana
        parents:
          - kind: addon
            name: kube-prometheus-stack
          - kind: addon
            name: tempo
        configuration:
          from_file: stacks/monitoring/add-ons/grafana/values.yaml
```

The CRDs deploy first, then Prometheus, then Tempo (which needs the remote-write target up), then Grafana (which needs both data sources). Every parent is a `kind` and `name` pair; the shorthand `- addon: tempo` is silently dropped.

**6. Make it the cluster's metrics source**

Ankra's own metrics pages, insights and the AI read from the cluster's configured Prometheus. Point the hub at itself in the cluster file, and the hub's dashboards light up on the next sync:

```yaml theme={null}
spec:
  prometheus_metrics:
    endpoint: http://kube-prometheus-stack-prometheus.prometheus-stack.svc.cluster.local:9090
    flavor: self_hosted
```

The spokes run Prometheus in agent mode and hold no queryable data, so they cannot point at themselves. Give them the hub instead: add a second Ingress on the hub for `metrics-query.example.com` with a `basicAuth` middleware, register that username and password as a metrics credential in Ankra, and set each spoke's `prometheus_metrics` to that endpoint with `credential_name` and `verify_ssl: true`. [Prometheus](/integrations/prometheus) covers the credential and the endpoints Ankra accepts.

***

## Step 5: Infrastructure cluster - central logs with OpenSearch

The OpenSearch operator runs a three-node cluster with Dashboards. Fluent Bit on the hub ships the hub's own logs; the spokes ship theirs through a `logs-ingest` endpoint that exposes exactly `/_bulk` to allow-listed addresses, each spoke with its own user that can write only its own index prefix.

**1. The OpenSearch cluster**

```yaml theme={null}
# stacks/logs/manifests/opensearch-cluster.yaml
apiVersion: opensearch.org/v1
kind: OpenSearchCluster
metadata:
  name: infra
  namespace: opensearch
spec:
  general:
    serviceName: infra-logs
    version: 2.19.2
  dashboards:
    enable: true
    version: 2.19.2
    replicas: 2
    tls:
      enable: false
    resources:
      requests:
        memory: 512Mi
        cpu: 200m
      limits:
        memory: 1Gi
        cpu: 500m
  security:
    config:
      adminCredentialsSecret:
        name: opensearch-admin          # from the infra-secrets stack, keys username and password
      securityConfigSecret:
        name: opensearch-securityconfig # users, roles and role mappings below
    tls:
      transport:
        generate: true
        perNode: true
      http:
        generate: true
  nodePools:
    - component: masters
      replicas: 3
      diskSize: 500Gi
      roles:
        - cluster_manager
        - data
        - ingest
      jvm: -Xms1g -Xmx1g
      resources:
        requests:
          memory: 2Gi
          cpu: 500m
        limits:
          memory: 2Gi
          cpu: "1"
      persistence:
        pvc:
          storageClass: block-storage-retain
          accessModes:
            - ReadWriteOnce
```

Pre-creating the admin password in `infra-secrets` instead of letting the operator generate one is what lets Fluent Bit on the hub read it from the same Secret. The operator defaults `securityConfigSecret` to an empty name with its own field manager, so this manifest is declared with `force: true` in the stack, or server-side apply conflicts on it.

**2. Retention and the application log index template**

Two ISM policies delete indices by age, and one index template keeps the application indices to a single shard with structured log lines under `app` as a `flat_object`, so two applications that use the same key with different types never reject each other's documents.

```yaml theme={null}
# stacks/logs/manifests/opensearch-retention.yaml
apiVersion: opensearch.org/v1
kind: OpenSearchISMPolicy
metadata:
  name: log-rotation
  namespace: opensearch
spec:
  opensearchCluster:
    name: infra
  policyId: log-rotation
  description: Delete indices older than 14 days
  defaultState: hot
  states:
    - name: hot
      actions: []
      transitions:
        - stateName: delete
          conditions:
            minIndexAge: 14d
    - name: delete
      actions:
        - delete: {}
      transitions: []
  ismTemplate:
    indexPatterns:
      - "*"
    priority: 100
```

```yaml theme={null}
# stacks/logs/manifests/opensearch-retention.yaml (continued)
apiVersion: opensearch.org/v1
kind: OpensearchIndexTemplate
metadata:
  name: app-logs
  namespace: opensearch
spec:
  opensearchCluster:
    name: infra
  name: app-logs
  indexPatterns:
    - production-*
    - development-*
  priority: 200
  template:
    settings:
      index:
        number_of_shards: 1
        number_of_replicas: 1
        refresh_interval: 30s
        mapping:
          total_fields:
            limit: 2000
    mappings:
      properties:
        app:
          type: flat_object
        log:
          type: text
```

ISM attaches a policy version to an index when the index is created. Shortening `minIndexAge` later applies to new indices on its own; existing ones keep the version they were born with until they age out.

**3. One user per sending cluster**

The security config is a Secret the operator pushes through a securityadmin job whenever it changes. Anything added through the Dashboards UI is wiped by the next run, so roles live in Git. The relevant part gives each spoke a role that can create and bulk-write its own prefix and nothing else:

```yaml theme={null}
# inside the opensearch-securityconfig Secret, roles.yml
log_shipper_production:
  cluster_permissions:
    - cluster_monitor
    - indices:data/write/bulk
  index_permissions:
    - index_patterns:
        - "production-*"
      allowed_actions:
        - create_index
        - indices:data/write/bulk*
        - indices:data/write/index
```

The users themselves are `OpenSearchUser` resources whose password comes from the sealed `opensearch-log-shipper-production` and `-development` Secrets in `infra-secrets`; the same values are what the spokes' shippers are given in Step 8. A `401` on a spoke means those two copies differ.

**4. The logs-ingest endpoint**

Traefik terminates the public TLS, re-encrypts to OpenSearch and verifies the operator-generated certificate, so no shipper ever needs `insecureSkipVerify`.

```yaml theme={null}
# stacks/logs/manifests/logs-ingest.yaml
apiVersion: v1
kind: Service
metadata:
  name: logs-ingest
  namespace: opensearch
  annotations:
    traefik.ingress.kubernetes.io/service.serversscheme: https
    traefik.ingress.kubernetes.io/service.serverstransport: opensearch-opensearch-http@kubernetescrd
spec:
  type: ClusterIP
  ports:
    - name: https
      port: 9200
      targetPort: 9200
  selector:
    opensearch.org/opensearch-cluster: infra
    opensearch.org/opensearch-nodepool: masters
```

```yaml theme={null}
# stacks/logs/manifests/logs-ingest.yaml (continued)
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
  name: opensearch-http
  namespace: opensearch
spec:
  serverName: infra.opensearch.svc
  rootCAs:
    - secret: infra-http-cert
```

```yaml theme={null}
# stacks/logs/manifests/logs-ingest.yaml (continued)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: logs-ingest-allowlist
  namespace: opensearch
spec:
  ipAllowList:
    sourceRange:
      - <production-egress-ip>/32
      - <development-egress-ip>/32
```

```yaml theme={null}
# stacks/logs/manifests/logs-ingest.yaml (continued)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: logs-ingest
  namespace: opensearch
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    external-dns.alpha.kubernetes.io/hostname: logs-ingest.example.com
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
    traefik.ingress.kubernetes.io/router.middlewares: opensearch-logs-ingest-allowlist@kubernetescrd
spec:
  ingressClassName: traefik
  rules:
    - host: logs-ingest.example.com
      http:
        paths:
          - path: /_bulk
            pathType: Exact
            backend:
              service:
                name: logs-ingest
                port:
                  number: 9200
  tls:
    - hosts:
        - logs-ingest.example.com
      secretName: logs-ingest-tls
```

Only exact `/_bulk` is routed. `_search`, `_cat`, `_security` and the rest of the REST API are not reachable through this host at all; Dashboards on `logs.example.com` is the only human entrance, and it is gated in Step 6.

**5. Fluent Bit for the hub's own logs**

```yaml theme={null}
# stacks/logs/add-ons/fluent-bit/values.yaml
env:
  - name: OPENSEARCH_USER
    valueFrom:
      secretKeyRef:
        name: opensearch-admin
        key: username
  - name: OPENSEARCH_PASSWORD
    valueFrom:
      secretKeyRef:
        name: opensearch-admin
        key: password
tolerations:
  - operator: Exists
    effect: NoSchedule
config:
  service: |
    [SERVICE]
        Flush         5
        Log_Level     info
        Parsers_File  parsers.conf
        HTTP_Server   On
        HTTP_Listen   0.0.0.0
        HTTP_Port     2020
  inputs: |
    [INPUT]
        Name              tail
        Path              /var/log/containers/*.log
        multiline.parser  docker, cri
        Tag               kube.*
        Mem_Buf_Limit     50MB
        DB                /var/log/flb_kube.db
        Skip_Long_Lines   On
  filters: |
    [FILTER]
        Name                kubernetes
        Match               kube.*
        Merge_Log           On
        Keep_Log            Off
        K8S-Logging.Parser  On
        K8S-Logging.Exclude On
  outputs: |
    [OUTPUT]
        Name                opensearch
        Match               kube.*
        Host                infra-logs.opensearch.svc
        Port                9200
        HTTP_User           ${OPENSEARCH_USER}
        HTTP_Passwd         ${OPENSEARCH_PASSWORD}
        tls                 On
        tls.verify          Off
        Suppress_Type_Name  On
        Logstash_Format     On
        Logstash_Prefix     infrastructure
        Replace_Dots        On
```

**6. Declare the stack and the log source**

```yaml theme={null}
stacks:
  - name: logs
    description: OpenSearch operator, cluster, Dashboards, retention and Fluent Bit.
    manifests:
      - name: opensearch-namespace
        from_file: stacks/logs/manifests/opensearch-namespace.yaml
      - name: opensearch-securityconfig
        from_file: stacks/logs/manifests/opensearch-securityconfig.yaml
        parents:
          - kind: manifest
            name: opensearch-namespace
        encrypted_paths:
          - internal_users.yml
      - name: opensearch-cluster
        from_file: stacks/logs/manifests/opensearch-cluster.yaml
        force: true
        parents:
          - kind: addon
            name: opensearch-operator
          - kind: manifest
            name: opensearch-securityconfig
      - name: opensearch-retention
        from_file: stacks/logs/manifests/opensearch-retention.yaml
        parents:
          - kind: manifest
            name: opensearch-cluster
      - name: opensearch-log-shipper-users
        from_file: stacks/logs/manifests/opensearch-log-shipper-users.yaml
        parents:
          - kind: manifest
            name: opensearch-cluster
      - name: logs-ingest
        from_file: stacks/logs/manifests/logs-ingest.yaml
        parents:
          - kind: manifest
            name: opensearch-cluster
    addons:
      - name: opensearch-operator
        chart_name: opensearch-operator
        chart_version: 3.0.2
        registry_name: opensearch-k8s-operator
        registry_url: https://opensearch-project.github.io/opensearch-k8s-operator/
        namespace: opensearch-operator
        parents: []
      - name: fluent-bit
        chart_name: fluent-bit
        chart_version: 0.49.1
        registry_name: fluent
        registry_url: https://fluent.github.io/helm-charts
        namespace: opensearch
        parents:
          - kind: manifest
            name: opensearch-cluster
        configuration:
          from_file: stacks/logs/add-ons/fluent-bit/values.yaml
```

Then make OpenSearch the cluster's log source so Ankra's log search and the AI read from it. The credential is registered in the platform and referred to by name; it is never in Git.

```yaml theme={null}
spec:
  log_source:
    provider: opensearch
    endpoint: https://infra-logs.opensearch.svc:9200
    credential_name: opensearch-read
    index_pattern: "infrastructure-*"
```

The spokes get the same block with their own index pattern once Step 8 has them shipping. [Log Sources](/integrations/log-sources) has the field mappings OpenSearch needs.

> [!NOTE]
>
> If you would rather not run a log store, [Ankra Hosted Logs](/guides/hosted-logs) keeps seven days of every cluster's container logs with one switch. The OpenSearch route is for longer retention, your own retention rules and a store you can query from Grafana and your own tooling.

***

## Step 6: Infrastructure cluster - a staff sign-in realm with Kratos and Hydra

Grafana, OpenSearch Dashboards, Harbor and OneUptime each have their own login. Instead of four sets of local accounts, the hub runs one **staff identity realm**: Ory Kratos, with Microsoft 365 as its only sign-in method, pinned to your Entra tenant; Ory Hydra, which turns a Kratos session into OpenID Connect tokens for each tool; and oauth2-proxy, a forward-auth gate that any Ingress opts into with one annotation. Disabling someone in Entra ends their next sign-in everywhere, because Kratos holds no password, passkey or code of its own that could outlive it.

> [!NOTE]
>
> This realm is for the tools on the hub. Sign-in to Ankra itself is the organisation's [single sign-on](/guides/single-sign-on), and `kubectl` access is a [cluster access grant](/guides/cluster-access). The three are separate on purpose: a person removed from one is not implicitly removed from the others, so remove them from all three.

| Host | What | Who talks to it |
| - | - | - |
| `staff-login.example.com` | The OAuth2 endpoints of Hydra, the self-service endpoints of Kratos, the login and consent UI | Browsers, during a sign-in |
| `oauth.example.com` | oauth2-proxy | Traefik, on every request to a gated host |

**1. A database for the realm**

Kratos and Hydra need separate databases (their table names collide). One CloudNativePG cluster with two instances hosts both; the second instance is a standby for failover. The `cloudnative-pg` operator can be shared with Harbor's database in Step 7.

```yaml theme={null}
# stacks/sso-gateway/manifests/sso-postgres.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: sso-postgres
  namespace: sso-gateway
spec:
  instances: 2
  imageName: ghcr.io/cloudnative-pg/postgresql:17.10-standard-bookworm
  primaryUpdateStrategy: unsupervised
  bootstrap:
    initdb:
      database: hydra
      owner: hydra
      secret:
        name: sso-hydra-db-credentials
  managed:
    roles:
      - name: kratos
        ensure: present
        login: true
        passwordSecret:
          name: sso-kratos-db-credentials
  postgresql:
    parameters:
      max_connections: "100"
  storage:
    size: 5Gi
    storageClass: block-storage-retain
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 1Gi
```

```yaml theme={null}
# stacks/sso-gateway/manifests/sso-postgres.yaml (continued)
apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: sso-kratos
  namespace: sso-gateway
spec:
  name: kratos
  owner: kratos
  cluster:
    name: sso-postgres
```

**2. Kratos: one sign-in method, pinned to your tenant**

Everything Kratos would own outright stays off. Registration is enabled only so a first Microsoft sign-in creates the identity; with the identity mapper supplying every required trait, no form is ever shown.

```yaml theme={null}
# stacks/sso-gateway/add-ons/kratos/values.yaml
replicaCount: 2
secret:
  enabled: false
  nameOverride: sso-kratos-secrets   # dsn, secretsDefault, secretsCookie, secretsCipher - a sealed manifest
courier:
  enabled: false                      # no email flows, nothing to send
cleanup:
  enabled: true
  batchSize: 100
  keepLast: 6h
cronjob:
  cleanup:
    schedule: "30 */6 * * *"
kratos:
  development: false
  automigration:
    enabled: true
    type: job                         # one migration per release, not a race between replicas
  identitySchemas:
    identity.default.schema.json: |
      {
        "$id": "https://staff-login.example.com/schemas/default.schema.json",
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "Staff",
        "type": "object",
        "properties": {
          "traits": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "format": "email",
                "pattern": "^[^@\\s]+@example\\.com$",
                "ory.sh/kratos": { "verification": { "via": "email" } }
              }
            },
            "required": ["email"],
            "additionalProperties": false
          }
        }
      }
  config:
    serve:
      public:
        port: 4433
        base_url: https://staff-login.example.com/
      admin:
        port: 4434
        base_url: http://kratos-admin.sso-gateway.svc.cluster.local/
    identity:
      default_schema_id: default
      schemas:
        - id: default
          url: file:///etc/config/identity.default.schema.json
    oauth2_provider:
      url: http://hydra-admin.sso-gateway.svc.cluster.local:4445
    selfservice:
      default_browser_return_url: https://staff-login.example.com/
      allowed_return_urls:
        - https://staff-login.example.com/
      methods:
        password:
          enabled: false
        passkey:
          enabled: false
        webauthn:
          enabled: false
        totp:
          enabled: false
        lookup_secret:
          enabled: false
        link:
          enabled: false
        code:
          enabled: false
        oidc:
          enabled: true
          config:
            providers:
              - id: microsoft
                provider: microsoft
                label: Microsoft 365
                microsoft_tenant: <entra-tenant-id>
                client_id: <entra-application-id>
                client_secret: <entra-client-secret>
                pkce: never
                scope:
                  - openid
                  - profile
                  - email
                mapper_url: base64://<jsonnet-mapper-base64>
      flows:
        login:
          ui_url: https://staff-login.example.com/login
          lifespan: 10m
        registration:
          enabled: true
          ui_url: https://staff-login.example.com/registration
          lifespan: 10m
          after:
            oidc:
              hooks:
                - hook: session
        settings:
          ui_url: https://staff-login.example.com/settings
          privileged_session_max_age: 15m
          required_aal: highest_available
        error:
          ui_url: https://staff-login.example.com/error
```

Three layers decide who gets in: the tenant pin (`microsoft_tenant`), the schema's email pattern (which also keeps B2B guests of the tenant out), and each tool's own domain check. The identity mapper is a small Jsonnet document that reads `email`, falling back to `preferred_username` and `upn` because Entra omits `email` for many directory members, lower-cases it, and records it as a verified address:

```jsonnet theme={null}
local claims = std.extVar('claims');
local has(o, k) = std.objectHas(o, k) && o[k] != null && o[k] != '';
local found =
  if has(claims, 'email') then claims.email
  else if has(claims, 'preferred_username') then claims.preferred_username
  else if has(claims, 'upn') then claims.upn
  else null;
local email = if found != null then std.asciiLower(found) else null;
{
  identity: {
    traits: { [if email != null then 'email']: email },
    [if email != null then 'verified_addresses']: [{ via: 'email', value: email }],
  },
}
```

`verified_addresses` is what makes the consent step emit `email_verified=true`; without it oauth2-proxy refuses the sign-in. Validate any change to the mapper with `jsonnet` before merging: Microsoft is the only method, so a mapper error is a total lockout.

In Entra, register a single-tenant **Web** application whose redirect URI is exactly `https://staff-login.example.com/self-service/methods/oidc/callback/microsoft`, with delegated `openid profile email` and admin consent. Until that URI is registered Microsoft answers every sign-in with `AADSTS50011`. Seal the secret: `ankra cluster encrypt addon kratos --key client_secret -f <cluster.yaml>`.

**3. Hydra: tokens for the tools**

```yaml theme={null}
# stacks/sso-gateway/add-ons/hydra/values.yaml
replicaCount: 2
secret:
  enabled: false
  nameOverride: sso-hydra-secrets    # dsn, secretsSystem, secretsCookie - a sealed manifest
hydra:
  dev: false
  automigration:
    enabled: true
    type: job
  config:
    serve:
      public:
        port: 4444
      admin:
        port: 4445                      # never routed
      cookies:
        same_site_mode: Lax
      tls:
        allow_termination_from:
          - 10.0.0.0/8                  # the pod CIDR: Traefik terminates TLS
    urls:
      self:
        issuer: https://staff-login.example.com/
        public: https://staff-login.example.com/
      login: https://staff-login.example.com/login
      consent: https://staff-login.example.com/consent
      logout: https://staff-login.example.com/logout
      error: https://staff-login.example.com/error
      post_logout_redirect: https://staff-login.example.com/
    ttl:
      access_token: 1h
      refresh_token: 8h
      id_token: 1h
      auth_code: 10m
    oauth2:
      expose_internal_errors: false
    log:
      level: info
      format: json
      leak_sensitive_values: false
maester:
  enabled: true                         # registers OAuth2Client resources from any namespace
janitor:
  enabled: true
  cleanupGrants: true
  cleanupRequests: true
  cleanupTokens: true
cronjob:
  janitor:
    schedule: "0 */6 * * *"
pdb:
  enabled: true
  spec:
    minAvailable: 1
```

Two details break everything when wrong. The issuer string, trailing slash included, is the `iss` claim and oauth2-proxy compares it byte for byte with its `--oidc-issuer-url`. And `allow_termination_from` must contain the pod CIDR, or Hydra silently emits `http://` redirect and issuer URLs behind Traefik.

Each tool is an `OAuth2Client` resource that hydra-maester registers; its secret is read from a sealed Secret in the tool's own namespace. Keep `skipConsent: false` on every client: the consent app is what injects the `email` claim into the id\_token.

**4. oauth2-proxy: the gate**

```yaml theme={null}
# stacks/sso-gateway/add-ons/oauth2-proxy/values.yaml
fullnameOverride: oauth2-proxy
replicaCount: 2
config:
  existingSecret: oauth2-proxy-credentials   # client-id, client-secret, cookie-secret - sealed
  configFile: ""
  emailDomains:
    - example.com
  upstreams:
    - static://202
extraArgs:
  - --provider=oidc
  - --provider-display-name=Staff
  - --oidc-issuer-url=https://staff-login.example.com/
  - --scope=openid email
  - --oidc-email-claim=email
  - --code-challenge-method=S256
  - --insecure-oidc-allow-unverified-email=false
  - --email-domain=example.com
  - --upstream=static://202
  - --reverse-proxy=true
  - --skip-provider-button=true
  - --set-xauthrequest=true
  - --pass-access-token=false
  - --pass-authorization-header=false
  - --skip-auth-preflight=true
  - --redirect-url=https://oauth.example.com/oauth2/callback
  - --cookie-domain=.example.com
  - --whitelist-domain=.example.com
  - --cookie-secure=true
  - --cookie-httponly=true
  - --cookie-samesite=lax
  - --cookie-expire=8h
  - --cookie-refresh=0
  - --cookie-csrf-per-request=true
  - --session-store-type=cookie
ingress:
  enabled: true
  className: traefik
  path: /
  pathType: Prefix
  hosts:
    - oauth.example.com
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    external-dns.alpha.kubernetes.io/hostname: oauth.example.com
  tls:
    - secretName: oauth2-proxy-tls
      hosts:
        - oauth.example.com
podDisruptionBudget:
  enabled: true
  minAvailable: 1
metrics:
  enabled: true
  serviceMonitor:
    enabled: true
```

The cookie is set for `.example.com`, so one sign-in covers every gated host for eight hours, then Microsoft again. The gate itself is a Traefik middleware:

```yaml theme={null}
# stacks/sso-gateway/manifests/sso-middleware.yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: sso
  namespace: sso-gateway
spec:
  forwardAuth:
    address: http://oauth2-proxy.sso-gateway.svc.cluster.local:80/
    trustForwardHeader: true
    preserveLocationHeader: true
    authResponseHeaders:
      - X-Auth-Request-User
      - X-Auth-Request-Email
      - X-Auth-Request-Preferred-Username
```

Any Ingress on the cluster opts in with one annotation; this is the line already on Grafana's Ingress in Step 4:

```yaml theme={null}
metadata:
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: sso-gateway-sso@kubernetescrd
```

**5. Protect the header**

Grafana trusts `X-Auth-Request-Email` as the signed-in user. Only Traefik may present it, so a NetworkPolicy lets only the `traefik` and `prometheus-stack` namespaces reach the Grafana pods. Without it, any pod in the cluster could forge the header and become any user.

```yaml theme={null}
# stacks/sso-gateway/manifests/grafana-networkpolicy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: grafana-allow-gated-ingress
  namespace: grafana
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: grafana
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: traefik
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: prometheus-stack
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: grafana
```

**6. Route the realm and declare the stack**

Hydra's public endpoints (`/oauth2`, `/userinfo`, `/.well-known/openid-configuration`, `/.well-known/jwks.json`), Kratos's public endpoints (`/self-service`, `/sessions`, `/schemas`, `/.well-known/ory`) and the login UI (everything else) share `staff-login.example.com` as three Ingresses with Traefik router priorities. Neither admin API is routed: Kratos's admin API has no authentication of its own, and exposing it is publishing the staff directory.

```yaml theme={null}
stacks:
  - name: sso-gateway
    description: Staff identity realm (Kratos + Hydra on Microsoft 365) and the oauth2-proxy gate.
    manifests:
      - name: sso-gateway-namespace
        from_file: stacks/sso-gateway/manifests/namespace.yaml
      - name: sso-hydra-db-credentials
        from_file: stacks/sso-gateway/manifests/sso-hydra-db-credentials.yaml
        parents:
          - kind: manifest
            name: sso-gateway-namespace
        encrypted_paths:
          - password
      - name: sso-kratos-db-credentials
        from_file: stacks/sso-gateway/manifests/sso-kratos-db-credentials.yaml
        parents:
          - kind: manifest
            name: sso-gateway-namespace
        encrypted_paths:
          - password
      - name: sso-postgres
        from_file: stacks/sso-gateway/manifests/sso-postgres.yaml
        parents:
          - kind: addon
            name: cloudnative-pg
          - kind: manifest
            name: sso-hydra-db-credentials
          - kind: manifest
            name: sso-kratos-db-credentials
      - name: sso-hydra-secrets
        from_file: stacks/sso-gateway/manifests/sso-hydra-secrets.yaml
        parents:
          - kind: manifest
            name: sso-gateway-namespace
        encrypted_paths:
          - dsn
          - secretsSystem
          - secretsCookie
      - name: sso-kratos-secrets
        from_file: stacks/sso-gateway/manifests/sso-kratos-secrets.yaml
        parents:
          - kind: manifest
            name: sso-gateway-namespace
        encrypted_paths:
          - dsn
          - secretsDefault
          - secretsCookie
          - secretsCipher
      - name: oauth2-proxy-credentials
        from_file: stacks/sso-gateway/manifests/oauth2-proxy-credentials.yaml
        parents:
          - kind: manifest
            name: sso-gateway-namespace
        encrypted_paths:
          - client-secret
          - cookie-secret
      - name: sso-gateway-oauth2-client
        from_file: stacks/sso-gateway/manifests/sso-gateway-oauth2-client.yaml
        parents:
          - kind: addon
            name: hydra
      - name: sso-middleware
        from_file: stacks/sso-gateway/manifests/sso-middleware.yaml
        parents:
          - kind: addon
            name: oauth2-proxy
      - name: staff-login-ingress
        from_file: stacks/sso-gateway/manifests/staff-login-ingress.yaml
        parents:
          - kind: addon
            name: hydra
          - kind: addon
            name: kratos
      - name: grafana-networkpolicy
        from_file: stacks/sso-gateway/manifests/grafana-networkpolicy.yaml
    addons:
      - name: cloudnative-pg
        chart_name: cloudnative-pg
        chart_version: 0.29.1
        registry_name: cloudnative-pg
        registry_url: https://cloudnative-pg.github.io/charts
        namespace: cnpg-system
        parents: []
      - name: hydra
        chart_name: hydra
        chart_version: 0.63.0
        registry_name: ory
        registry_url: https://k8s.ory.sh/helm/charts
        namespace: sso-gateway
        parents:
          - kind: manifest
            name: sso-postgres
          - kind: manifest
            name: sso-hydra-secrets
        configuration:
          from_file: stacks/sso-gateway/add-ons/hydra/values.yaml
      - name: kratos
        chart_name: kratos
        chart_version: 0.63.0
        registry_name: ory
        registry_url: https://k8s.ory.sh/helm/charts
        namespace: sso-gateway
        parents:
          - kind: manifest
            name: sso-postgres
          - kind: manifest
            name: sso-kratos-secrets
          - kind: addon
            name: hydra
        configuration:
          from_file: stacks/sso-gateway/add-ons/kratos/values.yaml
          encrypted_paths:
            - client_secret
      - name: kratos-selfservice-ui-node
        chart_name: kratos-selfservice-ui-node
        chart_version: 0.63.0
        registry_name: ory
        registry_url: https://k8s.ory.sh/helm/charts
        namespace: sso-gateway
        parents:
          - kind: addon
            name: kratos
        configuration:
          from_file: stacks/sso-gateway/add-ons/kratos-selfservice-ui-node/values.yaml
      - name: oauth2-proxy
        chart_name: oauth2-proxy
        chart_version: 10.7.0
        registry_name: oauth2-proxy
        registry_url: https://oauth2-proxy.github.io/manifests
        namespace: sso-gateway
        parents:
          - kind: addon
            name: hydra
          - kind: manifest
            name: oauth2-proxy-credentials
          - kind: manifest
            name: sso-gateway-oauth2-client
        configuration:
          from_file: stacks/sso-gateway/add-ons/oauth2-proxy/values.yaml
```

The parent edges matter here more than anywhere: Hydra's migration job is a Helm pre-install hook, so Ankra must not start the release until CloudNativePG reports the database healthy, and oauth2-proxy must not start until Hydra can answer its discovery request.

> [!WARNING]
>
> **Never gate the registry host.** A browser redirect on `registry.example.com` breaks `docker login`, CI pushes and Ankra's own chart pulls. Harbor and OpenSearch Dashboards sign in through the realm with their native OpenID Connect support (an `OAuth2Client` each); only tools with no OIDC of their own go behind the oauth2-proxy gate. Keep every tool's local admin as the break-glass account, reachable off the gated path.

***

## Step 7: Infrastructure cluster - registry and uptime

Two more stacks follow the same pattern, so only what is different is shown.

**1. Harbor on CloudNativePG and Redis**

Harbor's chart runs its own database and Redis by default; for production they come from operators instead, so they are backed up, replicated and upgraded like every other database. Harbor's OIDC settings go in `core.extraEnvVars` as `CONFIG_OVERWRITE_JSON`, read from a sealed Secret, with the Hydra client `harbor` registered by an `OAuth2Client` next to it:

```json theme={null}
{
  "auth_mode": "oidc_auth",
  "oidc_name": "Staff",
  "oidc_endpoint": "https://staff-login.example.com/",
  "oidc_client_id": "harbor",
  "oidc_client_secret": "<sealed>",
  "oidc_scope": "openid,profile,email,offline_access",
  "oidc_user_claim": "email",
  "oidc_auto_onboard": true,
  "oidc_verify_cert": true,
  "self_registration": false
}
```

Harbor applies that JSON on every core start and then makes every setting read-only in the UI, so changes are a Git change plus a bump of a pod annotation. Robot accounts never look at `auth_mode`, so CI pushes and Ankra's pulls are unaffected. Once Harbor is up, [register it as your application registry](/guides/harbor-registry) so Ankra mints a push robot per application.

Add a `PrometheusRule` beside it. The infrastructure Prometheus evaluates it, so the alert reaches the same channel as everything else:

```yaml theme={null}
# stacks/registry/manifests/harbor-alerts.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: harbor-core
  namespace: harbor
spec:
  groups:
    - name: harbor-core
      rules:
        - alert: HarborCoreReplicaServerErrors
          expr: |
            (
              sum by (pod) (rate(harbor_core_http_request_total{code=~"5.."}[5m]))
              /
              sum by (pod) (rate(harbor_core_http_request_total[5m]))
            ) > 0.2
            and
            sum by (pod) (rate(harbor_core_http_request_total[5m])) > 0.1
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: "harbor-core pod {{ $labels.pod }} is failing {{ $value | humanizePercentage }} of requests"
        - alert: HarborComponentUnhealthy
          expr: harbor_health == 0
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: "Harbor reports component {{ $labels.component }} unhealthy"
```

The first rule is per pod on purpose: a single replica returning 5xx behind a healthy Service is exactly what a readiness probe misses.

**2. OneUptime behind the gate**

OneUptime probes the public URLs that matter from inside the cluster every minute, opens an incident when one fails, and hosts status pages. Its Ingress carries the `sso-gateway-sso@kubernetescrd` middleware, and its own login is Global OIDC against the staff Hydra, so staff get in with Microsoft 365 and nobody else sees the page. Its Postgres is another CloudNativePG cluster, two instances, on the retain storage class.

A status page meant for customers needs an un-gated host of its own; everything under the gated host is staff-only by construction.

***

## Step 8: Production and development clusters - send metrics and logs

The spokes carry no Grafana, no Alertmanager, no rules and no queryable Prometheus. Two small stacks make each of them a sender. Add the following to `clusters/production-<short-id>/production.yaml`, then repeat for development with the names swapped.

**1. Prometheus in agent mode**

The same kube-prometheus-stack chart, with `agentMode` on and the hub as the remote-write target. The `cluster` external label is what tells this cluster's series apart in the central store; keep it equal to the Ankra cluster name.

```yaml theme={null}
# stacks/metrics-agent/add-ons/metrics-agent/values.yaml
fullnameOverride: metrics-agent
crds:
  enabled: false
grafana:
  enabled: false
alertmanager:
  enabled: false
defaultRules:
  create: false
kubeControllerManager:
  enabled: false
kubeScheduler:
  enabled: false
kubeEtcd:
  enabled: false
kubeProxy:
  enabled: false
prometheus:
  agentMode: true
  prometheusSpec:
    externalLabels:
      cluster: production
    remoteWrite:
      - url: https://metrics-ingest.example.com/api/v1/write
        queueConfig:
          capacity: 10000
          maxSamplesPerSend: 2000
    serviceMonitorSelectorNilUsesHelmValues: false
    podMonitorSelectorNilUsesHelmValues: false
    probeSelectorNilUsesHelmValues: false
    scrapeConfigSelectorNilUsesHelmValues: false
    resources:
      requests:
        cpu: 100m
        memory: 512Mi
      limits:
        memory: 1536Mi
prometheus-node-exporter:
  priorityClassName: system-node-critical
```

```yaml theme={null}
stacks:
  - name: metrics-agent
    description: Prometheus agent remote-writing every series to the infrastructure cluster.
    manifests:
      - name: metrics-agent-namespace
        from_file: stacks/metrics-agent/manifests/namespace.yaml
    addons:
      - name: prometheus-operator-crds
        chart_name: prometheus-operator-crds
        chart_version: 30.0.1
        registry_name: prometheus-community
        registry_url: https://prometheus-community.github.io/helm-charts
        namespace: metrics-agent
        parents:
          - kind: manifest
            name: metrics-agent-namespace
      - name: metrics-agent
        chart_name: kube-prometheus-stack
        chart_version: 83.4.0
        registry_name: prometheus-community
        registry_url: https://prometheus-community.github.io/helm-charts
        namespace: metrics-agent
        parents:
          - kind: addon
            name: prometheus-operator-crds
          - kind: manifest
            name: metrics-agent-namespace
        configuration:
          from_file: stacks/metrics-agent/add-ons/metrics-agent/values.yaml
```

Every `ServiceMonitor` and `PodMonitor` an application ships is picked up (the `NilUsesHelmValues: false` lines), so adding an exporter to an application is enough for it to appear in Grafana on the hub.

**2. Fluent Bit shipping to the hub**

Read only the application namespaces, buffer on the node's filesystem so an outage on the hub is replayed rather than lost, and authenticate as this cluster's own OpenSearch user. The password is the same value sealed into the hub's `infra-secrets` stack in Step 3.

```yaml theme={null}
# stacks/log-shipping/add-ons/fluent-bit/values.yaml
env:
  - name: OPENSEARCH_PASSWORD
    valueFrom:
      secretKeyRef:
        name: central-logs-opensearch
        key: password
resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    memory: 256Mi
config:
  service: |
    [SERVICE]
        Flush                     5
        Log_Level                 info
        Parsers_File              parsers.conf
        HTTP_Server               On
        HTTP_Listen               0.0.0.0
        HTTP_Port                 2020
        storage.path              /var/fluent-bit/data
        storage.sync              normal
        storage.backlog.mem_limit 16M
        storage.max_chunks_up     32
  inputs: |
    [INPUT]
        Name              tail
        Path              /var/log/containers/*_shop_*.log,/var/log/containers/*_api_*.log
        multiline.parser  cri
        Tag               kube.*
        Read_from_Head    On
        Skip_Long_Lines   On
        Skip_Empty_Lines  On
        storage.type      filesystem
        DB                /var/fluent-bit/data/tail.db
  filters: |
    [FILTER]
        Name                kubernetes
        Match               kube.*
        Merge_Log           On
        Merge_Log_Key       app
        Keep_Log            Off
        K8S-Logging.Parser  On
        K8S-Logging.Exclude On
        Labels              On
        Annotations         Off
    [FILTER]
        Name    modify
        Match   kube.*
        Add     cluster production
  outputs: |
    [OUTPUT]
        Name                     opensearch
        Match                    kube.*
        Host                     logs-ingest.example.com
        Port                     443
        tls                      On
        tls.verify               On
        HTTP_User                log-shipper-production
        HTTP_Passwd              ${OPENSEARCH_PASSWORD}
        Suppress_Type_Name       On
        Logstash_Format          On
        Logstash_Prefix          production
        Replace_Dots             On
        compress                 gzip
        Trace_Error              On
        Retry_Limit              20
        storage.total_limit_size 1G
extraVolumes:
  - name: buffer
    hostPath:
      path: /var/fluent-bit/data
      type: DirectoryOrCreate
extraVolumeMounts:
  - name: buffer
    mountPath: /var/fluent-bit/data
```

Indices arrive on the hub as `production-YYYY.MM.DD`, one per cluster per day, filtered by `kubernetes.namespace_name` or `cluster`. Structured JSON lines land under `app.*`; anything else stays in `log`.

```yaml theme={null}
stacks:
  - name: log-shipping
    description: Fluent Bit shipping the application namespaces to the central OpenSearch.
    manifests:
      - name: log-shipping-namespace
        from_file: stacks/log-shipping/manifests/namespace.yaml
      - name: central-logs-opensearch
        from_file: stacks/log-shipping/manifests/central-logs-opensearch.yaml
        parents:
          - kind: manifest
            name: log-shipping-namespace
        encrypted_paths:
          - password
    addons:
      - name: fluent-bit
        chart_name: fluent-bit
        chart_version: 0.49.1
        registry_name: fluent
        registry_url: https://fluent.github.io/helm-charts
        namespace: log-shipping
        parents:
          - kind: manifest
            name: central-logs-opensearch
        configuration:
          from_file: stacks/log-shipping/add-ons/fluent-bit/values.yaml
```

**3. Add the spoke's egress address on the hub**

Both ingest endpoints refuse everything that is not on their allow-list. Read the spoke's egress address, add it to `metrics-ingest-allowlist` and `logs-ingest-allowlist` in the hub's cluster file, and apply. Until then every write from the spoke is a `403` in the agent's and Fluent Bit's logs.

**4. Application databases on the spokes**

Every stateful application stack on a spoke follows one shape: a CloudNativePG cluster with three instances spread across workers, the retain storage class, and an owner role per database. This is what makes Step 9 work, because the backup data plane captures CloudNativePG clusters by name.

```yaml theme={null}
# stacks/shop/manifests/shop-postgres.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: shop-postgres
  namespace: shop
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:17.10-standard-bookworm
  primaryUpdateStrategy: unsupervised
  bootstrap:
    initdb:
      database: shop
      owner: shop
      secret:
        name: shop-db-credentials
  storage:
    size: 20Gi
    storageClass: block-storage-retain
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: "2"
      memory: 2Gi
```

***

## Step 9: Back up every stateful stack

A vault is where restore points land; a stack's backup policy is what puts them there. Protection is a property of the stack itself: the command writes a `backup` block onto the stack definition, and the platform installs the backup data plane (Velero and the CloudNativePG Barman plugin) on the cluster the first time a stack on it is protected.

**1. See what a backup would carry**

```bash theme={null}
ankra cluster select production
ankra cluster stacks data list shop
```

The output lists the stack's standalone PersistentVolumeClaims and the databases an operator runs, with the engine that would capture each and the consistency it can promise. Databases are captured by default; volumes only where you name them.

**2. Protect each stateful stack, staggered**

One stack at a time, each on its own minute, so the captures do not compete for the same disks and the same vault at once:

```bash theme={null}
ankra cluster stacks protect shop \
  --vault production-backups \
  --schedule "0 1 * * *" \
  --retention daily=7,weekly=4,monthly=6 \
  --include-pvc shop/uploads \
  --backup-now --wait

ankra cluster stacks protect identity \
  --vault production-backups \
  --schedule "10 1 * * *" \
  --retention daily=7,weekly=4,monthly=6 \
  --backup-now --wait
```

The first command reports `Backup stack: installing` until Velero is actually on the cluster; a capture started before then waits rather than failing. The policy lands in the cluster file as a `backup` block, so from here on it is reviewed and versioned like everything else:

```yaml theme={null}
stacks:
  - name: shop
    backup:
      enabled: true
      vault: production-backups
      schedule: "0 1 * * *"
      retention:
        daily: 7
        weekly: 4
        monthly: 6
      selection:
        databases: true
        persistent_volume_claims:
          - shop/uploads
```

Repeat on the development cluster against `development-backups`. The hub's own stateful stacks - `sso-gateway`, `registry`, `uptime` - are protected the same way into a third vault, or into `production-backups` if you prefer fewer buckets.

**3. Read the posture**

```bash theme={null}
ankra cluster backups status
```

Every stack on the cluster is listed against what protects it: `protected`, `unprotected (no_data_assets)` for stacks with nothing to carry, and `unprotected (no_policy)` for the ones you still owe a policy. The last line of each row says when the last run succeeded or failed and when the next fires. A stack that holds data and reads `no_policy` is the thing to fix before calling the estate production.

**4. Prove a restore point can be read**

```bash theme={null}
ankra cluster stacks restore-points list shop
ankra cluster stacks restore-points get shop <restore-point-id>
```

`get` shows the manifest, the assets it carries and the run that produced it. A restore point whose status is `failed` carries nothing; find the run under `ankra runs list --kind backup --cluster production` and fix the cause before the next schedule fires. [Backups and Restore Points](/guides/backups) covers restoring in place and cloning a stack with its data onto another cluster.

> [!WARNING]
>
> Nothing is scheduled inside the cluster: no Velero `Schedule`, no CloudNativePG `ScheduledBackup`. Ankra takes the scheduled restore points itself, so every backup is one you can list, inspect and restore from the platform. If you add an in-cluster schedule as well, the same data is captured twice.

***

## Step 10: Security and access

Most of this is already in place from Step 1. What remains is turning it on where it is off by default, and deciding who reaches what.

**1. Security baseline on every cluster**

Clusters Ankra provisions arrive with the `ankra-security-baseline` stack: Trivy Operator for image vulnerabilities, configuration audits and the CIS benchmark, and Pod Security Standards enforced by the API server from namespace labels the agent manages. It starts in **Audit** mode. Once the Security Center shows no workloads failing the `baseline` standard, enforce it:

```bash theme={null}
ankra security policy-mode enforce --cluster production
ankra security violations --cluster production
ankra security overview
```

Kyverno is not part of the baseline; it is the opt-in `ankra-policy-engine` profile for image-signature verification and policies of your own. [Cluster Security](/guides/cluster-security#security-baseline) describes what runs where.

**2. Kubernetes access through the gateway, time-boxed**

Nobody gets a static kubeconfig. Access to a cluster's API goes through the Ankra kube gateway, per person, per role, with an expiry and a reason:

```bash theme={null}
ankra cluster access grant alice@example.com --cluster production --role view
ankra cluster access grant bob@example.com --cluster production --role edit --namespace shop --expires 8h --reason "release 3.2"
ankra cluster access list --cluster production
```

The organisation [access policy](/guides/cluster-access#organisation-access-policy) can require an expiry and a reason on every grant. For an incident at three in the morning, `ankra cluster access elevate --cluster production --role edit --expires 4h --reason "incident 4711"` gives the caller themselves time-boxed access within that policy, and the grant is in the audit log.

**3. Credentials that can do one thing**

* The DNS credential can edit one zone.
* The Git credential can write one repository.
* Each log shipper user can create and bulk-write one index prefix.
* The metrics-ingest endpoint can append samples and nothing else.
* Harbor robot accounts are minted per application by Ankra and can push one project.
* The backup vault keys are held by Ankra and never printed.

None of them is reused, so revoking one revokes one thing.

**4. Everything sensitive is sealed before it is committed**

Run `ankra cluster sops-config` once to confirm the organisation has its AGE key, then make a rule of it: no `stringData` in a commit, no webhook URL in values. The pre-push check is the simplest one there is:

```bash theme={null}
grep -rn "stringData:" clusters/ --include=*.yaml | grep -v ENC
```

***

## Verify

Run through this once at the end, and again after any change to the hub.

**1. Every stack converged**

```bash theme={null}
ankra cluster operations list --cluster infrastructure
ankra cluster stacks list --cluster infrastructure
ankra cluster get pods -n sso-gateway --cluster infrastructure
ankra cluster get pods -n opensearch --cluster infrastructure
```

Every stack reads `up`; `sso-postgres` x2, `hydra`, `kratos`, the UI and `oauth2-proxy` are Running; three OpenSearch nodes and two Dashboards are Ready.

**2. The spokes' series have arrived**

```bash theme={null}
ankra cluster metrics query 'count by (cluster) (up)' --cluster infrastructure
```

Three values, one per cluster. A missing cluster is an allow-list or a `cluster` label problem; the spoke's Prometheus log shows which.

**3. The ingest endpoints refuse everyone else**

From your laptop, which is not on the allow-list:

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://metrics-ingest.example.com/api/v1/write
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://logs-ingest.example.com/_bulk
curl -s -o /dev/null -w '%{http_code}\n' https://logs-ingest.example.com/_cat/indices
```

`403`, `403`, `404`. The third line is the path restriction: the REST API is not reachable through that host at all.

**4. The realm answers**

```bash theme={null}
curl -s https://staff-login.example.com/.well-known/openid-configuration | grep -o '"issuer":"[^"]*"'
```

Exactly `https://staff-login.example.com/`, trailing slash included. Then in a browser, from `https://metrics.example.com/`: the Microsoft 365 sign-in, and Grafana with your address in the top right. Start a sign-in from a tool, never from `staff-login` itself.

**5. Logs are searchable from Ankra**

Open the production cluster's **Logs** and search `cluster:production`. Rows appear with `kubernetes.namespace_name` and `app.*` fields. In OpenSearch Dashboards the same query runs against `production-*`.

**6. Backups are on and recent**

```bash theme={null}
ankra cluster backups status --cluster production
ankra backup vaults list
```

No stack with data reads `no_policy`, every last run is `succeeded`, and both vaults read `ready`.

**7. An alert reaches the channel**

```bash theme={null}
ankra alerts destinations test <destination-id>
ankra alerts routes preview --kind resource_health_degraded --severity critical --cluster-id <production-id>
```

The test lands in the channel; the preview names the destination. Then silence the Alertmanager `Watchdog` route for a minute in the hub's values and watch Alertmanager's own `Watchdog` arrive the same way - that proves the in-cluster path end to end.

***

## Troubleshooting

> [accordion] Remote write or log shipping returns 403
>
> The spoke's egress address is not on the hub's allow-list. The address changes when a cluster's network is recreated. Read it from inside the spoke, update `metrics-ingest-allowlist` and `logs-ingest-allowlist` in the hub's cluster file, and apply. Fluent Bit replays its filesystem buffer once the `403`s stop; Prometheus's remote-write queue holds roughly an hour before it drops samples.

> [accordion] Log shipping returns 401
>
> The password in the spoke's `central-logs-opensearch` Secret and the hub's `opensearch-log-shipper-<cluster>` Secret differ. Decrypt both with `ankra cluster decrypt manifest <name> -f <cluster.yaml>` and compare. The shipper users are also briefly absent for up to 30 seconds after every security config push while the operator re-creates them; a burst of `401`s right after a commit to `opensearch-securityconfig` is that, and clears on its own.

> [accordion] A dependency edge was ignored and something deployed before its parent
>
> The shorthand `- addon: name` parses to an empty parent and is dropped without an error. Every parent is `kind` and `name` on two lines. Confirm what was stored with `ankra cluster stacks list <stack> -o json`, which echoes each resource's real `parents`.

> [accordion] OpenSearch Dashboards will not start
>
> Dashboards fetches the realm's discovery document at startup and refuses to start while `staff-login.example.com` is unreachable, password form included. Fix the realm first. The REST API with the `admin` basic credentials still works in the meantime through `ankra cluster exec` on an OpenSearch pod.

> [accordion] Hydra issues http\:// redirect URLs, or oauth2-proxy says the issuer does not match
>
> Two separate causes with the same symptom. `allow_termination_from` must contain the pod CIDR, or Hydra does not trust `X-Forwarded-Proto` from Traefik and emits `http://` everywhere. And the issuer string in Hydra's values and oauth2-proxy's `--oidc-issuer-url` must be identical, trailing slash included.

> [accordion] Microsoft answers AADSTS50011
>
> The redirect URI `https://staff-login.example.com/self-service/methods/oidc/callback/microsoft` is not registered on the Entra application, platform **Web**. Keep `pkce: never` in the Kratos provider: with PKCE on, Kratos switches to the provider-less callback path and the registered URI no longer matches.

> [accordion] Alertmanager fires but nothing reaches the channel
>
> Alertmanager's receiver still holds a placeholder, or the sealed `webhook_url` was never declared in `encrypted_paths` and deployed as ciphertext. `ankra cluster addons values kube-prometheus-stack --cluster infrastructure` shows the live values; the webhook must be a real URL there. Ankra's own notifications are a separate path: `ankra alerts destinations test` proves that one.

> [accordion] A scheduled restore point fails every night
>
> `ankra runs list --kind backup --cluster production` names the run; `ankra runs get <run-id>` shows which asset failed. The usual causes are a VolumeSnapshotClass whose CSI sidecars cannot write snapshot status (a chart RBAC gap - upgrade the CSI add-on), and a database that is `backup-policy`-annotated but whose operator plugin is not yet installed (the data plane shows `installing` in `ankra cluster backups status`).

> [accordion] A stack change deleted a volume
>
> A manifest was renamed, or a namespace manifest was removed, with a StorageClass that reclaims on delete. The retain class in Step 3 is the guard; the PersistentVolume still exists and can be re-bound. [Protect Persistent Data](/guides/protect-persistent-data) walks through it.

***

## Next steps

> [card] [Turn the hub into a stack profile](/concepts/stack-profiles)
>
> Parameterise the domain, the tenant and the storage class, and launch the same infrastructure for the next region in one apply.

> [card] [Ship an application to production](/guides/deliver-your-app)
>
> Connect a repository, build and scan on Ankra Pipelines, publish to the Harbor you just built, and deploy to the production cluster on merge.

> [card] [Connect the clusters with Cluster Mesh](/platform/cluster-mesh)
>
> Let a service on production reach the hub's Tempo or OpenSearch over the WireGuard overlay instead of a public endpoint.

> [card] [Compliance evidence](/security/compliance-management)
>
> Map the scanner coverage, the access grants and the backup posture you now have onto a framework.


# Prompt to Production
Source: https://docs.ankra.ai/use-cases/prompt-to-production

A four-stage developer flow for building a production-grade app with AI agents on Ankra - plan with evidence, storyboard before code, orchestrate the build on a fixed stack, then prove development in a real browser before production exists. Includes the four prompts, the agent contract to commit, and the evidence an agent must attach before it says done.

An agent can write an app in an afternoon. What decides whether it is fit to run is everything around the code: a plan that looked at what already exists, a design the team agreed to, a build on one stack, and a deployment that was tested before it was trusted.

This page is a flow for that, in four stages. Each stage is **one session with one written prompt**, and the output of a stage is the only input to the next. That is what keeps the agent honest, and it is what makes the result repeatable: the prompts live in your repository and improve like any other file.

> [!NOTE]
>
> **The whole flow in four lines.** Each is a fresh session.
>
> 1. **Define:** "Plan this idea with web search, name the existing tools, and write `docs/plan.md`."
> 2. **Storyboard:** "From the plan, build the screens as an interactive page behind a login, inspired by these links."
> 3. **Orchestrate:** "Spawn sub-agents to build the storyboard on this stack, and get Ankra to run it."
> 4. **Deploy:** "Bring up development, test it in a browser, and only then promote the same tag to production."
>
> The rest of this page is the full prompt for each line and the checks that make it safe.

![Four stages in a row. Define produces a plan. Storyboard takes only the plan and produces screens and journeys, served for review behind authentication. Orchestrate takes the storyboard and has sub-agents build it on a fixed stack as pull requests. Deploy and verify brings up development first, tests it in a real browser, and only then promotes the tag that passed to production. Done means evidence: test output, image tag and digest, scan summary, browser recording, public URL and rollback command.](https://mintcdn.com/ankra/kzSQWVfZoEhYa497/images/use-cases/prompt-to-production.svg?fit=max\&auto=format\&n=kzSQWVfZoEhYa497\&q=85\&s=4a60974304fdcb9851b7d0c002b0405f)

Four sessions, four artefacts: a plan, a storyboard, a build, and a verified deployment

***

## What you need

* The Ankra CLI and the agent skills installed for your assistant, as described in [Build it with your AI coding assistant](/use-cases/production-multi-cluster-platform#build-it-with-your-ai-coding-assistant).
* An empty GitHub repository and a [GitHub credential](/platform/credentials/git) in your Ankra organisation that can reach it.
* A development cluster and a production cluster. Development is where the agent may create and delete anything. Production is where it may not, without you.
* The tools the agent verifies with: a browser it can drive (for example Claude in Chrome), and a way to tell the team when it is live (for example a Slack integration). Both are optional, and both make the last stage much stronger.
* Optionally, the [Ankra MCP server](/platform/mcp-server), so the agent can read clusters, runs and logs directly instead of through the CLI.

> [!NOTE]
>
> Run each stage in a **fresh session**. A long conversation accumulates stale assumptions, and the artefact from the previous stage is a better memory than the transcript.

***

## Stage 1: Define the idea

The first prompt asks for a detailed plan and forces the agent to look outward: what already exists, what people pay for, which tools would do half the job for free. Only then does it commit to building.

```
Produce a detailed plan for this idea: <one paragraph>.

Use active web search. Most importantly, survey the existing tools in this space
and say where we differ. Treat this as a production-grade app from day one.

Apply industry standards: clean architecture, hexagonal (ports and adapters),
minimal imported libraries, and a clear testing framework with unit, integration
and end-to-end layers.

Database: we use Alembic for migrations. We do not use an ORM; write explicit,
parameterised SQL.

Deliver: problem statement, competitor table, architecture diagram, module
boundaries, data model, test strategy, risks, and a milestone plan. Write it to
docs/plan.md.
```

The standards in the second paragraph are an example set. Replace them with yours. What matters is that they are written down and specific, because every standard you leave out is a decision the agent will make differently on each run.

**A good plan has:**

* Three to five real competitors with links, pricing, and the one thing each does better than you will.
* A sentence per bounded context: what it owns and what it never touches.
* The dependency rule drawn as a diagram, with the database on the outside.
* The test pyramid as a contract: what runs on every commit and what runs nightly.
* Milestones measured in demos, not in weeks.

> [!TIP]
>
> Making web search part of the prompt is how you stop the plan from quietly rebuilding something that already exists as a well-funded open-source project. A model's training data is a snapshot; pricing, licences and whether a project is still maintained all change monthly.

***

## Stage 2: Storyboard

A fresh session takes only the plan. It produces a storyboard: every screen, every journey, every empty and error state, reusing the logos, palettes and components you already own.

```
Use docs/plan.md and create a storyboard, considering existing assets. Make it
modern. These products hold design and values I like; study them and use them
as inspiration: <link 1> <link 2> <link 3>.

Deliver the storyboard as an interactive HTML page, served on an Ankra-automated
domain with auth access so the team can review it.
```

Links steer taste better than adjectives. "Modern and clean" means nothing to an agent; three URLs of products you admire give it concrete spacing, type, motion and tone to read and match.

### Serve it for review

The storyboard goes live on a subdomain of the cluster's generated `ankra.cc` domain behind basic authentication, with a Let's Encrypt certificate, so the review is a URL and not an attachment. The agent can do this from the prompt above. The shape it produces is a stack of seven manifests: a namespace, a ConfigMap holding the page, a Secret holding the password hash, a Traefik middleware, a Deployment of an unprivileged nginx, a Service and an Ingress.

```bash theme={null}
htpasswd -nbB reviewer '<a-long-random-password>'
```

The output line is the value of the Secret's `users` key, sealed with `ankra cluster encrypt manifest` before it is committed. The two manifests that make it private:

```yaml theme={null}
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: storyboard-auth
  namespace: storyboard
spec:
  basicAuth:
    secret: storyboard-auth
    realm: Storyboard review
```

```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: storyboard
  namespace: storyboard
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    traefik.ingress.kubernetes.io/router.middlewares: storyboard-storyboard-auth@kubernetescrd
spec:
  ingressClassName: traefik
  rules:
    - host: storyboard.<cluster-short-id>.<org-short-id>.ankra.cc
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: storyboard
                port:
                  number: 80
  tls:
    - hosts:
        - storyboard.<cluster-short-id>.<org-short-id>.ankra.cc
      secretName: storyboard-tls
```

> [!WARNING]
>
> Manifest names are unique across the whole cluster, not per stack, so prefix every manifest with the stack's name. Give the review password to the team out of band, never in the repository.

***

## Stage 3: Orchestrate

The third session gets the storyboard and a hard constraint: the technology choices are already made. Its job is to spawn as many sub-agents as the work needs, keep them on the same stack, and let Ankra build the platform underneath.

```
You are the orchestrator. Your job is to spawn as many sub-agents as you need to
get this storyboard live.

Our preferred framework is Next.js and Go. We use PostgreSQL, and caching is
Redis. If we need a time-series database, TimescaleDB is where that lives.

Get Ankra to build this up to production: pipeline, registry, secrets,
environments. Read docs/plan.md and the storyboard first.
```

Naming the stack removes the biggest source of agent drift, which is re-litigating technology every time a sub-agent starts. The stack above is an example; name yours.

**How the orchestrator splits the work:**

* One agent per bounded context from the plan.
* One agent owns the schema and its migrations.
* One agent owns the test harness and the fakes for every port.
* One agent owns the Ankra application and its pipeline.
* The orchestrator integrates and reviews. It never writes code itself.

### The agent contract

A prompt is one conversation. A contract is every conversation. Put the standards, the tools and the gates where the agent reads them automatically, so the fourth session behaves like the first.

| In the repository | What it holds |
| - | - |
| `AGENTS.md` | Architecture, naming, "no ORM", the test contract, the stack, what is forbidden |
| `.ankra/pipeline.yaml` | What runs on every push and merge: test, build, scan, gate, publish |
| `.claude/skills/` | Repeatable procedures, loaded on demand: how to add a migration, how to ship a service |
| `.claude/settings.json` | Hooks that run lint and tests before every commit and the full suite before every push |
| `docs/adr/` | One record per architectural decision, so the next session reads why and not just what |

* **Skills over long prompts.** Package "how we add a migration" as a skill. The orchestrator invokes it by name and sub-agents inherit the same procedure.
* **One worktree per agent.** Parallel sub-agents never share a checkout. Each gets its own worktree and branch, and the orchestrator merges through pull requests.
* **Hooks are the hard gate.** The harness runs the tests, so the agent cannot forget to.
* **Permission modes match the blast radius.** Planning is read-only. Building edits a worktree. Deploying to development may create and delete freely. Deploying to production needs a human.

Ankra's own [agent skills](/integrations/agent-skills) cover the platform half of this contract, so the agent knows the CLI, the YAML and the order of operations without you teaching it.

***

## Stage 4: Deploy and verify

Development first. Production only after the gate.

> [card] Development
>
> A cluster with its own `.dev` domain. The agent may create and delete any resource. It must test the product in a real browser: sign up, sign in, every journey in the storyboard and every error state. Tests, build, Semgrep, Checkov and Trivy are green; migrations apply and reverse; logs and metrics are visible in Ankra.

> [card] Production
>
> A separate cluster with the `.com` domain, not brought online until development is online and fully tested. Nothing is created here by hand: the same pipeline promotes the same immutable image tag. Secrets and variables are set per environment, DNS and TLS are automated.

```
Deploy this solution to a development and a production cluster. Give development
a .dev domain and production a .com domain.

Do not bring production online until development is online and fully tested,
including using my Chrome MCP to navigate the platform and test everything. You
may create and delete any resource in development.

Once it is live, use the Slack MCP to update the team with the URL.
```

The Ankra half of what the agent does:

```bash theme={null}
ankra application ship . --cluster <dev-cluster>
ankra pipeline get --application <application-id> --latest --wait --exit-code
ankra application deployments <application-id>
```

When development passes, the tag that was tested is the tag that is promoted. First, in the portal, open the application's **Settings** → **Push to deploy** and, under **What follows pushes**, leave development on and turn production off, so production never follows a push. Then promote:

```bash theme={null}
ankra application deploy <application-id> \
  --cluster <prod-cluster-id> \
  --set image_tag=sha-<the-tag-that-passed> \
  --set ingress_enabled=true \
  --set ingress_host=app.example.com
```

`ankra application auto-deploy set <application-id> --enabled=false` is not the same switch: it turns push to deploy off for every environment, so development would stop following merges too. Secrets and variables are set per environment, and the pipeline never builds for production. See [Ship your app](/guides/deliver-your-app) for the route in detail and [Lovable to Ankra](/use-cases/lovable-to-ankra) for a worked example of one image serving two environments.

***

## Make "done" mean evidence

"Done" is a claim. Evidence is the deliverable. Append this to any stage prompt:

```
Before you report done, attach the evidence: the test runner output, the image
tag and digest, the scan summary, a browser recording of every storyboard
journey, a curl of the public URL, and the exact rollback command. If any item
is missing, you are not done.
```

| Evidence | What counts |
| - | - |
| Tests | The runner's output pasted in, not "tests pass" |
| Build | The immutable `sha-` tag and its digest |
| Scan | The Semgrep, Checkov and Trivy findings, or an explicit zero |
| Browser | A recording of every journey in the storyboard |
| Public | DNS resolves, the certificate is valid, the URL returns 200 |
| Rollback | The previous tag redeploys with one command |

The loop is build, verify, read the evidence, fix, verify again. The agent runs it, and you read the evidence before the code. Add reviewers for the reviewer: a second agent reviews the pull request with no memory of writing it, and Ankra AI reviews every pull request and watches every pipeline run.

***

## Day 2: keeping it in production

* **Supply chain.** Every push builds rootless in your cluster, is scanned by Semgrep, Checkov and Trivy, and publishes an immutable `sha-` tag. No tag is ever overwritten.
* **Secrets.** Nothing in plaintext. SOPS-encrypted manifests in Git ([SOPS](/guides/sops)), per-environment secrets in the platform, and least-privilege tokens for every integration.
* **Observability.** Metrics, logs and events from day one. The agent can query Prometheus and read pod logs, so "why is it slow" is a prompt and not a war room. See [Cluster metrics](/platform/cluster-metrics).
* **Promotion and rollback.** The same image moves from development to production through the pipeline, and rolling back is redeploying the previous tag.
* **Alerts that reach people.** Route pipeline failures, blocked images and cluster events to your channel. See [Notification routing](/guides/notification-routing).
* **Backups.** Protect every stack that holds data into a vault. See [Backups and restore points](/guides/backups).

***

## Prompt like a tech lead

> [accordion] One stage, one session
>
> Planning, design, building and shipping each get a fresh context with only the previous artefact as input.

> [accordion] Name the constraints up front
>
> Stack, database, migration tool, and what you refuse to use. Every unstated preference is a decision the agent will make differently each time.

> [accordion] Demand evidence
>
> "Use web search", "cite the competitor", "show the test output". The verb in your prompt decides whether you get a plan or a guess.

> [accordion] Write prompts that are reusable
>
> If a prompt works, it is a template. Keep the four stage prompts in the repository and improve them the way you improve CI configuration.

> [accordion] Give it the tools, not the answers
>
> A browser, Slack, the Ankra CLI, the repository. An agent that can verify its own work needs far less supervision than one that can only talk.

> [accordion] Gate promotion on verification
>
> Development must be seen working, in a browser, by the agent, before production exists. Put the gate in the prompt so it is never forgotten.

***

## Next steps

> [card] [Lovable to Ankra](/use-cases/lovable-to-ankra)
>
> Already built the app in a visual builder? Take it from its repository to production.

> [card] [Production multi-cluster platform](/use-cases/production-multi-cluster-platform)
>
> The infrastructure around a fleet: central metrics, logs, sign-in, backups and alerts.

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> Every stage the pipeline runs, and how the gate decides what may publish.

> [card] [Agent Skills](/integrations/agent-skills)
>
> Install Ankra's skills into Claude Code, Cursor, Codex, Copilot and more.


# Self-host an AI agent observability backend on-prem
Source: https://docs.ankra.ai/use-cases/self-host-ai-agent-observability

Run Moyai's AI agent observability backend on your own Kubernetes cluster from one shared stack profile - the trace API, highly available Postgres, S3 object storage, an Iceberg REST catalog, an LLM and Prometheus - on Proxmox, HPE Morpheus, an imported cluster or any cloud, in a handful of commands.

Your agent traces stay in your network. Moyai packages its whole backend as one Ankra stack profile, shares it with your organisation, and you apply it to a cluster you already run. Ankra deploys it, keeps it reconciled, and rolls out every new version Moyai publishes.

There is no Helm chart to assemble and no runbook to follow. The profile pins every component, orders them, and asks you only for what is yours: your secrets, your sizes and where the LLM lives.

![The vendor shares the moyai-observatory stack profile with your Ankra organisation. You apply it with a dry run, bind the secrets and deploy, and Ankra runs it on Proxmox VE, HPE Morpheus, an imported cluster or any cloud. On the cluster your AI agents send traces to the easterisland API, which uses Postgres with three CloudNativePG instances, SeaweedFS S3 for uploads and the Iceberg trace lake, a Lakekeeper Iceberg REST catalog and an OpenAI-compatible LLM. A lean Prometheus scrapes every component.](https://mintcdn.com/ankra/7gX3GqCMvxlpaCaA/images/use-cases/self-host-ai-agent-observability.svg?fit=max\&auto=format\&n=7gX3GqCMvxlpaCaA\&q=85\&s=ee33040c9334f45372dfe356c64bd41c)

One shared profile puts the whole backend on your cluster

***

## What runs

Everything lands in one Stack, `moyai-observatory`, in the order each part needs.

| Component | What it is | Namespace |
| - | - | - |
| `easterisland` API | Trace upload and ingest, triage, evidence and incident reports | `easterisland` |
| Postgres | Two CloudNativePG clusters (the API's and the catalog's), three instances each by default, with automatic failover | `easterisland` |
| Object storage | SeaweedFS with an S3 API, holding uploaded traces and the Iceberg trace lake | `easterisland` |
| Iceberg REST catalog | Lakekeeper, the table catalog the API queries the trace lake through | `easterisland` |
| LLM | An OpenAI-compatible endpoint for the analysis pipeline: a small in-cluster CPU model, or yours | `easterisland` |
| CloudNativePG operator | Runs the Postgres clusters | `cnpg-system` |
| Prometheus | A lean kube-prometheus-stack (no Grafana or Alertmanager, 3 days of data) that scrapes every component | `monitoring` |

The API is internal to the cluster unless you publish it on a host of your own.

***

## What you need

* An Ankra organisation that Moyai has shared the `moyai-observatory` profile with. Send Moyai your organisation slug (under organisation settings); they grant the share, and the profile appears in your catalogue. See [Share with specific organisations](/concepts/stack-profiles#share-with-specific-organisations).
* A cluster in that organisation, wherever you run Kubernetes:
  * On-prem: [Proxmox VE](/guides/proxmox-clusters) or [HPE Morpheus](/guides/morpheus-clusters) (closed beta), which Ankra builds for you.
  * A cluster you already run: [import it](/guides/import-cluster) with one command.
  * Any cloud Ankra supports.
* About 4 vCPU and 8 GiB of memory free, and a StorageClass. For three Postgres instances, use three nodes so each replica lands on its own.
* The pull credentials and the WorkOS client ID Moyai issues you.
* The [Ankra CLI](/integrations/ankra-cli), or the portal: every step below is also **Stack Profiles** > **moyai-observatory** > **Use Profile**.

***

## Install

**1. See what the profile asks for**

```bash theme={null}
ankra stack-profiles get moyai-observatory
ankra stack-profiles apply moyai-observatory --cluster my-cluster --dry-run
```

The dry run creates nothing. It prints every input with the value it would deploy with and where that value came from: your `--set`, a choice, or the default. Five inputs are secrets with no default, and the dry run lists them as unset until you bind them.

**2. Write the secrets to files**

Secrets are bound from files, so they never reach your shell history. You choose the S3 keys and the catalog key yourself:

```bash theme={null}
umask 077 && mkdir -p observatory-secrets && cd observatory-secrets
openssl rand -hex 10 > s3-access-key-id
openssl rand -hex 20 > s3-secret-access-key
openssl rand -hex 32 > catalog-encryption-key
printf 'unused' > llm-api-key        # your LLM endpoint's key, if it needs one
printf '{"auths":{"%s":{"auth":"%s"}}}' "$REGISTRY" \
  "$(printf '%s:%s' "$PULL_USER" "$PULL_TOKEN" | base64)" > pull-secret.json
```

`REGISTRY`, `PULL_USER` and `PULL_TOKEN` are the pull credentials Moyai gave you. Keep this directory: upgrades bind the same files.

**3. Apply, review, deploy**

```bash theme={null}
ankra stack-profiles apply moyai-observatory --cluster my-cluster \
  --set workos_client_id=client_XXXXXXXX \
  --set-file manifest.registry-credentials.stringData..dockerconfigjson=pull-secret.json \
  --set-file manifest.object-storage-credentials.stringData.access-key-id=s3-access-key-id \
  --set-file manifest.object-storage-credentials.stringData.secret-access-key=s3-secret-access-key \
  --set-file manifest.catalog-credentials.stringData.encryption-key=catalog-encryption-key \
  --set-file manifest.llm-credentials.stringData.api-key=llm-api-key
```

Without `--deploy` this creates a reviewable Stack draft on the cluster. Read it in the Stack builder, then deploy it there, or run the same command again with `--deploy`. The secrets are sealed with SOPS before they reach the cluster's GitOps repository.

Add `--set` for anything you want to change from the default:

| Input | Default | Set it when |
| - | - | - |
| `database_instances` | `3` | `1` for a small or evaluation install |
| `database_storage` | `5Gi` | Each Postgres instance needs more room |
| `object_storage_size` | `20Gi` | You keep more traces |
| `storage_class` | empty (the cluster default) | Your cluster has no default class, for example `local-path` or `longhorn` |
| `api_exposure` | `internal` | `public`, with `public_host`, to publish the API over HTTPS |
| `public_host` | empty | The API's hostname, for example `observatory-api.example.com` |
| `cluster_issuer` | `letsencrypt-prod` | Your certificates come from an internal CA issuer |
| `api_ingress_class` | set by `api_exposure` | Your ingress controller is not Traefik |
| `otel_dev_mode` | `false` | Never on a shared cluster: `true` turns authentication off |

`ankra stack-profiles apply` takes `--cluster` more than once, so the same command installs the backend on several clusters at a time.

***

## Choose the LLM

The analysis pipeline calls one OpenAI-compatible endpoint. Pick where it lives with `llm_mode`; the choice sets the model, the endpoint and whether the demo model runs.

> [tab] In-cluster CPU demo
>
> The default. llama.cpp serves Qwen2.5 0.5B on CPU inside the Stack, with about 1 GiB of memory. It needs no GPU and no key, and it is right for evaluation, not for production analysis.
>
> ```bash theme={null}
> --set llm_mode=in-cluster-demo
> ```

> [tab] Your own GPU with vLLM
>
> Serve a stronger model on your own GPUs, for example with the public `gpu-chat` stack profile or any vLLM deployment, and point the backend at it. The demo model scales to zero.
>
> ```bash theme={null}
> --set llm_mode=external \
> --set llm_base_url=http://vllm.inference.svc:8000/v1 \
> --set llm_model=qwen3-8b
> ```

> [tab] An OpenAI-compatible API
>
> Any hosted endpoint or gateway that speaks the OpenAI API. Put its key in `llm-api-key` before you apply.
>
> ```bash theme={null}
> --set llm_mode=external \
> --set llm_base_url=https://api.openai.com/v1 \
> --set llm_model=gpt-4.1-mini
> ```

***

## Verify

```bash theme={null}
ankra cluster get pods -n easterisland --cluster my-cluster
ankra cluster exec <easterisland-pod> -n easterisland --cluster my-cluster -- \
  python -c "import urllib.request as r; [print(p, r.urlopen('http://localhost:8000' + p).read().decode()) for p in ('/health', '/health/db', '/health/s3', '/health/trace-lake')]"
ankra cluster exec prometheus-kps-prometheus-0 -n monitoring -c prometheus --cluster my-cluster -- \
  promtool query instant http://localhost:9090 'up{namespace="easterisland"}'
```

All pods are `Running` and ready (the `create-buckets` and `create-warehouse` jobs `Completed`), the four health checks answer healthy, and every Prometheus target returns `1`: the API database, SeaweedFS, the catalog and, when it runs, the demo LLM.

Then upload one trace end to end. With a WorkOS token in the `X-Moyai-Authorization: Bearer <token>` header, the API under `/internal/v1/uploads` takes four calls: create the upload record (`POST`), ask for a presigned URL (`POST /{upload-id}/presigned-url`), `PUT` the JSONL file to that URL, and start processing (`POST /{upload-id}/process`). `GET /internal/v1/uploads/{upload-id}` then reports its progress until the incident report is ready.

> [!NOTE]
>
> The presigned URL points at the in-cluster S3 service, so run the upload from inside the cluster or from a network that reaches it.

***

## Upgrades

Moyai publishes new versions of the profile; you choose when each cluster takes one. A rollout replaces the Stack's contents in place, so Kubernetes rolls the workloads and the data stays where it is.

```bash theme={null}
ankra stack-profiles deployments moyai-observatory --outdated
ankra stack-profiles diff moyai-observatory --from 1 --to 2
ankra stack-profiles rollout moyai-observatory --cluster my-cluster --version 2 --dry-run
ankra stack-profiles rollout moyai-observatory --cluster my-cluster --version 2 \
  --set-file manifest.object-storage-credentials.stringData.access-key-id=s3-access-key-id \
  --set-file manifest.object-storage-credentials.stringData.secret-access-key=s3-secret-access-key \
  --set-file manifest.catalog-credentials.stringData.encryption-key=catalog-encryption-key \
  --set-file manifest.llm-credentials.stringData.api-key=llm-api-key \
  --set-file manifest.registry-credentials.stringData..dockerconfigjson=pull-secret.json
```

Your non-secret inputs carry forward; pass the same secret files again. Never apply the profile a second time to upgrade: that creates a second Stack beside the first. Protect the Stack into a [backup vault](/guides/backups) before the first upgrade, so a restore point exists if a version misbehaves.

***

## Air-gapped clusters

The profile reaches the internet for three things: container images, the embedding model the API loads at startup, and the weights of the demo LLM. Each has a local replacement.

* **Images.** Mirror the images into your registry and configure it as a registry mirror on the nodes. Set `image` to your mirrored easterisland reference and bind your registry's pull secret in `pull-secret.json`.
* **Model weights.** Mirror `minishlab/potion-base-32M` and `Qwen/Qwen2.5-0.5B-Instruct-GGUF` into a Hugging Face-compatible mirror inside your network and set `model_mirror_url` to it. With an external LLM, only the embedding model is needed.
* **Helm charts.** Add internal mirrors of the CloudNativePG and prometheus-community charts as [Helm registries](/guides/registries).
* **Certificates.** Keep the API internal, or publish it with `cluster_issuer` set to the cert-manager issuer for your internal CA instead of Let's Encrypt.

***

## Troubleshooting

> [accordion] The easterisland pod is stuck in ImagePullBackOff
>
> The pull secret cannot pull `image`. Check the registry host and credentials in `pull-secret.json`, then bind it again with `rollout` and `--set-file`.

> [accordion] Postgres or SeaweedFS volumes stay Pending
>
> The cluster has no default StorageClass. Set `storage_class` to one that exists.

> [accordion] Authenticated calls answer 500 'No authentication provider configured'
>
> `workos_client_id` is empty. Set it to the client ID Moyai gave you.

> [accordion] The fetch-model init container fails
>
> It cannot reach `model_mirror_url`. Allow egress to Hugging Face, or point it at your mirror.

***

## Next steps

> [card] [Stack profiles](/concepts/stack-profiles)
>
> Versions, choices, sharing and fleet rollouts.

> [card] [Proxmox VE clusters](/guides/proxmox-clusters)
>
> Build the cluster on your own hardware.

> [card] [Backups and restore points](/guides/backups)
>
> Protect the trace lake and the databases.

> [card] [Build a Monitoring Stack](/guides/monitoring-stack)
>
> Add Grafana, Alertmanager and logs on top of the bundled Prometheus.


# Speed Up CI
Source: https://docs.ankra.ai/use-cases/speed-up-ci

Run only the work a change needs, and publish the image that was already tested. Ready-to-paste pipeline.yaml examples and real timings from Ankra's own pipelines.

Most CI time goes on work a change did not need: backend tests for a frontend fix, or a second build of a commit its pull request already built and tested. Ankra Pipelines skips that work with a few lines of `.ankra/pipeline.yaml`, and never skips anything it cannot prove the change left alone.

![Four steps. A pull request runs only the stages its files touch. The image is built once, scanned and gated by digest. The merge train tests the pull request as it will merge. Publish re-tags the tested image instead of building it again. Below them: if Ankra cannot see every changed file, nothing is skipped.](https://mintcdn.com/ankra/YXyjjLuuqrU4Bw7Z/images/use-cases/speed-up-ci.svg?fit=max\&auto=format\&n=YXyjjLuuqrU4Bw7Z\&q=85\&s=9b49b3ed5618c65d8e883d54e2572830)

## What it saves

Timings from Ankra's own pipelines.

> [card] 15 seconds from merge to published
>
> A TypeScript frontend with 20-minute pull request runs. Its last 40 merges re-tagged the image the pull request had already built and tested.

> [card] About 3 minutes instead of 19
>
> A Go and Next.js repository. A pull request that does not touch the backend skips its 17 minutes of tests.

> [card] About 60 CPU minutes per merge
>
> A Go, TypeScript and Rust monorepo. Three rarely touched stages, one a 10-minute suite, now run only when their files change. Estimated from stage timings.

## Which technique to use

| You want to | Use |
| - | - |
| Run nothing when a change only touches documentation | [`on.<event>.paths`](#skip-documentation-only-changes) |
| Run a pull request's checks only for what it touches, and everything on main | [`when.pull_request`](#run-only-the-tests-a-change-touches) |
| Skip a component's tests on every event when its files did not change | [`paths:` on the stage](#run-only-the-tests-a-change-touches) |
| Skip a component's tests when nothing it imports changed, across modules and workspace packages | [`affected:` on the stage](#run-only-the-tests-a-change-touches) |
| Stop building and testing a commit again after its pull request did | [`promote_from`](#build-once-and-promote-on-merge) |
| Test each pull request on top of the latest main | [Merge train](#test-each-pull-request-as-it-will-merge) |
| Run slow suites less often | [`on.schedule`](#run-slow-suites-nightly) |
| Write a list of paths once and use it on many stages | [`path_sets`](#write-each-path-list-once) |
| Run everything anyway, or keep a stage from ever being skipped | [Full runs and always-run stages](#run-everything-when-you-need-to) |

They combine. A typical setup is pull-request-only filters on the expensive tests, `promote_from` on `publish`, and the merge train on the default branch.

## Skip documentation-only changes

A trigger `paths` list that starts with `!` means "everything except". A change that only touches the excluded files runs no stage, and the run is recorded as skipped. Name the list once in `path_sets:` and both triggers use it.

```yaml theme={null}
path_sets:
  not-docs: ["!docs/**", "!*.md", "!.github/**"]
on:
  push:
    branches: [main]
    paths: {set: not-docs}
  pull_request:
    branches: [main]
    paths: {set: not-docs}
```

A pull request that changes only `docs/intro.md` and `README.md` is skipped with the reason "Every file this event changed falls outside the paths this pipeline's trigger declares." One that also changes `api/README.md` runs, because `*.md` matches only files at the repository root.

> [accordion] Full pipeline.yaml
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: shop
> path_sets:
>   not-docs: ["!docs/**", "!*.md", "!.github/**"]
> on:
>   push:
>     branches: [main]
>     paths: {set: not-docs}
>   pull_request:
>     branches: [main]
>     paths: {set: not-docs}
> defaults:
>   network: egress-https
> stages:
>   - name: checkout
>     kind: checkout
>   - name: test
>     kind: run
>     image: golang:1.26
>     run: go test ./...
>     needs: [checkout]
> ```

> [accordion] How path patterns match
>
> * Patterns match file paths from the repository root: `api/**`, never `./api/**` or `/api/**`.
> * `*` matches any characters except `/`, `**` matches any characters including `/`, and `?` matches one character.
> * A pattern matches whole file names, so `docs/` matches nothing. Write `docs/**`.
> * `!` removes what a pattern matches, and the last pattern that matches a file decides: `["web/**", "!web/**/*.md"]` is the web directory without its Markdown files.
> * Matching is case-sensitive.
> * Exclude a file type everywhere (`**/*.md`) only when nothing your build or tests read has that type. Code that embeds Markdown prompts or templates needs its tests to run when they change.
> * `ankra pipeline validate` warns about a pattern that can match no file (a leading `./` or `/`, a trailing `/`, a backslash) and names the pattern to write instead.

## Run only the tests a change touches

Filter each expensive test stage on the files it covers. Choose whether the filter applies to pull requests only or to every event.

> [tab] Pull requests only
>
> Pull requests skip the tests of components they do not touch, and every push to main still runs everything. This is the safest place to start, and the technique behind the "About 3 minutes instead of 19" example.
>
> ```yaml theme={null}
> - name: backend-test
>   kind: run
>   image: golang:1.26
>   run: go test ./...
>   when:
>     pull_request:
>       paths: ["backend/**"]
>     push: {}
> ```
>
> A pull request that changes only `frontend/src/app.tsx` skips `backend-test` with reason `path_filter`. A stage that needs a filtered stage is skipped with it, unless it lists it in `skippable_needs` (see **Later stages and conditions**).
>
> > [accordion] Full pipeline.yaml
> >
> > ```yaml theme={null}
> > apiVersion: ankra.io/v1
> > kind: Pipeline
> > metadata:
> >   name: shop
> > on:
> >   push:
> >     branches: [main]
> >   pull_request:
> >     branches: [main]
> > defaults:
> >   network: egress-https
> > stages:
> >   - name: checkout
> >     kind: checkout
> >   - name: backend-test
> >     kind: run
> >     image: golang:1.26
> >     run: go test ./...
> >     working_directory: backend
> >     needs: [checkout]
> >     when:
> >       pull_request:
> >         paths: ["backend/**"]
> >       push: {}
> >   - name: frontend-test
> >     kind: run
> >     image: node:24
> >     run: corepack enable && pnpm install --frozen-lockfile && pnpm run test
> >     working_directory: frontend
> >     needs: [checkout]
> >     when:
> >       pull_request:
> >         paths: ["frontend/**"]
> >       push: {}
> > ```

> [tab] Every event
>
> A stage with `paths:` is **affected-only**: when no changed file matches, it is skipped on every event, pushes included, and the stages that need it still run, each waiting on what the skipped stage waited on. The image is still built, scanned, gated and published.
>
> ```yaml theme={null}
> - name: test-api
>   kind: run
>   image: golang:1.26
>   run: go test ./...
>   working_directory: api
>   needs: [checkout]
>   paths: ["api/**", "go.work"]
> ```
>
> A push that changes `web/app.ts` skips `test-api`, and `build` waits for `test-web`, and for `checkout` in place of `test-api`. `ankra pipeline validate` refuses `paths:` where a skip would be unsafe: a stage whose outputs another stage reads, a `build` another stage needs, a `checkout`, `gate` or `approval`, a scan a gate judges, or a stage a release bundle build packs. It warns when an affected-only stage that another stage needs declares `artifacts:`.
>
> > [accordion] Full pipeline.yaml
> >
> > ```yaml theme={null}
> > apiVersion: ankra.io/v1
> > kind: Pipeline
> > metadata:
> >   name: shop
> > on:
> >   push:
> >     branches: [main]
> >   pull_request:
> >     branches: [main]
> > defaults:
> >   network: egress-https
> > stages:
> >   - name: checkout
> >     kind: checkout
> >   - name: test-web
> >     kind: run
> >     image: node:24
> >     run: corepack enable && pnpm install --frozen-lockfile && pnpm -C web run test
> >     needs: [checkout]
> >     paths: ["web/**", "packages/ui/**"]
> >   - name: test-api
> >     kind: run
> >     image: golang:1.26
> >     run: go test ./...
> >     working_directory: api
> >     needs: [checkout]
> >     paths: ["api/**", "go.work"]
> >   - name: build
> >     kind: build
> >     needs: [test-web, test-api]
> >     build:
> >       dockerfile: Dockerfile
> >   - name: scan
> >     kind: scan
> >     needs: [build]
> >     scan:
> >       scanners: [semgrep, trivy]
> >   - name: gate
> >     kind: gate
> >     needs: [scan]
> >   - name: publish
> >     kind: publish
> >     needs: [gate]
> >     when:
> >       events: [push]
> > ```

> [tab] From the dependency graph
>
> Name the packages a stage tests instead of listing their files. Ankra follows the imports, so a change to a shared library reaches every stage that uses it, even from another Go module or pnpm workspace package, and a change to anything else skips it. Like `paths:`, the stages that need a skipped stage still run.
>
> ```yaml theme={null}
> - name: test-api
>   kind: run
>   image: golang:1.26
>   run: go test ./...
>   working_directory: api
>   needs: [checkout]
>   affected:
>     go: ["./..."]
>   paths: ["migrations/**"]
> ```
>
> A change to `libs/auth/token.go`, which `api` imports through a `replace` directive in `api/go.mod`, runs `test-api`. A change to `web/app.ts` skips it as not affected. `paths:` adds the files the tests read at run time, which no import graph sees. The run's checkout reads the graph of the exact commit it tested in a few seconds; a stage it cannot answer for runs.
>
> > [accordion] Full pipeline.yaml
> >
> > ```yaml theme={null}
> > apiVersion: ankra.io/v1
> > kind: Pipeline
> > metadata:
> >   name: shop
> > on:
> >   push:
> >     branches: [main]
> >   pull_request:
> >     branches: [main]
> > defaults:
> >   network: egress-https
> > stages:
> >   - name: checkout
> >     kind: checkout
> >   - name: test-api
> >     kind: run
> >     image: golang:1.26
> >     run: go test ./...
> >     working_directory: api
> >     needs: [checkout]
> >     affected:
> >       go: ["./..."]
> >     paths: ["migrations/**"]
> >   - name: test-web
> >     kind: run
> >     image: node:24
> >     run: corepack enable && pnpm install --frozen-lockfile && pnpm --filter @acme/web... test
> >     needs: [checkout]
> >     affected:
> >       pnpm: ["@acme/web"]
> >   - name: build
> >     kind: build
> >     needs: [test-api, test-web]
> >     build:
> >       dockerfile: Dockerfile
> >   - name: scan
> >     kind: scan
> >     needs: [build]
> >     scan:
> >       scanners: [semgrep, trivy]
> >   - name: gate
> >     kind: gate
> >     needs: [scan]
> >   - name: publish
> >     kind: publish
> >     needs: [gate]
> >     when:
> >       events: [push]
> > ```

> [tab] Later stages and conditions
>
> `skippable_needs` keeps a later stage running when a stage it needs was skipped for its paths. `if:` covers rules a path list cannot express, using `event.changed_files` and `event.kind`.
>
> ```yaml theme={null}
> - name: e2e
>   needs: [checkout, frontend-test]
>   skippable_needs: [frontend-test]
> - name: migrations-check
>   needs: [checkout]
>   if: "event.kind == 'push' || event.changed_files.exists(f, f.startsWith('db/migrations/'))"
> ```
>
> A pull request that changes only `backend/main.go` skips `frontend-test` (`path_filter`) and `migrations-check` (`condition_false`), and still runs `e2e`. An `if:` that calls a status function such as `always()` also runs when a need was skipped, and `needs.<stage>.result` reads `skipped`.
>
> > [accordion] Full pipeline.yaml
> >
> > ```yaml theme={null}
> > apiVersion: ankra.io/v1
> > kind: Pipeline
> > metadata:
> >   name: shop
> > on:
> >   push:
> >     branches: [main]
> >   pull_request:
> >     branches: [main]
> > defaults:
> >   network: egress-https
> > stages:
> >   - name: checkout
> >     kind: checkout
> >   - name: frontend-test
> >     kind: run
> >     image: node:24
> >     run: corepack enable && pnpm install --frozen-lockfile && pnpm run test
> >     working_directory: frontend
> >     needs: [checkout]
> >     when:
> >       pull_request:
> >         paths: ["frontend/**"]
> >       push: {}
> >   - name: e2e
> >     kind: run
> >     image: mcr.microsoft.com/playwright:v1.56.0-noble
> >     run: corepack enable && pnpm install --frozen-lockfile && pnpm run e2e
> >     working_directory: frontend
> >     needs: [checkout, frontend-test]
> >     skippable_needs: [frontend-test]
> >   - name: migrations-check
> >     kind: run
> >     image: golang:1.26
> >     run: go run ./cmd/migrate --dry-run
> >     needs: [checkout]
> >     if: "event.kind == 'push' || event.changed_files.exists(f, f.startsWith('db/migrations/'))"
> > ```

## Build once and promote on merge

Publish the image the pull request run already built, scanned and tested, instead of building the merged commit again.

```yaml theme={null}
- name: publish
  kind: publish
  needs: [gate]
  when:
    events: [push]
  publish:
    promote_from: pull_request
```

A promoted push runs `publish` alone: it re-tags the gate-approved digest as the push's own `sha-<7>` tag, and push-to-deploy rolls it out. The other stages show as skipped with reason `promoted`, naming the run that passed them. This is the "15 seconds from merge to published" example.

A push is promoted when its commit has the same git tree as a pull request run that passed every stage `publish` needs, under the same approved pipeline authority, within the last 72 hours, from a branch in the repository itself. Anything else builds and tests in full, and the run records why. A stage that a pull-request-only filter skipped did not pass, so that merge builds in full too. A stage the pull request run skipped as not affected (`affected:`) counts when the merge changes no file that run's dependency graph was not asked about, which is the case for a squash of an up-to-date pull request: same tree, so the same answer. A merge that changes more builds in full and reads the graph itself.

> [!NOTE]
>
> `promote_from` is a protected section: an administrator approves it with the default branch's definition, and a pull request cannot turn it on for itself. Pipelines Ankra generates for an application already declare it when their shape allows. A publish that meets a registry timeout or an outage status is retried for up to five minutes before the step fails.

> [accordion] Full pipeline.yaml
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: shop
> on:
>   push:
>     branches: [main]
>   pull_request:
>     branches: [main]
> defaults:
>   network: egress-https
> stages:
>   - name: checkout
>     kind: checkout
>   - name: test
>     kind: run
>     image: golang:1.26
>     run: go test ./...
>     needs: [checkout]
>   - name: build
>     kind: build
>     needs: [test]
>     build:
>       dockerfile: Dockerfile
>   - name: scan
>     kind: scan
>     needs: [build]
>     scan:
>       scanners: [semgrep, trivy]
>   - name: gate
>     kind: gate
>     needs: [scan]
>   - name: publish
>     kind: publish
>     needs: [gate]
>     when:
>       events: [push]
>     publish:
>       promote_from: pull_request
> ```

## Test each pull request as it will merge

The merge train tests each pull request squashed onto the latest main, then merges it through GitHub's own merge. When that run passed every stage `publish` needs, `promote_from` publishes its image on the merge.

```bash theme={null}
ankra pipeline train enable --application my-app
ankra pipeline train add 412 --application my-app
ankra pipeline train list --application my-app
```

* A train run uses the pull request's own list of changed files, so the same filters apply. A train run with nothing left to run passes, and is never a source for promotion.
* `--max-cars 3` on `enable` tests three pull requests at once. One that fails leaves the train, and the ones behind it are tested again without it.
* Make the **Ankra merge train** check required on main, and every merge goes through the train.

The merge train runs on GitHub repositories. See [the merge train](/guides/ankra-pipelines#the-merge-train-test-every-pull-request-as-it-will-merge) for what happens when main moves or a car fails.

## Run slow suites nightly

Run a suite that is too slow for every pull request once a night, and cancel a branch's older run when a newer commit arrives.

```yaml theme={null}
on:
  schedule:
    - cron: "0 3 * * *"
      branch: main
      stages: [checkout, e2e-all-browsers]
concurrency:
  group: "${{ ankra.repository.name }}-${{ ankra.ref }}"
  cancel_in_progress: true
```

The schedule's `stages` list restricts the nightly run to those stages, so name every stage they need, `checkout` included. `when.events: [schedule]` on the suite keeps it out of push and pull request runs. A cancelled older run shows as **Superseded**, with a neutral commit status and no failure notification.

> [accordion] Full pipeline.yaml
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: shop
> on:
>   push:
>     branches: [main]
>   pull_request:
>     branches: [main]
>   schedule:
>     - cron: "0 3 * * *"
>       branch: main
>       stages: [checkout, e2e-all-browsers]
> concurrency:
>   group: "${{ ankra.repository.name }}-${{ ankra.ref }}"
>   cancel_in_progress: true
> defaults:
>   network: egress-https
> stages:
>   - name: checkout
>     kind: checkout
>   - name: test
>     kind: run
>     image: node:24
>     run: corepack enable && pnpm install --frozen-lockfile && pnpm run test
>     needs: [checkout]
>   - name: e2e-all-browsers
>     kind: run
>     image: mcr.microsoft.com/playwright:v1.56.0-noble
>     run: corepack enable && pnpm install --frozen-lockfile && pnpm run e2e --project=all
>     needs: [checkout]
>     when:
>       events: [schedule]
> ```

## Write each path list once

A monorepo filters many stages on the same directories, and most of those lists also name the pipeline file. `path_sets:` names each list once. Any path list includes a set with a `{set: <name>}` entry, and a set can include another set.

```yaml theme={null}
path_sets:
  pipeline: [".ankra/**"]
  backend: ["backend/**", {set: pipeline}]
  frontend: ["frontend/**", "packages/ui/**", {set: pipeline}]
```

```yaml theme={null}
- name: backend-test
  kind: run
  image: golang:1.26
  run: go test ./...
  working_directory: backend
  needs: [checkout]
  when:
    pull_request:
      paths: [{set: backend}]
    push: {}
```

Ankra replaces each reference with the set's patterns where it stands, when it reads the file, so the plan is exactly the plan of the lists written out by hand. Changing `pipeline` changes every list that includes it. `ankra pipeline validate` refuses a reference to a set that does not exist and sets that include each other, warns about a set nothing uses, and lists every set with its patterns and the stages that use it. See [Path sets](/guides/pipeline-reference#path-sets).

> [accordion] Full pipeline.yaml
>
> ```yaml theme={null}
> apiVersion: ankra.io/v1
> kind: Pipeline
> metadata:
>   name: shop
> path_sets:
>   pipeline: [".ankra/**"]
>   backend: ["backend/**", {set: pipeline}]
>   frontend: ["frontend/**", "packages/ui/**", {set: pipeline}]
> on:
>   push:
>     branches: [main]
>   pull_request:
>     branches: [main]
> defaults:
>   network: egress-https
> stages:
>   - name: checkout
>     kind: checkout
>   - name: backend-test
>     kind: run
>     image: golang:1.26
>     run: go test ./...
>     working_directory: backend
>     needs: [checkout]
>     when:
>       pull_request:
>         paths: [{set: backend}]
>       push: {}
>   - name: frontend-test
>     kind: run
>     image: node:24
>     run: corepack enable && pnpm install --frozen-lockfile && pnpm run test
>     working_directory: frontend
>     needs: [checkout]
>     when:
>       pull_request:
>         paths: [{set: frontend}]
>       push: {}
>   - name: frontend-lint
>     kind: run
>     image: node:24
>     run: corepack enable && pnpm install --frozen-lockfile && pnpm run lint
>     working_directory: frontend
>     needs: [checkout]
>     when:
>       pull_request:
>         paths: [{set: frontend}]
>       push: {}
> ```

## Run everything when you need to

Skipping is the default only where you asked for it, and you can always set it aside.

* **One run in full.** `ankra pipeline run --full` or `ankra pipeline rerun <run> --full` runs every stage, whatever the path filters say.

* **A pull request in full.** Add the `ankra:full-run` label on GitHub. A full run starts at once, every later push to the pull request runs in full while the label stays, and so does its merge train car.

* **Main in full.** Add a `full_run` block, or have an organisation administrator turn on `ci_full_run_on_default_branch`:

  ```yaml theme={null}
  full_run:
    events: [push]
    branches: [main]
  ```

* **A stage that is never skipped.** List it in the organisation's `ci_always_run_stages`. It runs with every stage it needs, whatever its path filters or the trigger's say, and a pull request cannot change that, because the list is not in the repository.

* **Nothing at all.** A pushed commit with `[skip ci]` in its message records a skipped run. By default that works on every branch but the default branch; `ci_skip_markers` changes where.

Each full run says why on the run page, for example "Path filters were set aside: a full run was requested by user:...". See [Setting path filters aside](/guides/pipeline-reference#setting-path-filters-aside) for every source and setting.

## Why a skip never hides a failure

> [!TIP]
>
> A path filter only skips a stage when Ankra has the complete list of files the change touched. When it cannot be sure, the stage runs, and the run's `paths_unverified` says why.

| Situation | What Ankra does |
| - | - |
| No file list, more than 300 files, a push that created the branch, or a push that rewrote history | Nothing is skipped for its paths: `provider_error`, `unsupported_provider`, `truncated`, `branch_created` or `forced_push` |
| An earlier push to the branch was cancelled or failed | A push's files are counted from the last push run on the branch that succeeded within 30 days, so they are still in the list |
| The change edits `.ankra/pipeline.yaml` | Every path filter is set aside (`plan_definition_changed`) |
| A pull request is retargeted to another base | It is planned again against the new base, and the new check replaces the old one |
| An `if:` can only be decided when its step starts | It reads the run's stored list, and runs when that list is incomplete and the answer depends on it |
| A stage declares `affected:` | It is skipped only when the run's checkout read the graph and answered that no changed file reaches it. An analysis that failed, timed out or found nothing to match runs the stage |
| A push asks to promote | Only an identical tree, the same approved authority, the gate's own digest, within 72 hours, never from a fork |

Pushes and pull requests are filtered the same way on GitHub, GitLab and Bitbucket Cloud, up to 300 changed files.

## Preview before you commit

**1. Plan the pipeline for a change**

`ankra pipeline validate` plans the pipeline for a push and a pull request without running anything. Each `--changed-file` makes the path filters decide for real.

```bash theme={null}
ankra pipeline validate --application my-app \
  --spec-file .ankra/pipeline.yaml \
  --changed-file web/app.ts
```

**2. Read the plan**

The output ends with every stage against every event. For the **Every event** pipeline above:

```text theme={null}
╭──────────┬───────────────────┬────────────────────╮
│ STAGE    │ PUSH              │ PULL_REQUEST       │
├──────────┼───────────────────┼────────────────────┤
│ checkout │ run               │ run                │
│ test-web │ run               │ run                │
│ build    │ run               │ run                │
│ scan     │ run               │ run                │
│ gate     │ run               │ run                │
│ publish  │ run               │ skip: event_filter │
│ test-api │ skip: path_filter │ skip: path_filter  │
╰──────────┴───────────────────┴────────────────────╯
```

**3. Try a few typical changes**

Run it for a documentation edit, one component and two components. The command also reports every refusal and warning above, and exits non-zero only when the pipeline cannot be planned. For stages with `affected:`, run it inside your checkout: it reads the same dependency graph from your working tree and marks each one `run (graph: affected)` or `skip: not affected (graph)`.

## See what you saved

Ankra records the CI time each run did not spend because of a path filter, the dependency graph or a promoted publish, and shows it in three places.

* The run page says what the run skipped, for example "Skipped 3 stages, saved about 14 min of CI time."
* The Pipelines page shows the total for the last 30 days.
* `ankra pipeline get <run-id>` prints the same figure under the run's steps, with one line per saving.

```text theme={null}
Time saved: about 14 min of CI time (3 stages skipped, 1 unknown)
  build: left out by a path filter, about 12 min (median of 20 successful runs of this stage)
  e2e: skipped because build was left out by a path filter, unknown (no history to estimate from)
  test: not run again, the publish was promoted, about 2 min (its time in run <run-id>)
```

Each figure is an estimate from the stage's own recent successful runs in the same repository, or, for a promoted step, the time it took in the run it was promoted from. A stage that has no successful runs yet shows as unknown and is not counted. A stage skipped by a branch filter or a condition is not counted either, because it would not have run anyway. The figure is runner time, so two stages that would have run side by side count twice. Only runs planned after this was released are counted. The [pipeline.yaml reference](/guides/pipeline-reference#time-saved) describes the method and the API routes.

## Next steps

> [card] [Ankra Pipelines](/guides/ankra-pipelines)
>
> How a run happens, the merge train and affected-only stages.

> [card] [pipeline.yaml reference](/guides/pipeline-reference)
>
> Every key, event-scoped filters, expressions and validator diagnostics.

> [card] [Promote a tested image](/guides/pipeline-reference#promote-a-tested-image-instead-of-rebuilding)
>
> Every condition a push must meet to publish a pull request run's image.

> [card] [Get started with Ankra CI](/get-started/ankra-ci)
>
> Connect a repository and get its first commit through a run.


# Vercel to Ankra
Source: https://docs.ankra.ai/use-cases/vercel-to-ankra

Move a Vercel project, usually Next.js, onto your own Kubernetes cluster - start from the Vercel project page with the Ankra Chrome extension, review one Launch Plan that says per service what stays at Vercel and what Ankra runs open source, approve once, and keep API routes, middleware, cron jobs and environment variables working.

Vercel builds and serves your project from its own platform. Ankra builds the same GitHub repository and runs it on your own cluster, behind HTTPS, with every change built and scanned first.

You keep pushing to the same repository. Ankra builds every commit.

***

## What moves, and what it becomes

| On Vercel | On Ankra |
| - | - |
| Next.js build | One container image. When `next.config` sets `output: 'standalone'`, the image carries only the standalone server, its static assets and `public/`. Otherwise it runs `next start` |
| API routes, route handlers, middleware, edge routes | Served by the Next.js server in that container. Nothing to split out |
| `vercel.json` crons | One Kubernetes CronJob per cron entry. It calls the same route on the same UTC schedule, with the `vercel-cron/1.0` user agent and `Authorization: Bearer <CRON_SECRET>` when the app has a `CRON_SECRET` secret, so a route that checks it keeps working |
| `vercel.json` rewrites, redirects and headers | Listed in the setup pull request. Vercel applied them at its edge; on Ankra your own server serves every request, so they have to live in `next.config` (`rewrites()`, `redirects()`, `headers()`) before you move traffic. Ask for the [next.config pull request](#the-nextconfig-pull-request) to have Ankra move them |
| Project environment variables | The application's environment secrets. Bring them over with the extension (below) or enter them in Ankra |
| Preview deployments | [Preview demos](/concepts/applications#preview-demos) on a preview address. The proof run of the setup pull request is compared with Vercel's preview of the same commit ([below](#compared-with-your-vercel-preview)) |
| Your domain | Your own domain with its certificate on the cluster ([Applications](/concepts/applications)) |

The setup pull request contains the Dockerfile, the Kubernetes manifests, the CronJobs, the deploy options (`.ankra/ankra.yaml`) and the build pipeline (`.ankra/pipeline.yaml`). Ankra's AI writes it when you add the repository. You review and merge it.

***

## Vercel storage in the Launch Plan

Ankra reads which Vercel storage the code uses and puts one card per service in the project's Launch Plan. Each card shows how locked in the service is and which choice applies by default. You can change the choice.

| Vercel service | Default | What you can choose instead |
| - | - | - |
| Vercel Postgres (`@vercel/postgres`) | Keep it: `POSTGRES_URL` stays an environment secret | A portability pull request switches to a plain Postgres driver on one connection string, then Ankra runs CloudNativePG in your cluster |
| Vercel KV (`@vercel/kv`) | Keep it | A portability pull request moves to a Redis client on `REDIS_URL`, backed by Valkey in your cluster |
| Vercel Blob (`@vercel/blob`) | Keep it | A portability pull request moves uploads to the S3 API, backed by object storage in your cluster |
| Edge Config (`@vercel/edge-config`) | Keep it | A portability pull request reads the same keys from environment variables, delivered as a ConfigMap |

A portability pull request is opt-in. It adds the open-protocol path beside Vercel's, and the app keeps using Vercel until you set the new variables. Data is copied only when you start a [data migration](#moving-your-data-closed-beta).

***

## Portability pull requests

A portability pull request is a small change to your code that Ankra opens on your repository only when you ask for it. Ankra opens two kinds:

* **A service's portability pull request.** It adds the open-protocol path for a Vercel storage service from the table above, beside Vercel's.
* **The next.config pull request.** It moves your `vercel.json` routing into `next.config`.

### Asking for one

Each portability pull request is an action of the project's Launch Plan, and a plan-level approval covers it like any other action:

1. For a storage service, choose the portability pull request on its card. A Vercel project always offers the next.config pull request.
2. Select the pull request among the actions you approve. It is never selected for you.
3. Open it under the approval with **Open an approved portability pull request** in the [API reference](/api-reference/introduction). It needs `applications.write`. Only you, the approver, can open it, and each approved pull request opens once.

The request answers straight away with the operation that opens the pull request. Ankra reads your repository at the commit the plan was made from and opens the pull request from there. If the branch has moved on since, nothing is opened: analyse the application again and approve the new plan.

### When a person has to make the change

Ankra changes only what it can change with confidence. If it cannot, it opens nothing. The operation fails with the reason, starting with `needs a person:`, for example when `next.config` already defines `redirects()`. Make that change yourself.

### The next.config pull request

The next.config pull request moves the redirects, rewrites and headers from `vercel.json` into `next.config`, and sets `output: 'standalone'` so the image carries only the standalone server. Your existing configuration is kept as it is: the pull request only adds to it. While Vercel builds the app, the moved rules return nothing, so `vercel.json` keeps serving your routing on Vercel until you move traffic.

### After it opens

The [PR shepherd](/concepts/applications#the-pr-shepherd) follows every portability pull request and drives it to ready. Ankra never merges a portability pull request, whatever your merge settings, because it changes your code. You review and merge it.

***

## Moving your data (Closed Beta)

> [!WARNING]
>
> **Closed beta.** Data migration is in closed beta. Where Ankra cannot yet carry out a step for a service, the run stops before anything at the vendor changes, or rolls back, and gives the reason. [Contact support](/platform/support) before relying on it for a production move.

When you choose to move a service into your cluster, the Launch Plan carries a data migration for it. The migration plans the move in steps, and one plan-level approval covers all of them.

Every service moves before one cutover:

1. Ankra copies the data in while your app keeps running on Vercel.
2. It makes each vendor source read-only.
3. It copies what changed since the first copy and checks counts and checksums.
4. It switches your app's variables to the services in your cluster in one change.

The vendor sources then stay read-only for a rollback window, seven days by default. In that window, one command puts the previous variables back and makes the sources writable again. Ankra never deletes data at the vendor. When the window closes, you get a checklist of what to remove there yourself.

| Service | How the data moves |
| - | - |
| Postgres | Ankra reads the source with the connection string you stored, to choose how it moves. It dumps the read-only source into one of your [backup vaults](/guides/backups) and restores the dump into CloudNativePG, then compares row counts and sequences |
| S3-compatible object storage | Every object is copied with its checksum checked, then copied again right before the cutover |

```bash theme={null}
# follow the runs, and roll one back inside its window
ankra application data-migration list <application>
ankra application data-migration get <application> <run-id>
ankra application data-migration rollback <application> <run-id>
```

Vercel Blob is not S3-compatible, so its data is not copied yet.

***

## Compared with your Vercel preview

Before you merge the setup pull request, Ankra's proof run deploys it to an ankra.cc preview and requests its health routes and its home page. For a Vercel project, the proof then requests the same routes on the preview Vercel deployed of the same commit, and compares the two answers.

The comparison looks at the shape of each answer, not its exact bytes:

* the status code
* the content type
* for JSON, the keys two levels deep
* for an HTML page, its title and which of `header`, `nav`, `main` and `footer` it has
* the size, which counts as different only when one answer is more than twice the other

Build ids, nonces and timestamps differ between any two deployments, so they are not compared.

Each route gets one of three results on the proof card in the pull request:

| Result | Meaning |
| - | - |
| **match** | Both previews answered with the same shape |
| **differs** | Both answered, differently. The card names the first difference, for example a different status or page title |
| **unknown** | The routes were not compared. The card says why, for example: Vercel deployed no preview of the commit, the preview was still building, the preview is protected, or a request timed out |

An unknown route is never counted as a match.

A difference is a warning. It does not fail the proof and does not block the pull request. A Vercel preview can differ for good reasons, such as variables set only for previews. Check each difference before you move your domain.

Ankra finds the Vercel preview from the deployment status Vercel's GitHub integration posts on the commit, so the GitHub App Ankra uses must be able to read the repository's deployments. Ankra sends no credential to the Vercel preview. If the preview is protected by Vercel Authentication, its routes show as unknown.

***

## Start from the Vercel project page

The **Ankra — Chat & Deploy** extension for Chrome puts an **Ask Ankra** button on your Vercel project page, and also on Lovable, Claude Design and GitHub repository pages. See [install the extension](/use-cases/lovable-to-ankra#install-the-extension-without-the-chrome-web-store).

**1. See where the project stands**

The button carries a status pill for the project's repository: **Not connected**, **Analysing**, **N decisions**, **Ready to approve**, **Proving**, **Proof failed** or **Live**. The same pill appears on the repository's GitHub pages.

**2. Review the Launch Plan**

Open **Deploy project**. The extension fills in the GitHub repository the Vercel project builds and its branch. The **Launch Plan** panel lists:

* the decisions only you can make, with their defaults
* per external service, what stays at Vercel and what Ankra runs open source
* the result of the proof run of the setup pull request

To change a decision, use **Change decisions in Ankra**. All configuration stays in Ankra.

**3. Bring your variables**

Under **Bring variables from Vercel**, paste a Vercel access token for the project's team and choose **Read variables**. The token is used from your browser only and is not stored or sent to Ankra.

By default you get the names of the project's production variables, marked by whether Ankra already has each one. Tick the box to copy the values into the application's encrypted secrets. Values Ankra already holds are never overwritten. Variables marked sensitive on Vercel cannot be read back, so enter those in Ankra.

Values can be copied once Ankra has registered the application, which happens on the first deploy.

**4. Approve**

Click **Approve and deploy**. Ankra registers the application, opens the setup pull request, builds and scans the image, and deploys it with the plan's choices. If the setup pull request or the first build is still pending, the request waits and is sent when Ankra is ready.

The approval covers exactly the actions the panel lists, for one hour. When Ankra AI works on the launch in your chat or in an agent run that carries the approval, it runs those actions without asking you again. Anything outside the list still asks first. If the plan changes after you approve, nothing runs under the old approval: read the new plan and approve it.

> [!NOTE]
>
> Test on the Ankra address before you move your domain. Check every route the proof card shows as differing or unknown, the cron routes, the rewrites you moved into `next.config`, and every variable your app reads.

***

## From the CLI

```bash theme={null}
ankra application add . --branch main
ankra chat "show me the Launch Plan of <application>" --mode ask
```

Run the first command in a local checkout of the repository.

See [Applications](/concepts/applications) and [Lovable to Ankra](/use-cases/lovable-to-ankra) for the rest of the flow, from the setup pull request to automatic deploys.