--- title: "Overview" canonical: "https://admiral.io/docs/api" description: "Reference for the Admiral REST API, generated from the OpenAPI spec. Browse endpoints by resource group, then drill into operations for request and response." --- # Overview This section is generated from the Admiral OpenAPI specification. Browse by resource group in the sidebar, then drill into individual operations for request and response details. --- title: "Changelog" canonical: "https://admiral.io/docs/changelog" description: "What has shipped in Admiral, by month, newest first." --- # Changelog ## What is not ready yet? * **Applying a changeset.** You can stage a changeset, have Admiral render it, and plan it. Apply is next. * **The Terraform agent.** The Kubernetes agent has shipped. The Terraform agent has not. * **Hosted Terraform state.** The backend at `api.admiral.io`, and the CLI's Terraform credentials helper, come with the Terraform agent. * **The [Get Started](https://admiral.io/docs/get-started/overview.md) walkthrough.** Steps 1 and 2 work today. Steps 3 to 5 wait on apply and the Terraform agent. ## September 2026 September added the component registry, changesets, and the Kubernetes agent, so a team can publish a component, stage it in an environment, and have its cluster's agent plan it. * **Component registry.** `admiral component publish` publishes every component a repository declares in `admiral.yaml`. A registry pull copies a module or chart you do not own, using a stored credential when the source is private. Revisions are content-addressed and labeled by tags, and a revision can be deprecated or revoked after it is published. Each revision records its inputs, with each input's validation, whether it accepts null, and a chart's `values.schema.json`. * **Changesets.** Stage changes to one environment, have Admiral render them, read what it rendered, and plan them with the environment's agent. * **Kubernetes agent.** Admiral trusts a cluster through its service-account token issuer or keys you upload, with no shared secret. An agent can be granted to an organization, a team, an application, or one environment. * **Organizations and access.** Environments, invitations, and personal and service account API keys. A key stops working when its owner leaves the organization. * **Tools.** The CLI covers applications, environments, components, credentials, and changesets. The Terraform provider adds `admiral_environment`. --- title: "Architecture" canonical: "https://admiral.io/docs/architecture" description: "Admiral hosts the control plane, and agents on your infrastructure pull their work, so Admiral needs no path into your cloud or clusters." --- # Architecture Admiral hosts the control plane and operates it for you. Agents run on infrastructure you operate and pull their work from it. Admiral never connects into your clusters or runs your Terraform. It connects out only to fetch: a registry pull reads from a source you name, and for a GKE or EKS cluster Admiral reads the issuer's public signing keys. ## Where does my code run? On an agent. Admiral only renders a Helm chart into manifests, and every plan and apply runs on an agent. You publish each component's code to the [registry](https://admiral.io/docs/concepts/registry.md) with `admiral component publish`, as a **bundle**, the packed bytes of a Terraform module, a Helm chart, or raw manifests. A published bundle is an immutable **revision**, identified by its digest. A Terraform agent pulls the bundle and runs it. A Kubernetes agent pulls the manifests Admiral renders from it. ```mermaid flowchart LR subgraph agents[" "] direction TB TA["Terraform agent
a machine you operate
that can reach your cloud"] KA["Kubernetes agent
runs in
the cluster"] end S["Admiral
control plane"] TA -->|pulls the bundle| S KA -->|pulls manifests| S style agents fill:none,stroke:none ``` * A **Terraform agent** runs on a machine you operate, wherever that machine can reach your cloud. It pulls the Terraform bundle and runs plan and apply there. The Terraform agent has not shipped yet. * A **Kubernetes agent** runs in the cluster. Admiral renders a Helm chart into manifests and passes raw manifests through as written. The agent pulls those manifests and plans them, and reconciles them at apply. Today it plans only. ### What happens to a Helm chart's hooks and `lookup`? Admiral renders a chart the way `helm template` does, without a cluster. Hooks are kept and ordered by `helm.sh/hook-weight`, for the agent to run in their phases at apply. `lookup` returns nothing without a cluster, so Admiral reports every template that calls it when it renders. ## What does my network need to allow? One outbound path. An agent dials `api.admiral.io`. It needs no inbound rule, no port mapping, and no route from Admiral back to the agent. An agent in a local [kind](https://kind.sigs.k8s.io/) cluster can reach Admiral as long as that cluster has outbound internet. The cloud credential used to plan and apply stays on the agent. Admiral does not store it. Inside a cluster, the Kubernetes agent can do what its role allows, so [decide its permissions](https://admiral.io/docs/agents.md#what-may-the-kubernetes-agent-do-in-my-cluster) before you install it. [Agents](https://admiral.io/docs/agents.md#who-may-deploy-and-what-may-the-deploy-do) explains how that keeps who may ship apart from what the cloud allows. ## What does the control plane keep? The resource model: applications, environments, components, changesets, runs, agents, sources, and the registry. The [Concepts overview](https://admiral.io/docs/concepts.md) defines each one. * Desired state is the set of components in an environment. Each component pins a registry revision and carries its own values. When you add a component from a catalog item, or copy one from another environment, Admiral copies the definition onto it. Editing the catalog item or the other component later does not change it. * Components declare [inputs and outputs](https://admiral.io/docs/concepts/variables-and-outputs.md) and form a dependency graph. An upstream applies, Admiral records its outputs, and the next component renders against those values. * You change an environment through a **changeset**, a reviewed batch of changes to one environment. Planning it starts a **run**, which plans each changed component. You approve once. A component whose inputs come from another component's outputs is planned only after that upstream applies, so you approve without seeing its plan. Apply has not shipped yet. * Admiral hosts [Terraform state](https://admiral.io/docs/concepts/state.md) for a Terraform component, unless the component keeps a backend of its own. The plan runs on the agent, and Admiral records the plan result. For each component it works on, the Terraform agent gets a short-lived token that reaches only that component's state and expires with the run. * A change made outside Admiral shows up as [drift](https://admiral.io/docs/concepts/drift.md). ### Does Admiral store my secrets? Yes, if you put one in a value or pass one to a Terraform input. A pointer keeps it out. * For a Terraform component, a value can be a pointer into GCP Secret Manager, AWS Secrets Manager, or Vault. Admiral stores the pointer, and the Terraform agent resolves it at apply. * A Helm chart gets no pointer resolution. It keeps the secret handling it already uses, such as Sealed Secrets, External Secrets, or Vault. * A value you write in plaintext, including one in a Helm chart's values, is stored as you wrote it. * A secret passed to an ordinary Terraform input lands in Terraform state, which Admiral hosts unless you keep your own backend. An ephemeral input or a write-only argument does not. [Secrets](https://admiral.io/docs/security/secrets.md) covers each case. Admiral encrypts what it stores the same way: a value, hosted Terraform state, and a [credential](https://admiral.io/docs/concepts/sources-and-catalog.md#credentials) for fetching from a private source. Every value, every state version, and every credential is encrypted with AES-256-GCM under its own data key. That key is wrapped by a key for your organization, which is wrapped by a root key held in a cloud KMS. Admiral holds those keys, so it can decrypt what it stores. It decrypts values when it renders a component, hosted state when it serves it to an agent or a person, and a credential only during a registry pull. A stored credential is never the cloud credential an agent uses. ## How do I manage Admiral? In the console or with the `admiral` CLI. The [CLI](https://admiral.io/docs/reference/cli.md), the [Terraform provider](https://admiral.io/docs/reference/terraform-provider.md), and the [Go SDK](https://admiral.io/docs/reference/go-sdk.md) call the API at `api.admiral.io`. * The console is for day-to-day use in the browser. * The `admiral` CLI is for a terminal and for CI. * The Terraform provider manages Admiral resources as code. * The Go SDK builds automation against the API. * The OpenAPI document is the REST contract behind the [API reference](https://admiral.io/docs/api.md). ## Why is it split this way? Admiral hosts the control plane, so scaling, patching, and backups are Admiral's job, not your team's. The agents run where the access already is. That lets Admiral coordinate many clouds and clusters without a path into any of them, and it lets a team ship without holding the cloud credential. Only the agent holds it. ## Where to go next * [Concepts Overview](https://admiral.io/docs/concepts.md): Every resource the control plane keeps, and how a change becomes a deploy. * [Agents](https://admiral.io/docs/agents.md): Where each agent runs, how it proves who it is, and what it pulls. --- title: "Overview" canonical: "https://admiral.io/docs" description: "Admiral ships an application and the infrastructure it depends on in one reviewed change, and agents on your own infrastructure do the work." --- # Overview The database, the network, and the IAM role have to exist before the workload can start. A change to the database is a change to the application that uses it. Today you ship those through two products. Tools like Atlantis, Terraform Cloud, and Spacelift plan and apply the infrastructure. Tools like Argo CD and Flux deploy the application. You review each on its own. A database address reaches the application only if you copy it, or if a pipeline you maintain copies it for you. Admiral puts both in one **changeset**, a reviewed batch of changes to one environment. The Terraform component applies, Admiral records its outputs, and the workload renders against those values before it applies. Admiral plans, applies, and deploys the components you add to it. Anything you have not added keeps running in the tools you use today, so you can move one component at a time. ## What does Admiral do? * You stage infrastructure and workloads in one changeset, plan them, and apply them in waves. Each component applies only after the components it depends on have applied. A change made outside Admiral shows up as drift. * Agents pull their work and run it on infrastructure you operate. A Terraform agent pulls a Terraform module and runs plan and apply. A Kubernetes agent pulls manifests and reconciles them. Admiral renders a Helm chart into manifests before that pull, and passes raw manifests through as written. Admiral needs no inbound access to your clouds or clusters. * A component declares what it depends on and passes outputs to the next one. The upstream apply finishes, and the downstream renders against the real values. * A Terraform component is a module you publish as it is. You do not wrap modules in a root module that wires them together, because Admiral does that wiring. One module serves many environments and applications unchanged. * Each Terraform component keeps its own [state](https://admiral.io/docs/concepts/state.md), without the `terraform_remote_state` wiring that split states usually need. Plans for different components run side by side instead of queuing on one state lock. Admiral hosts that state, or the component keeps the backend it already uses. * Agents use workload identity. A Kubernetes agent proves who it is with its cluster's service-account token, and a Terraform agent deploys with the identity of the machine it runs on, such as an IAM role. Admiral and an agent share no long-lived secret, so there is nothing in Admiral to store or rotate. ## Where should I start? * [Architecture](https://admiral.io/docs/architecture.md): Where your code runs, what the control plane keeps, and what your network must allow. * [Get Started](https://admiral.io/docs/get-started/overview.md): The walkthrough, from a local cluster to production. Still being written. * [Concepts Overview](https://admiral.io/docs/concepts.md): The resources, who owns them, and how a change becomes a deploy. ## How are the docs organized? * **Get Started** is the walkthrough, from connecting your first cluster to promoting to production. * **Concepts** is the resource model, including applications, the registry, state, changesets, and drift. * **Agents** covers where a Terraform agent and a Kubernetes agent run, how each proves who it is, and what each pulls. * **Access** covers how people and machines authenticate. * **Security** covers how secrets are referenced and resolved. * **Tools & SDKs** covers the CLI, the Terraform provider, and the Go SDK. * **API Reference** is the REST API contract. --- title: "Applications & environments" canonical: "https://admiral.io/docs/get-started/applications-and-environments" description: "Create the resources Admiral deploys into: a source to fetch code from, an application to own it, and the dev and prod environments you promote between." --- # Applications & environments Now you create the resources Admiral deploys *into*: a place to fetch code from, an application to own it, and the two environments you'll deploy and promote between. ## 1. Create a source A [Source](https://admiral.io/docs/concepts/sources-and-catalog.md) is where bytes live. For the walkthrough we point at a public chart repository, so no credentials are needed. **CLI:** ```bash # TODO: confirm flags. Public source used so no Credential is required. admiral source create \ --name podinfo \ --type helm \ --url https://stefanprodan.github.io/podinfo ``` **Console:** 1. Open **Sources**, choose **New source**. 2. Type **helm**, URL of the public chart repo. 3. Save. ## 2. Create an application **CLI:** ```bash admiral app create --name demo ``` **Console:** Open **Applications**, choose **New application**, name it `demo`. ## 3. Create dev and prod environments The same definition added to two environments becomes two independent [Components](https://admiral.io/docs/concepts/applications-and-components.md), each with its own values. **CLI:** ```bash admiral env create --app demo --name dev admiral env create --app demo --name prod ``` **Console:** Inside the `demo` application, add two environments: `dev` and `prod`. --- title: "Promote to production" canonical: "https://admiral.io/docs/get-started/promote-to-production" description: "Promote your tested changeset from dev to prod: Admiral copies changes into a new prod changeset, re-based on prod's own state, with per-env values resolved." --- # Promote to production You have a working setup in `dev`: a workload wired to an infrastructure output. Promotion ships that same, tested setup to `prod`. Promotion is a **copy**, not a link: Admiral clones the changes into a new changeset in `prod`, re-based on `prod`'s own state, and the per-environment values resolve against `prod`'s variables. ## 1. Promote the changeset **CLI:** ```bash # TODO: confirm the promote/copy verb and target-env flag. admiral changeset promote --to demo/prod ``` **Console:** Open the applied `dev` changeset and choose **Promote to prod**. Admiral creates a new, open changeset in `prod`. ## 2. Review against prod and apply The promoted changeset is reviewed against `prod`'s own deployed state, not `dev`'s. Plan it, check the diff, and apply. **CLI:** ```bash admiral changeset plan admiral changeset apply ``` **Console:** Review the diff in the `prod` changeset, then **Apply**. ## You're done You connected a cluster, deployed a real workload, wired an infrastructure output into it, and promoted the whole thing from dev to prod - the core Admiral loop end to end. ## Where to go next * [Agent Lifecycle](https://admiral.io/docs/agents/lifecycle.md): Operate agents beyond a local kind cluster * [CLI Reference](https://admiral.io/docs/reference/cli.md): Every command in depth --- title: "Wire infrastructure" canonical: "https://admiral.io/docs/get-started/wire-infrastructure" description: "Compose components in Admiral: add a Terraform infrastructure component, emit an output, and feed it into your workload through the dependency graph." --- # Wire infrastructure So far you deployed one workload. The thing that makes Admiral different is composing components: an upstream component produces an output, and a downstream component consumes it automatically, in the right order. Here you add an [infrastructure](https://admiral.io/docs/concepts/applications-and-components.md#component-kinds) component and feed its output into the workload. ## 1. Register a Terraform agent Infrastructure components run on a **Terraform agent** rather than the Kubernetes agent. **CLI:** ```bash admiral agent register --kind terraform --name local-tf # TODO: run/install the Terraform agent (local process or container) ``` **Console:** Register a second agent of kind **Terraform**, then run it where it has what it needs. ## 2. Add an infrastructure component **CLI:** ```bash # TODO: confirm. Adds an infra change to a new changeset in dev. admiral changeset create --env demo/dev --name add-config admiral changeset add-change \ --name config \ --kind infrastructure \ --engine terraform \ --target local-tf ``` **Console:** Add a change of kind **infrastructure**, engine **terraform**, bound to the Terraform agent. ## 3. Declare the dependency Make the workload consume the infra component's output. The workload reads it as `.component.config.`; Admiral defers the workload until the infra component has applied and its output exists. See [Variables & Outputs](https://admiral.io/docs/concepts/variables-and-outputs.md). **CLI:** ```bash # TODO: how a dependency + output reference is expressed on the workload change # (values template referencing .component.config.). ``` **Console:** On the workload component, reference the infra component's output in its values; the dependency is recorded automatically. ## 4. See the dependency graph **CLI:** ```bash admiral env describe demo/dev ``` **Console:** The environment view renders the graph: `config` upstream of `web`. ## 5. Plan and apply the wavefront Plan and apply the changeset. The run applies `config` first, captures its output, renders `web` against that concrete value, then applies `web` - one approval, the rest cascades. --- title: "Connect a cluster" canonical: "https://admiral.io/docs/get-started/connect-a-cluster" description: "Get access to Admiral, install the CLI, and run a Kubernetes agent in a kind cluster on your own machine." --- # Connect a cluster In this step you connect a Kubernetes cluster to Admiral by running a **Kubernetes agent** inside it. The cluster is a [kind](https://kind.sigs.k8s.io/) cluster on your own machine, so everything in this walkthrough runs locally. ## 1. Get access Admiral is open by invitation. Accept the invitation a colleague sent you, or [join the waitlist](https://admiral.io/waitlist.md). ## 2. Install the CLI **Homebrew:** ```bash brew install admiral-io/tap/admiral ``` **Scoop:** ```powershell scoop bucket add admiral-io https://github.com/admiral-io/scoop-bucket scoop install admiral-io/admiral ``` Binaries for Linux, macOS, and Windows, and `.deb`, `.rpm`, and Arch Linux packages, are on the [admiral-cli releases page](https://github.com/admiral-io/admiral-cli/releases). Check the install with `admiral version`. ## 3. Sign in ```bash admiral auth login ``` The CLI opens a browser to sign in and keeps the session. Over SSH, add `--no-browser` to print the sign-in URL instead. ## 4. Create a local cluster ```bash kind create cluster --name admiral-demo kubectl cluster-info --context kind-admiral-demo ``` ## 5. Register and run the agent ### Register the agent with Admiral Registering yields a token the agent uses to authenticate when it pulls work. **CLI:** ```bash admiral agent register --kind kubernetes --name admiral-demo ``` **Console:** 1. Open **Agents** in the console. 2. Choose **New agent**, kind **Kubernetes**. 3. Copy the issued token for the next step. ### Install the agent into the cluster > **Warning:** By default the agent's role can read and change every resource in every namespace. That is fine for this throwaway kind cluster. Before you install it on a cluster you care about, read [what the Kubernetes agent may do in your cluster](https://admiral.io/docs/agents.md#what-may-the-kubernetes-agent-do-in-my-cluster) and narrow its role. **CLI:** ```bash # TODO: one-command, token-in agent install into the current kube-context admiral agent install --token ``` **Console:** The console shows a copy-paste install command after you register the agent. ## 6. Verify it connected **CLI:** ```bash admiral agent list ``` A healthy agent reports a recent heartbeat. **Console:** The agent shows as **connected** in the Agents list once it dials in. --- title: "Overview" canonical: "https://admiral.io/docs/get-started/overview" description: "A local walkthrough that connects a kind cluster, deploys a workload, wires an infrastructure component to it, and promotes it to production." --- # Overview By the end of this walkthrough you will have connected a cluster to Admiral, deployed a real workload, wired an infrastructure component to it, and promoted the whole thing from a dev environment to a production environment. All on your own machine, using a local Kubernetes cluster. > **Warning:** This walkthrough is still being written. Steps 1 and 2 work today. Steps 3 to 5 need changeset apply and the Terraform agent, which have not shipped, so they cannot finish yet. The [changelog](https://admiral.io/docs/changelog.md) says what has shipped. ## What will I build? * An **Application** with two **Environments**: `dev` and `prod`. * A **workload** component deployed from a public Helm chart. * An **infrastructure** component whose output feeds the workload (the dependency graph). * A **promotion** that ships the same, tested setup from `dev` to `prod`. * Two **agents**: a Kubernetes agent in the local cluster from step 1, and a Terraform agent for the infrastructure component, added in step 4. ## What are the steps? * [1. Connect a cluster](https://admiral.io/docs/get-started/connect-a-cluster.md): Get access, install the CLI, run an agent in a local kind cluster * [2. Applications & environments](https://admiral.io/docs/get-started/applications-and-environments.md): Create a source, an app, and dev + prod environments * [3. Your first deploy](https://admiral.io/docs/get-started/first-deploy.md): Deploy a workload through a changeset and watch it go live * [4. Wire infrastructure](https://admiral.io/docs/get-started/wire-infrastructure.md): Add an infra component and pass its output to the workload * [5. Promote to production](https://admiral.io/docs/get-started/promote-to-production.md): Copy the tested changeset from dev to prod ## What do I need? Admiral is hosted, so there is no server to install. You need an invitation and a target to deploy into. For this walkthrough the target is a throwaway local cluster. * **An invitation to Admiral.** [Connect a cluster](https://admiral.io/docs/get-started/connect-a-cluster.md) covers getting access. * **The `admiral` CLI.** [Connect a cluster](https://admiral.io/docs/get-started/connect-a-cluster.md) installs it. * **A local Kubernetes target**, for the Kubernetes agent. The Terraform example in step 4 creates nothing in a cloud, so it runs locally too. | Tool | Minimum version | Purpose | | -------------------------------------------------------------------- | --------------- | -------------------------- | | [Docker](https://docs.docker.com/get-docker/) | 20.10+ | Container runtime for kind | | [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) | 0.20+ | Local Kubernetes cluster | | [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.28+ | Inspect the cluster | > **Note:** The agent is **outbound-only**. It dials `api.admiral.io` and pulls its work, so a local kind cluster with plain internet access is enough. No inbound networking, no port mapping. See [Architecture](https://admiral.io/docs/architecture.md). ## Should I use the CLI or the console? Steps that create resources are shown in two tabs, the **CLI** and the **console**. Both create the same resources, so use either. --- title: "Your first deploy" canonical: "https://admiral.io/docs/get-started/first-deploy" description: "Deploy your first workload with Admiral: define a component in dev, stage it in a changeset, apply it through your Kubernetes agent, and watch it go live." --- # Your first deploy This is the payoff: you define a workload component in `dev`, stage it in a changeset, apply it, and see it running in your cluster. This deploys through your Kubernetes agent from [step 1](https://admiral.io/docs/get-started/connect-a-cluster.md). ## 1. Add a workload component A [Component](https://admiral.io/docs/concepts/applications-and-components.md) of kind `workload` deploys via the Kubernetes agent. You add it as a [Change](https://admiral.io/docs/concepts/changesets-and-runs.md) inside a changeset; you never edit an environment directly. ### Open a changeset **CLI:** ```bash admiral changeset create --env demo/dev --name add-podinfo ``` **Console:** In the `dev` environment, choose **New changeset** and name it `add-podinfo`. ### Stage a change that creates the component **CLI:** ```bash # TODO: confirm flags - source/engine/path + target agent + values. admiral changeset add-change \ --name web \ --kind workload \ --source podinfo \ --engine helm \ --target admiral-demo ``` **Console:** 1. Add a change to the changeset. 2. Choose the `podinfo` source, engine **helm**, kind **workload**. 3. Bind it to the `admiral-demo` Kubernetes agent. ## 2. Plan, review, apply A [Run](https://admiral.io/docs/concepts/changesets-and-runs.md) has two phases. Plan first, review what will happen, then apply at the single approval gate. **CLI:** ```bash admiral changeset plan admiral changeset apply ``` **Console:** Click **Plan**, review the planned change, then **Apply**. ## 3. See it live **CLI:** ```bash kubectl get pods --context kind-admiral-demo # TODO: admiral-side view of the resulting Revision / run status admiral run get ``` **Console:** The environment shows the component as deployed, with the [revision it runs](https://admiral.io/docs/concepts/changesets-and-runs.md#what-an-apply-records) and the run logs. > **Note:** You just ran a real deployment through Admiral. The next step shows the part competitors do badly: wiring one component's output into another. --- title: "Authentication" canonical: "https://admiral.io/docs/access" description: "Sign in to Admiral in the console or the CLI, and use a personal or service account API key, bounded by scopes, for scripts and CI." --- # Authentication Admiral is hosted, so authentication has two sides: how *people* sign in through the console or the CLI, and how *machines* (CI and automation) authenticate to the API. This page explains both. There is no identity provider for you to install or configure, because that is part of the managed service. ## Signing in You sign in to the console through your identity, and the CLI signs in the same way: ```bash admiral auth login ``` `admiral auth login` opens a browser to complete sign-in, then stores a session so subsequent commands are authenticated. Your session is maintained by Admiral Cloud with configurable idle and absolute lifetimes. ## Token types For anything non-interactive you use an API key. Admiral issues two kinds, for two different access patterns. ### Personal API keys * Scoped to an individual user. * Created in the console. * Used for CLI access and API calls on your behalf. * Act with your permissions, limited to the scopes the key was created with. Use a personal API key for local scripting and one-off automation that acts as you. A key stops working when its owner leaves the organization. ### Service account API keys * Scoped to a service identity, not a person. * Created in the console or through the API. * Used by machines, such as CI pipelines. * Do not vanish when a person leaves. Use a service account API key for CI. An agent does not use an API key. Admiral trusts its cluster instead, see [Agents](https://admiral.io/docs/agents.md#how-does-an-agent-prove-who-it-is). ## Scopes API keys carry scopes that bound what they can do (for example, `catalog:read` versus `catalog:write`). Grant the narrowest scope that fits the job, especially for a service account key that lives in CI. A personal key for Terraform is limited to the Terraform API, which serves [hosted state](https://admiral.io/docs/concepts/state.md). ## Rotating and revoking Treat an API key like any other secret. Rotate service account keys on a schedule, and revoke any key that may be exposed. A revoked key stops authenticating immediately. ## Where to go next * [Agents & Execution](https://admiral.io/docs/agents.md): How an agent proves who it is without an API key --- title: "Secrets" canonical: "https://admiral.io/docs/security/secrets" description: "Admiral stores a pointer into your secret manager and the agent resolves it, while chart values pass through exactly as you wrote them." --- # Secrets Admiral works with the way you already handle secrets. A team that already reads secrets from its own module, or that already ships Sealed Secrets, External Secrets, or a Vault chart, keeps doing that. ## How do I keep a secret out of Admiral? For a Terraform component, a value may name an entry in GCP Secret Manager, AWS Secrets Manager, or Vault. The reference is one string, `secret(":
")`, and the address is the manager's own identifier: ```yaml db_password: ref: secret("gcp:projects/acme-prod/secrets/users-db-password") api_token: ref: secret("aws:arn:aws:secretsmanager:us-east-1:111122223333:secret:api-token#token") tls_key: ref: secret("vault:kv/data/users-db#tls_key") ``` * `#key` reads one field of a JSON or key/value secret. Vault needs it. On AWS, leaving it off reads the whole secret string. * A reference reads the latest version unless you pin one, with `/versions/N` on GCP or `?version=` on AWS. An unpinned reference is read at apply, so a rotated secret needs no changeset. Admiral stores that pointer. When you plan, Admiral renders each component into a **run artifact**, the exact files the agent receives, and the pointer goes into it unresolved. The agent resolves it with the cloud identity it already uses to apply. The control plane does not. ```mermaid flowchart LR Ref["Value
secret("gcp:…")"] --> CP["Control plane
stores the pointer"] CP --> Agent["Agent
resolves at apply"] Agent --> SM["Your manager
GCP, AWS, or Vault"] ``` The reference is offered. It is not required. A module may keep using a data source. ## What happens to secrets in chart values? A workload gets no secret resolution from Admiral. A chart's values are what the chart takes. Sealed Secrets ciphertext, an ExternalSecret name, a Vault wrapper, or plaintext you chose to put there all pass through untouched. Admiral does not refuse a chart and does not rewrite one. Plaintext you put in values is stored as you gave it. ## Which secrets still land in Terraform state? A secret fed to an ordinary Terraform input lands in [state](https://admiral.io/docs/concepts/state.md). An ephemeral input or a write-only argument stays out of it. The changeset review shows which kind each secret input is. When Admiral hosts the state, it encrypts it the way it encrypts a stored credential, and Admiral can decrypt it. When a component keeps its own backend, the secret lands in that backend, and Admiral never holds it. Admiral has no secret store of its own, so a reference always points into your own manager. ## Where to go next * [State](https://admiral.io/docs/concepts/state.md): Where an ordinary Terraform input is stored after apply * [Credentials](https://admiral.io/docs/concepts/sources-and-catalog.md#credentials): A different secret: what a private pull may present --- title: "Agent Lifecycle" canonical: "https://admiral.io/docs/agents/lifecycle" description: "Operate Admiral's execution agents end to end: register, install, and validate Terraform and Kubernetes agents, then monitor, rotate, and upgrade them." --- # Agent Lifecycle Agents register with the control plane and pull a bundle. A Terraform agent runs where it has cloud access. A Kubernetes agent runs in the cluster. For the conceptual model see [Agents & Execution](https://admiral.io/docs/agents.md); this page covers operating them. ## The two kinds An agent's **kind** determines what it executes and where it runs: | Kind | Executes | Runs | Installed | | -------------- | --------------------------------------------------- | ---------------------------- | ------------------------------------------- | | **Terraform** | `infrastructure` components (terraform) | wherever it has cloud access | as a process or container with cloud access | | **Kubernetes** | `workload` components (helm / kustomize / manifest) | inside the target cluster | via Helm chart into the cluster it manages | Both kinds share the same lifecycle: register, install, validate, monitor, rotate, upgrade. ## Register Registering an agent with Admiral yields a token the agent uses to authenticate when it pulls work. ```bash admiral agent register --kind kubernetes --name prod-k8s admiral agent register --kind terraform --name aws-prod-tf ``` Keep the issued token secret; it is the agent's identity to the control plane. ## Install ### Terraform agent Run the Terraform agent where it has the cloud access its targets need: an IAM role, instance profile, or configured cloud credentials. Provide the registration token; the agent deploys with the identity of its environment. ### Kubernetes agent Install the Kubernetes agent via its Helm chart into the Kubernetes cluster it will manage, passing the registration token. It connects outbound to Admiral and begins pulling revisions for workloads bound to it. ## Validate registration Confirm the agent has connected and is pulling: ```bash admiral agent list admiral agent get prod-k8s ``` A healthy agent reports recent heartbeats and its detected tooling. ## Monitor Agents report health and the work they are executing back to the control plane. Watch for: * **Heartbeat staleness** - an agent that stops checking in cannot pull new work. * **Job or revision state** - in-flight, succeeded, or failed work attributed to the agent. * **Tooling drift**: the runtime versions an agent reports, such as which Terraform version a Terraform agent is running. ## Rotate credentials Rotate an agent's token without downtime by issuing a new one, rolling it into the agent's configuration, then revoking the old one. ```bash admiral agent rotate-token prod-k8s ``` ## Upgrade Upgrade an agent by deploying the new agent build (a new container image for Terraform agents, a `helm upgrade` for Kubernetes agents). Because work is pull-based and idempotent, an agent can be restarted or replaced without coordinating with the control plane; it resumes pulling once it reconnects. ## Where to go next * [Authentication](https://admiral.io/docs/access.md): How people and CI authenticate, and why an agent needs no API key * [Connect a Cluster](https://admiral.io/docs/get-started/connect-a-cluster.md): Run an agent in a local kind cluster --- title: "Agents & Execution" canonical: "https://admiral.io/docs/agents" description: "Agents pull their work from Admiral, a Terraform agent wherever it can reach your cloud and a Kubernetes agent inside the cluster." --- # Agents & Execution Components describe *what* should exist. Agents are *who makes it real*. They are the execution layer, and they always call Admiral, never the other way round. ## Why does the agent call out? The agent calls out so Admiral never has a path into your cloud or your clusters. The cloud credential used to plan and apply stays on the agent. The agent already runs where that access is. A Terraform agent runs on a machine you operate, wherever that machine can reach your cloud, and pulls the Terraform bundle. A Kubernetes agent runs inside the cluster it manages. Admiral renders a Helm chart into manifests before that pull, includes raw manifests as written, and the agent pulls those manifests. ```mermaid flowchart TB S["Admiral
server"] T["Terraform agent
runs where it has cloud access"] K["Kubernetes agent
runs in the cluster"] T -->|pulls the bundle| S K -->|pulls manifests| S ``` For the people who approve the connection, the ask is one outbound path. There is no inbound rule to review, and no cloud or cluster credential to store, rotate, or revoke inside Admiral. ## What does each kind of agent run? Terraform and Kubernetes are the two **kinds** of the one Agent concept. The kind determines what an agent executes and where it runs. | Agent kind | Executes | Runs | Pulls | | -------------- | --------------------------------------- | -------------------------------------------------- | -------------------- | | **Terraform** | `infrastructure` components (terraform) | on a machine you operate that can reach your cloud | the Terraform bundle | | **Kubernetes** | `workload` components (helm / manifest) | inside the target Kubernetes cluster | rendered manifests | A **Terraform agent** runs on a machine you operate, wherever that machine can reach your cloud. It pulls the Terraform bundle, runs plan and apply, and streams results back. A **Kubernetes agent** runs inside the Kubernetes cluster it manages. Admiral renders a Helm chart into manifests, includes raw manifests as written, and the agent pulls those manifests and reconciles them. ## How does work reach an agent? An environment selects the Kubernetes agent it deploys through, from the agents granted to it. A run sends each workload component's work to that agent. ```mermaid flowchart LR C["Component
kind: workload"] E["Environment
prod"] A["Kubernetes agent
prod-k8s"] C -->|lives in| E E -->|deploys through| A ``` The component's kind decides which agent gets the work, so a Helm release cannot reach a Terraform agent, and a Terraform job cannot reach a Kubernetes agent. ## How does an agent prove who it is? This section describes the Kubernetes agent. The Terraform agent has not shipped, and its enrollment is not documented yet. Admiral trusts the cluster, not a shared secret. A Kubernetes agent is a namespace and service account in a cluster, and one cluster can hold several agents. The agent holds no long-lived credential. It presents a service-account token that the kubelet issues for Admiral and rotates, and Admiral checks that token against the cluster's public signing keys: * On a cluster whose token issuer is public (GKE, EKS), Admiral fetches those keys from the issuer. * On a cluster without a public issuer (kind, on-premises), the agent sends the keys once. It uses an enrollment key that an admin creates in Admiral, which can do nothing else and stops working once used or after an hour. When the cluster's keys change later, an admin accepts the new set. Admiral never trusts keys an agent reports on its own. The signing keys are public, so they are not a secret to protect. Admiral accepts the agent's token only on the agent API, and every other API refuses it. Who may use an agent is a grant. The agent's owner grants it to the organization, a team, an application, or one environment. An environment's editor then picks an agent within those grants. Your organization's first agent is open to everyone in it. See the [agent lifecycle guide](https://admiral.io/docs/agents/lifecycle.md) for operations. ## What may the Kubernetes agent do in my cluster? What its role allows, so decide that before you install it. By default the agent is bound to a ClusterRole that grants `get`, `list`, `patch`, and `create` on every resource in every namespace. That is more than most clusters should grant. List the namespaces the agent serves in the chart's `rbac.namespaces`, and the chart grants a Role in each of those instead. * Today the agent plans only. Every write it sends is a dry run. Kubernetes RBAC cannot tell a dry run from a real write, so grant only what you would let it change. * A plan reads Secrets, including their values, to tell a changed key from an unchanged one. The agent never sends a value it reads. A plan shows only which keys were added, changed, or removed. * The agent reads the cluster's service-account signing keys, to enroll and to report a key rotation. ## Who may deploy, and what may the deploy do? A deployment has two permissions, and most tools collapse them into one credential. The first is who on the team is allowed to ship. The second is what the cloud or the cluster will allow that run to do. The usual fix is to store the cloud credential in the product, or to require the person running the job to hold it. Granting a team access to deploy then means handing them that credential, or letting them trigger a run that uses a shared privileged credential the product holds. You cannot give a team the access they need without also widening what that credential can do. Everyone who can apply exercises the same cloud role, and the product becomes a standing holder of your account. Admiral keeps the two permissions apart. The cloud or the cluster authorizes the agent, and only the agent. A Terraform agent deploys with the identity of the place it runs: an IAM role, an instance profile, or other cloud credentials you grant when you install it. A Kubernetes agent reconciles with its in-cluster service account. Admiral does not store those credentials, and it has no standing access to the account or the cluster. Who may act is decided in Admiral. Access to an application or an environment, granted to a person or a team, decides who can open a changeset, review it, and apply it. Those people can cause the agent for that environment to run. They do not receive the cloud or cluster credentials, and they do not need an account there to do the work. Each side is scoped on its own. A production agent carries the production role in the cloud. A development agent carries a narrower one. Adding someone to a team in Admiral does not change what the cloud role can do. Narrowing or rotating the cloud role does not change who can apply. This is separate from a [Credential](https://admiral.io/docs/concepts/sources-and-catalog.md#credentials), which is the stored secret a private Source uses for fetching, not an execution identity. > **Note:** A team can ship through Admiral without holding the cloud or cluster credentials the agent uses, and without Admiral holding them either. ## Where to go next * [Changesets & Runs](https://admiral.io/docs/concepts/changesets-and-runs.md): How a run hands work to agents wave by wave --- title: "CLI" canonical: "https://admiral.io/docs/reference/cli" description: "Install the Admiral CLI on macOS, Windows, Linux, Docker, or from source, sign in, and set it up for CI." --- # CLI The `admiral` CLI does from a terminal or a CI job what the console does in a browser: applications, environments, components, credentials, and changesets. > **Note:** The CLI is under active development. This page covers installation and > configuration. Command reference documentation will be added as the CLI > stabilizes. ## How do I install the CLI? **macOS (Homebrew):** Install via the Admiral Homebrew tap: ```bash brew install admiral-io/tap/admiral ``` To upgrade: ```bash brew upgrade admiral ``` To uninstall: ```bash brew uninstall admiral ``` Supports both Intel (x86\_64) and Apple Silicon (arm64). Shell completions for bash, zsh, and fish are installed automatically. **Windows (Scoop):** Install via the Admiral Scoop bucket: ```powershell scoop bucket add admiral-io https://github.com/admiral-io/scoop-bucket scoop install admiral-io/admiral ``` To upgrade: ```powershell scoop update admiral ``` To uninstall: ```powershell scoop uninstall admiral ``` Supports both x86\_64 and arm64 Windows. **Linux:** #### Package managers Pre-built packages are available for common Linux distributions: | Format | Distributions | | -------------- | ----------------------- | | `.deb` | Debian, Ubuntu | | `.rpm` | Red Hat, CentOS, Fedora | | `.apk` | Alpine | | `.pkg.tar.zst` | Arch Linux | Download the appropriate package from the [GitHub Releases](https://github.com/admiral-io/admiral-cli/releases) page and install with your package manager: ```bash # Debian/Ubuntu sudo dpkg -i admiral_*.deb # Red Hat/CentOS/Fedora sudo rpm -i admiral_*.rpm # Alpine sudo apk add --allow-untrusted admiral_*.apk ``` #### Direct download Download the binary archive for your architecture from [GitHub Releases](https://github.com/admiral-io/admiral-cli/releases): ```bash # Example for Linux x86_64 curl -Lo admiral.tar.gz https://github.com/admiral-io/admiral-cli/releases/latest/download/admiral_linux_x86_64.tar.gz tar xzf admiral.tar.gz sudo mv admiral /usr/local/bin/ ``` Shell completions are included in the archive and in all packages. **Docker:** Run the CLI from a container image: ```bash docker run --rm ghcr.io/admiral-io/admiral:latest version ``` The image is a non-root distroless build, available for `linux/amd64` and `linux/arm64`. The image suits CI. It cannot open a browser to sign in, so pass an API key with `-e ADMIRAL_API_KEY`. **From source:** Requires Go 1.26+: ```bash git clone https://github.com/admiral-io/admiral-cli.git cd admiral-cli make build ``` The binary is written to `dist/`. To install directly to your `$GOPATH/bin`: ```bash make install ``` ## How do I check the install? ```bash admiral version ``` ## How do I configure the CLI? The CLI reads configuration from a local config directory and supports overrides via flags and environment variables. ### Signing in ```bash admiral auth login ``` The CLI opens a browser to sign in and keeps a session that refreshes itself. Over SSH, add `--no-browser` to print the sign-in URL instead. Without a browser, `admiral auth login --with-token` stores an [API key](https://admiral.io/docs/access.md) instead, prompted so it never reaches your shell history. `admiral auth status` shows who the CLI is signed in as. To keep the key in 1Password instead, pass a reference. The CLI fetches the key with `op` on each run, so it is never written to disk: ```bash echo "op://Engineering/admiral/api-key" | admiral auth login --with-token ``` For CI, pass an API key through the environment. It takes precedence over anything `auth login` stored: ```bash export ADMIRAL_API_KEY= ``` ### Configuration keys | Key | Description | Default | | -------- | --------------------- | ------- | | `output` | Default output format | `table` | ### Managing configuration ```bash # Set a value admiral config set output json # Get a value admiral config get output # List all settings admiral config list # Remove a setting admiral config unset output ``` ## Which flags work on every command? These flags are available on every command and override config file values: | Flag | Short | Description | | -------------- | ----- | ---------------------------------------------- | | `--output` | `-o` | Output format: `table`, `json`, `yaml`, `wide` | | `--verbose` | `-v` | Enable debug logging | | `--config-dir` | | Override config directory path | ## How do I set up shell completion? If you installed via Homebrew, Scoop, or a Linux package, shell completions are set up automatically. To generate them manually: ```bash # Bash admiral completion bash > /usr/share/bash-completion/completions/admiral # Zsh admiral completion zsh > "${fpath[1]}/_admiral" # Fish admiral completion fish > ~/.config/fish/completions/admiral.fish ``` --- title: "Go SDK" canonical: "https://admiral.io/docs/reference/go-sdk" description: "Integrate Admiral into Go apps with the official SDK: a typed client for the Admiral API for building tools, operators, and integrations that manage resources." --- # Go SDK The Admiral Go SDK provides a typed client for the Admiral API. Use it to build tools, operators, and integrations that manage Admiral resources programmatically. > **Note:** The SDK is under active development. The API surface may change between > releases. This page covers the stable client setup and a basic usage example. ## Installation ```bash go get go.admiral.io/sdk ``` Requires Go 1.26+. ## Client setup ```go package main import ( "context" "log" "os" "go.admiral.io/sdk/client" ) func main() { ctx := context.Background() c, err := client.New(ctx, client.Config{ AuthToken: os.Getenv("ADMIRAL_API_KEY"), AuthScheme: client.AuthSchemeToken, }) if err != nil { log.Fatal(err) } defer c.Close() } ``` `HostPort` defaults to `api.admiral.io:443`. API keys are sent with the `Token` scheme; `Bearer` is for the session tokens the CLI's browser login produces. `ADMIRAL_API_KEY` is the same variable the [CLI](https://admiral.io/docs/reference/cli.md) and the [Terraform provider](https://admiral.io/docs/reference/terraform-provider.md) read. ### Configuration options | Field | Type | Default | Description | | ------------------------------------------------ | ------------------- | ----------------------- | --------------------------------------------------------------------- | | `HostPort` | `string` | `api.admiral.io:443` | Admiral API server address (`host:port`) | | `AuthToken` | `string` | none (required) | API key (`admp_…` personal, `adms_…` service) or session token | | `AuthScheme` | `AuthScheme` | `AuthSchemeBearer` | `AuthSchemeToken` for API keys, `AuthSchemeBearer` for session tokens | | `TokenValidator` | `TokenValidator` | `DefaultTokenValidator` | Validates the token format before connecting | | `Logger` | `Logger` | no-op | Logger implementation | | `ConnectionOptions.Insecure` | `bool` | `false` | Use plaintext (no TLS) | | `ConnectionOptions.TLSConfig` | `*tls.Config` | TLS 1.2 minimum | Custom TLS configuration (ignored when `Insecure` is set) | | `ConnectionOptions.DialTimeout` | `time.Duration` | `30s` | Connection establishment timeout | | `ConnectionOptions.DialOptions` | `[]grpc.DialOption` | none | Additional gRPC dial options | | `ConnectionOptions.EnableKeepAliveCheck` | `bool` | `false` | Enable client keepalive pings | | `ConnectionOptions.KeepAliveTime` | `time.Duration` | `30s` | Keepalive ping interval | | `ConnectionOptions.KeepAliveTimeout` | `time.Duration` | `90s` | Keepalive ping response timeout | | `ConnectionOptions.KeepAlivePermitWithoutStream` | `bool` | `false` | Send pings even with no active streams | ### Logging The SDK ships with three logger implementations: ```go // Silent (default) client.NewNoOpLogger() // Standard library writer client.NewStdLogger(os.Stderr, client.LevelInfo) // slog integration client.NewSlogLogger(slog.Default()) ``` ## Usage example This example creates an application, reads it back, and then cleans up: ```go package main import ( "context" "fmt" "log" "os" "go.admiral.io/sdk/client" applicationv1 "go.admiral.io/sdk/proto/admiral/api/application/v1" ) func main() { ctx := context.Background() c, err := client.New(ctx, client.Config{ AuthToken: os.Getenv("ADMIRAL_API_KEY"), AuthScheme: client.AuthSchemeToken, }) if err != nil { log.Fatal(err) } defer c.Close() // Create an application createResp, err := c.Application().CreateApplication(ctx, &applicationv1.CreateApplicationRequest{ Name: "my-service", Description: "Example application", Labels: map[string]string{ "team": "platform", }, }, ) if err != nil { log.Fatal(err) } fmt.Printf("Created: %s (ID: %s)\n", createResp.Application.Name, createResp.Application.Id, ) // Read it back getResp, err := c.Application().GetApplication(ctx, &applicationv1.GetApplicationRequest{ ApplicationId: createResp.Application.Id, }, ) if err != nil { log.Fatal(err) } fmt.Printf("Retrieved: %s\n", getResp.Application.Name) // Clean up _, err = c.Application().DeleteApplication(ctx, &applicationv1.DeleteApplicationRequest{ ApplicationId: createResp.Application.Id, }, ) if err != nil { log.Fatal(err) } fmt.Println("Deleted application") } ``` ## Error handling The SDK returns standard gRPC errors. Use the `status` package to inspect error codes: ```go resp, err := c.Application().GetApplication(ctx, req) if err != nil { st, ok := status.FromError(err) if ok { switch st.Code() { case codes.NotFound: log.Println("resource does not exist") case codes.Unauthenticated: log.Println("invalid or expired token") case codes.PermissionDenied: log.Println("insufficient permissions") default: log.Fatalf("API error (%s): %s", st.Code(), st.Message()) } } } ``` The `codes` and `status` packages come from `google.golang.org/grpc/codes` and `google.golang.org/grpc/status`. Refer to the [API reference](https://admiral.io/docs/api.md) for details on request and response types for each service. --- title: "Terraform Provider" canonical: "https://admiral.io/docs/reference/terraform-provider" description: "Manage Admiral resources as infrastructure-as-code with the Terraform provider: create applications, configure environments, and fold it into your pipelines." --- # Terraform Provider The Admiral Terraform provider lets you declare and manage Admiral resources as part of your infrastructure-as-code workflows. Use it to create applications and their environments, and to integrate Admiral into your existing Terraform pipelines. > **Note:** Resource and data source schemas are generated from the provider itself and > published on the [Terraform > Registry](https://registry.terraform.io/providers/admiral-io/admiral/latest/docs), > which is the source of truth for the current release. ## Installation Add the provider to your Terraform configuration: ```hcl terraform { required_version = ">= 1.0" required_providers { admiral = { source = "admiral-io/admiral" version = "~> 0.2" } } } ``` Then run: ```bash terraform init ``` ## Provider configuration ```hcl provider "admiral" { api_key = var.admiral_api_key } ``` | Attribute | Type | Required | Default | Description | | ----------- | ------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------ | | `server` | String | No | `api.admiral.io:443` | Admiral API address as `host:port`. Port 443 is appended if omitted. Also reads `ADMIRAL_SERVER` | | `api_key` | String | Yes | none | API key (sensitive). Also reads `ADMIRAL_API_KEY` | | `insecure` | Boolean | No | `false` | Connect over TLS without verifying the server certificate | | `plaintext` | Boolean | No | `false` | Connect without TLS. The key travels unencrypted; only for a local server | The attribute names and environment variables match the [CLI](https://admiral.io/docs/reference/cli.md), so a shell set up for `admiral` is already set up for Terraform. API keys are created in the console; see [CLI reference](https://admiral.io/docs/reference/cli.md) for how they are used from CI. ### Using environment variables For CI/CD and shared configurations, set credentials via environment variables instead of hardcoding them: ```bash export ADMIRAL_API_KEY="admp_..." ``` ```hcl # No explicit api_key needed when the env var is set provider "admiral" {} ``` ## Example usage ### Create an application ```hcl resource "admiral_application" "payments" { name = "payment-service" description = "Payment processing microservice" labels = { team = "backend" tier = "critical" } } output "app_id" { value = admiral_application.payments.id } ``` ### Add environments An environment belongs to an application. Its name is unique within that application, and changing `application_id` replaces the environment. ```hcl resource "admiral_environment" "staging" { application_id = admiral_application.payments.id name = "staging" } resource "admiral_environment" "production" { application_id = admiral_application.payments.id name = "production" description = "Customer-facing" labels = { tier = "critical" } } ``` ### Look up existing resources ```hcl # An application, by name or by ID data "admiral_application" "existing" { name = "payment-service" } data "admiral_application" "by_id" { id = "550e8400-e29b-41d4-a716-446655440000" } # An environment, by application and name, or by ID data "admiral_environment" "production" { application_id = data.admiral_application.existing.id name = "production" } data "admiral_environment" "by_id" { id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8" } ``` ### Manage multiple applications ```hcl variable "applications" { type = map(object({ description = string labels = map(string) environments = set(string) })) default = { "auth-service" = { description = "Authentication and authorization" labels = { team = "platform", tier = "critical" } environments = ["staging", "production"] } "api-gateway" = { description = "Public API gateway" labels = { team = "platform", tier = "critical" } environments = ["staging", "production"] } "worker" = { description = "Background job processing" labels = { team = "backend", tier = "standard" } environments = ["production"] } } } resource "admiral_application" "apps" { for_each = var.applications name = each.key description = each.value.description labels = each.value.labels } locals { environments = { for pair in flatten([ for app, cfg in var.applications : [ for env in cfg.environments : { app = app, env = env } ] ]) : "${pair.app}/${pair.env}" => pair } } resource "admiral_environment" "envs" { for_each = local.environments application_id = admiral_application.apps[each.value.app].id name = each.value.env } ``` ### Import existing resources Import an application or environment into Terraform state using its UUID: ```bash terraform import admiral_application.payments 550e8400-e29b-41d4-a716-446655440000 terraform import admiral_environment.production 6ba7b810-9dad-11d1-80b4-00c04fd430c8 ``` ## Further reading * [Terraform Registry](https://registry.terraform.io/providers/admiral-io/admiral/latest/docs). Published provider with generated resource and data source documentation. * [Provider source](https://github.com/admiral-io/terraform-provider-admiral). Issues, releases and contributing. --- title: "Drift" canonical: "https://admiral.io/docs/concepts/drift" description: "Drift is a change in the environment that the current changeset did not make. Admiral shows it on review, and fixing it is its own changeset." --- # Drift Drift is the difference between what an environment last applied and what is actually there. A changeset does not absorb that difference. It shows it. ## What a changeset plans A changeset plans the components it touches and every component whose inputs consume their outputs. It does not plan the rest of the environment. ```mermaid flowchart LR CS["Changeset"] --> Plan["Plan
touched components and their consumers"] Env["Everything else"] --> Drift["Drift
shown beside the review"] Drift --> Fix["Remediation
its own changeset"] ``` An unrelated component with a non-empty plan is drift. Folding it into the changeset would ask a reviewer to approve a change nobody on that changeset made, or it would silently revert a hotfix. The review shows the drift beside the plan, for example "prod: A drifted since Tue, 3 resources". ## When it is checked A drift check is a refresh-only plan on a runner that has a read-only identity. For Helm it is a server-side dry-run diff by the agent. The view always says how old the check is. | When | What happens | | ------------ | ------------------------------------------------------------------------------------ | | Daily | Each environment, by default. An environment can change the interval. | | On demand | You ask for a fresh check. | | Before apply | When the environment requires a clean drift check, the check runs again at the gate. | Remediation is its own changeset. That changeset either returns the resource to the code, or it adopts the outside change into the code. An environment may refuse to apply while drift is present. A provider version does not move outside a changeset. Lock files are required, and a provider changes only when the component's revision changes. ## Where to go next * [State](https://admiral.io/docs/concepts/state.md): A state write outside a run is one way an environment moves --- title: "Changesets & Runs" canonical: "https://admiral.io/docs/concepts/changesets-and-runs" description: "How a staged change becomes a live deployment: changesets batch edits, runs plan and apply them in two phases, and each component records what it runs." --- # Changesets & Runs This is where the model comes to life. Components describe desired state, but nothing moves until you stage changes, plan them, and apply them. Four resources cover that flow. ```mermaid flowchart LR Cs["Changeset
reviewable batch,
one environment"] --> Ch["Change
one edit to
one component"] Ch --> Rn["Run
one execution,
plan + apply"] Rn --> Lv["Live component
the revision and values
it now runs"] ``` ## Changeset A Changeset is a reviewable batch of changes scoped to one environment. It is the only way to mutate the environment's components. Changesets behave like branches: **many can be open at once** against the same environment. You stage your work, review it in isolation, and apply when ready. A changeset is not an atomic transaction - it is a planning artifact, an authorization boundary, and an observation window. ```bash admiral changeset create --env checkout/prod --name bump-postgres ``` ## Change A Change is one staged modification to one component. A changeset holds at most one Change per component, and each Change is one of: * **create** - add a new component * **update** - modify an existing component's values or definition * **destroy** - tear down the component's resources and remove it * **orphan** - stop managing the component, leave its resources in place A Change's content can be authored inline, prefilled from a Catalog Item, or copied from another changeset. Variable overrides ride along in the changeset too. ## Run Planning a changeset starts a **Run**, one execution carrying every changed component. Plan and apply are two **phases** of one run, not two separate runs. ### Planning When you plan a changeset, the server computes the dependency graph and plans each component: * components with no unresolved inputs are **queued** and planned immediately (the first graph layer) * components that depend on another's outputs are **deferred** - their inputs do not exist yet You review the plans that came back. Downstream components stay deferred until the upstream they need has actually applied. ### Applying There is a **single approval gate**: the transition from planned to applying. You authorize once. After that, the run walks the dependency graph one wave at a time: 1. the current layer applies 2. each component's outputs are captured 3. deferred downstream components render against those concrete outputs 4. they plan, then apply automatically (auto-continue) ...and so on until every component reaches a terminal state. ```mermaid flowchart LR P["plan"] --> PG["PLANNING"] --> PD["PLANNED"] -->|approve| AP["APPLYING"] --> SC["SUCCEEDED"] AP -->|"wavefront cascades,
no further approvals"| AP ``` | Run status | Meaning | | ------------------ | --------------------------------------------------------- | | `PLANNING` | first-layer plans being computed | | `PLANNED` | plans ready for review; downstream deferred | | `APPLYING` | authorized; the wavefront is unfolding | | `SUCCEEDED` | every component applied | | `PARTIALLY_FAILED` | some components applied, then a failure stopped the chain | | `FAILED` | the run failed without partial success | > **Warning:** A changeset is **not atomic**. Once an upstream component applies, that state has changed regardless of whether downstream components succeed. A mid-chain apply failure leaves real state partially changed - there is no automatic rollback. Dependents of a failed component are blocked, and the run aggregates to `PARTIALLY_FAILED`. ## What an apply records When a component applies, it records two things: the [registry revision](https://admiral.io/docs/concepts/registry.md) it now runs, and the digest of its fully rendered values. Both are immutable, so the pair names exactly what deployed. * An environment's history is the changesets applied to it. * To go back, you [revert](#revert-not-rollback). A revert is a new changeset that pins the earlier revision and values. ## Concurrency: stale rejection Because many changesets can be open against one environment at once, two of them might touch the same component. Admiral resolves this with optimistic concurrency: each changeset is based on the environment's deployed head at the time it was opened. If a parallel changeset applies first and moves a component you are also touching, your apply is **rejected as stale**. You discard and recreate against the new head. This keeps a sight-unseen apply from quietly clobbering someone else's deployment. ## Promotion Promotion moves a tested change from one environment to another in the same application (dev to prod). It is a **copy**, not a link: 1. Admiral clones the changeset's Changes (and variable changes) into a new open changeset in the target environment. 2. Conflict detection re-bases on the target environment's own deployed head, because the target has its own state. 3. You review the diff against the target and apply. The promoted changeset carries the same definitions you tested, but per-environment values resolve against the target's own variables, so you ship the same artifact configured for its destination. Promotion is same-application only. ## Revert, not rollback To undo a deployment you **revert**, following the Git model: reverting generates a *new* changeset that reverses the prior changes, which you review and apply like any other. It does not silently mutate state backward. Reverting a change that created resources produces create-style entries that an operator reviews before they apply. ## Where to go next * [Agents & Execution](https://admiral.io/docs/agents.md): The agents that carry out a run's work --- title: "Registry" canonical: "https://admiral.io/docs/concepts/registry" description: "Publish a repository you own, or pull a copy of an artifact you do not. Revisions are content-addressed, and tags are labels on those revisions." --- # Registry The registry is where a component's bytes live after they are published. An environment does not fetch those bytes again at deploy time. It pins a revision, and that pin is what a changeset reviews. A registry revision is the published bytes, identified by digest. When a component applies, it [records the revision it runs](https://admiral.io/docs/concepts/changesets-and-runs.md#what-an-apply-records). ## Two ways in ```mermaid flowchart TB Repo["Repository you own
admiral.yaml"] -->|publish| Reg["Registry
revision = sha256"] Other["Artifact you do not own
chart, module, git, archive"] -->|pull a copy| Reg Reg --> Pin["Environment
pins the digest"] ``` **Push** is for a repository the tenant owns. `admiral.yaml` at the repository root lists the component paths, and an optional name for each path. `admiral component publish` packs every declared path and pushes it. Publishing the same tree twice yields the same revision, so a pipeline that publishes everything on each push is safe. Admiral does not scan the repository for components, and it does not compute a version number. **Pull** is for an artifact the tenant does not own: a Helm chart, a Terraform module, a git tree at a ref, or an archive at a URL. Admiral pulls it, stores a copy in the tenant's registry, and records where it came from and what the reference resolved to. The console calls this "Add component". The CLI calls it `component pull`. The copy is named after the artifact unless you name it, and a chart or module version becomes a tag. A pull is a copy, not a pointer. Nothing in the deploy path fetches the upstream again. A wrapper chart is optional. Values belong on the environment. A wrapper that adds templates of its own, a chart plus a ClusterIssuer for example, is a real component and stays one. A private pull names the [credentials](https://admiral.io/docs/concepts/sources-and-catalog.md#credentials) it may use. Those credentials are an argument of that pull. They are not stored on the component, and a later pull attaches its own. ## Tags A tag is a label on a revision, the way a Docker tag names an image digest. | Tag | Moves? | | ------------------------------------ | ------------- | | Semver, such as `v1.2.0` | No. Set once. | | Floating, such as `latest` or `main` | Yes. | You refer to a revision as `NAME:TAG` or `NAME@DIGEST`. A changeset stores the digest it resolved, and it stores the reference you typed beside that digest. What was reviewed is what runs, even if the tag moves later. Revisions are not deleted. An untagged revision stays, and it stays readable by digest. A push to a tracked branch publishes the affected components under the branch name and `sha-`. A git tag shaped `vX.Y.Z` publishes under that immutable tag. Anything else publishes with no tag unless the pipeline passes one. For Helm, a change to `version` in `Chart.yaml` is the semver event, and that version is applied as an immutable tag. ## Where to go next * [Applications & Components](https://admiral.io/docs/concepts/applications-and-components.md): How an environment pins a revision as a component --- title: "Applications & Components" canonical: "https://admiral.io/docs/concepts/applications-and-components" description: "Admiral's ownership hierarchy: applications group environments like dev and prod, and each component is the per-environment desired state you own and change." --- # Applications & Components An **Application** groups related work into **Environments** like dev and prod, and a **Component** is a single thing you deploy into one environment. The Component is the per-environment desired state you own and change. ## The ownership hierarchy ```mermaid flowchart LR A["Application"] --> E["Environment"] --> C["Component"] ``` * An **Application** groups related work: a service, a stack, or a product area. * An **Environment** is a deployment target within an application: dev, staging, prod. Each is independent and carries its own variables. * A **Component** is a single deployable unit within one environment. Deploy the same thing to dev and prod and you get **two independent components**, each with its own per-environment values. A change to one does not touch the other. ```bash admiral app create --name checkout admiral env create --app checkout --name prod ``` ## Component A Component is the per-environment desired state. It is the unit a deployment acts on, and it is **self-contained**: it carries its own definition instead of linking back to a shared template. A component carries: * the **Source** to fetch from, with the **ref and path** within it * the **engine** that deploys it * its **kind** (`infrastructure` or `workload`) * its per-environment **values** * its **dependencies** on other components * its declared **inputs and outputs** * its **target**, the agent that executes it Because the component carries its own definition, "what will this environment deploy?" is answerable from the environment's own data, with no chase to a shared template that might have moved. ### Component kinds A component's kind determines which execution path deploys it: | Kind | Engines | Executes via | | ---------------- | --------------------------- | ---------------- | | `infrastructure` | terraform | Terraform agent | | `workload` | helm / kustomize / manifest | Kubernetes agent | This is covered in depth in [Agents & Execution](https://admiral.io/docs/agents.md). ### Dependencies and the graph Components in an environment form a dependency graph. A component declares the components it depends on, and a deployment uses that graph to order work: upstream components apply first, their outputs are captured, and downstream components render against those outputs before they apply. This is how a database component can hand a connection string to an application component without you wiring it by hand. See [Variables & Outputs](https://admiral.io/docs/concepts/variables-and-outputs.md). ## You never edit a Component directly This is the most important rule in the model. A Component is mutated **only** through a [Changeset](https://admiral.io/docs/concepts/changesets-and-runs.md). There is no "edit this component" action that takes effect immediately. Every change (creating a component, changing its values, destroying it) is staged as a reviewable Change, planned, and applied. The live state of an environment only ever moves forward through that gate. > **Note:** A Change that creates a component has three possible sources for its content: authored inline, prefilled from a Catalog Item, or copied from another environment's changeset (promotion). All three produce the same self-contained component; the catalog is just the convenient one. ## Lifecycle: destroy and orphan Removing a component from an environment is itself a staged Change, with two distinct intents: * **destroy**: tear down the real resources, then remove the component * **orphan**: stop managing the component but leave the real resources in place Both flow through the same changeset-plan-apply cycle as any other change, so a teardown is as reviewable as a rollout. ## Where to go next * [Variables & Outputs](https://admiral.io/docs/concepts/variables-and-outputs.md): How values and cross-component data feed rendering --- title: "Sources & Catalog" canonical: "https://admiral.io/docs/concepts/sources-and-catalog" description: "A Source tells Admiral where your code lives - git, Helm, OCI, HTTP, or Terraform - and Catalog Items are reusable templates that point at a source." --- # Sources & Catalog A **Source** says where your code lives. It is the one building block every deployment needs, and every component fetches what it deploys from a source. ## Source A Source is the "where the bytes live" primitive. It is a fetch location, nothing more: * a **type**, the protocol used to retrieve bytes * a **URL** * optional **credentials** for private locations | Source type | Fetches from | | ----------- | --------------------------- | | `git` | a Git repository | | `helm` | a Helm chart repository | | `oci` | an OCI registry | | `http` | a plain HTTP(S) endpoint | | `terraform` | a Terraform module registry | A source describes retrieval, not execution. The same `git` source can back a Terraform deployment, a Helm deployment, or a raw manifest deployment. What turns bytes into a deployment is the engine, which is declared one layer down on the Catalog Item. **CLI:** ```bash admiral source create \ --name acme-infra \ --type git \ --url https://github.com/acme/infrastructure.git ``` **Console:** 1. Open **Sources** and click **New source**. 2. Enter a **name** (for example, `acme-infra`). 3. Choose a **type** (`git`) and enter the repository **URL**. 4. For a private source, attach a **Credential**. 5. Click **Create**. Private sources reference a **Credential** to authenticate when Admiral fetches from them. ## Credentials A **Credential** is a stored, encrypted secret that a private Source references so Admiral can authenticate when it fetches. It is a first-class resource, so the secret lives in one place and is referenced rather than pasted inline. Credentials are used only by Sources. Credentials are typed by the **authentication mechanism**, not the provider: | Type | Holds | Used for | | -------------- | --------------------------------------- | ----------------------------------------------- | | `SSH_KEY` | a private key (and optional passphrase) | a private Git source over SSH | | `BASIC_AUTH` | a username and password | a private Helm or HTTP source | | `BEARER_TOKEN` | a token | an OCI registry or token-authenticated endpoint | The mechanism has to match how the source authenticates, and Admiral enforces the pairing when you attach a credential: | Source type | Accepts | | ----------- | ------------------------ | | `git` | SSH key, basic auth | | `terraform` | bearer token | | `helm` | basic auth, bearer token | | `oci` | basic auth, bearer token | | `http` | basic auth, bearer token | Secrets are encrypted at rest with envelope encryption (AES-256-GCM); the plaintext is never stored, and is decrypted only to authenticate a fetch. > **Note:** Credentials let Admiral reach your private source material, such as a Terraform module in a private Git repo or a Helm chart in a private OCI registry, so it can pull that material in and process it into deployable artifacts. They are never used to deploy. A Credential stays bound to Admiral and is not shipped out to an agent. ## Catalog Item A Catalog Item is a reusable template. It points into a source (pinning a ref and a subpath) and declares the **engine** used to deploy it. | Engine | Deploys | Runs via | | ----------- | ------------------------ | ---------------- | | `terraform` | infrastructure | Terraform agent | | `helm` | a Helm release | Kubernetes agent | | `kustomize` | a Kustomize overlay | Kubernetes agent | | `manifest` | raw Kubernetes manifests | Kubernetes agent | The source's type constrains which engines are valid; the Catalog Item picks one. A Catalog Item is a starting point, not a parent: it is a **template you copy from**, never a live runtime dependency. **CLI:** ```bash admiral catalog add \ --name postgres-rds \ --source acme-infra \ --engine terraform \ --path modules/rds ``` **Console:** 1. Open **Catalog** and click **Add item**. 2. Enter a **name** (for example, `postgres-rds`). 3. Choose the **source** (`acme-infra`) and an **engine** (`terraform`). 4. Set the **path** within the source (for example, `modules/rds`). 5. Click **Add**. ### One global catalog There is a single, global catalog. Every Catalog Item in it is discoverable by any application. There is no per-application or per-environment catalog tier. This is deliberate. A catalog is only valuable if it is curated, and the way you keep it from becoming a junk drawer is curation metadata on the items rather than a structural fork into many catalogs. The intent is for team standards to be expressed as facets you filter on (owner, labels) within the one catalog, not as separate catalogs. ### The catalog is optional A Catalog Item is only a starting point: it prefills a new Component when you create one. You can stand up an entire application without ever touching the catalog, because a Component can be authored inline or copied from another environment (see [promotion](https://admiral.io/docs/concepts/changesets-and-runs.md#promotion)). The catalog exists to make the common case fast, not to gate it. > **Note:** **Copy, not link.** When you add a Catalog Item to an environment, its definition is copied into a Component. There is no live link back, and the Component keeps no reference to the item it came from. Patching a Catalog Item never changes anything already placed. This trades automatic central updates for zero blast radius and self-contained environments, and that trade is intentional. ## How they relate ```mermaid flowchart LR CI["Catalog Item
optional template"] -. prefill .-> Cm["Component
per-env desired state"] CI -->|points into| S["Source
where bytes live"] Cm -->|fetches from| S ``` The Source and Catalog Item are the reusable, shared half of the model. Everything below them (the Component, and the revision and values it runs) is owned by a specific environment and is the subject of the [Applications & Components](https://admiral.io/docs/concepts/applications-and-components.md) page. --- title: "Variables & Outputs" canonical: "https://admiral.io/docs/concepts/variables-and-outputs" description: "Variables set a component's config per environment, and outputs captured after an upstream applies feed the components that depend on it." --- # Variables & Outputs A component's **inputs** are what its Terraform module or Helm chart accepts: a module's variables, a chart's values. A component's **values** set those inputs, and they come from two places. Variables configure a component differently per environment, and outputs hand data from one component to another. ## Where do a component's values come from? * **Variables** are configuration *you set*. They are referenced in templates as `.var`. * **Outputs** are values *captured from a component* after it deploys. They are referenced as `.component.NAME.OUTPUT` and are how data flows downstream. Both feed the same rendering step, but they come from opposite ends: variables are inputs you provide, outputs are facts a deployment produces. ## How do I configure a component per environment? A variable is config scoped to an environment. The same component deployed to dev and prod renders against each environment's own variables, so one definition produces environment-appropriate results. ``` .var.region → "us-east-1" (prod) / "us-west-2" (dev) .var.instance_size → "large" (prod) / "small" (dev) ``` Variable overrides can also ride inside a changeset, so a value change is staged and reviewed alongside the component changes it affects. ## How does one component pass data to another? When a component applies, it can emit outputs, such as a database endpoint or a VPC ID. Admiral records those outputs on the environment, and they become available to other components as `.component.NAME.OUTPUT`. This is what makes the dependency graph more than ordering. A downstream component does not just wait for its upstream; it **reads** the upstream's outputs: ```mermaid flowchart LR D["database component"] -->|applies| O["output
connection_string"] O -->|read by| A["api component
DATABASE_URL = .component.database.connection_string"] ``` Because outputs only exist after the upstream applies, a run defers any component that references an upstream output until that upstream has actually deployed. Then it renders the downstream against the concrete value and applies it. (See the [wavefront](https://admiral.io/docs/concepts/changesets-and-runs.md#applying).) ## What can a values template reference? When you plan, each component's values template renders against four namespaces, and a component that reads outputs renders again once its upstream applies: | Namespace | Holds | | ------------ | ----------------------------------------- | | `.var` | environment variables you set | | `.component` | outputs captured from other components | | `.self` | the component's own identity and metadata | | `.app` | application-level context | The result is the fully resolved set of values. It is immutable, and the component records its digest beside the [revision](https://admiral.io/docs/concepts/registry.md) it runs. That record, not the live template, is exactly what deployed. > **Note:** A component renders when you plan, and a component that reads outputs renders again once its upstream applies, against the values that exist at that moment. This is why output-dependent components must wait: rendering them earlier would template against data that does not exist yet. ## How does it fit together? ```mermaid flowchart LR V[".var
variables you set"] --> R["Render
at plan, again after
an upstream applies"] C[".component
outputs an upstream emits"] --> R R --> F["Frozen values
what the component runs"] ``` Variables let one definition serve many environments. Outputs let many components compose into one system. Together they are why an environment can be described once and deployed correctly everywhere. ## Where to go next * [Applications & Components](https://admiral.io/docs/concepts/applications-and-components.md): Where values live on a component --- title: "Concepts Overview" canonical: "https://admiral.io/docs/concepts" description: "How Admiral's applications, environments, and components nest, and how a changeset becomes a live deployment." --- # Concepts Overview Admiral coordinates infrastructure and application delivery across environments. This page lays out the model: the resources, how they nest, and how changes become deployments. ## How does Admiral model a deployment? Admiral separates **what should exist** from **who makes it real**. * *Desired state* is per-environment. A **Component** pairs your configuration with a **Source** (where the code lives), and pins a **Revision**, an immutable published version of that code. * *Execution* is pull-based. Agents run on machines you operate and in your clusters, and pull their own work. Admiral never reaches in. * *Change* is always reviewable. You never edit live state directly. You stage changes, plan them, and apply them as a single reviewable unit. ## What does Admiral deploy? Three resources form the backbone of what Admiral deploys. ```mermaid flowchart LR S["Source
where the bytes live"] -->|publish or pull| R["Revision
immutable, in the registry"] R -->|pinned by| Cm["Component
per-env desired state"] ``` * **Source** is where bytes live: a type (git, terraform, helm, oci, http), a URL, and optional [credentials](https://admiral.io/docs/concepts/sources-and-catalog.md#credentials) for private locations. * **Component** is the heart of the model: the per-environment desired state you own and edit. It holds its own definition (the registry revision it pins, how to deploy it, and its values), so an environment never depends on a shared template. * **Revision** is an immutable version of a component's code in the [registry](https://admiral.io/docs/concepts/registry.md), identified by its digest. A component pins one, and many components can pin the same one. A **Catalog Item** is an optional shortcut, not a step in the flow: a saved template you can use to prefill a Component instead of writing it out by hand. Without one, you author a Component's definition directly, or copy it from another environment. ## Who owns what? Resources nest into an ownership hierarchy: ```mermaid flowchart LR A["Application
checkout, billing"] --> E["Environment
dev, staging, prod"] --> C["Component
api, database, cache"] ``` An **Application** groups related work. Each **Environment** in it holds a set of **Components**, and a Component lives in exactly one environment. ## How does a change become a deploy? You never mutate a component directly. Every change flows through a changeset. ```mermaid flowchart LR Cs["Changeset
reviewable batch,
scoped to one env"] Ch["Change
one edit to
one component"] Rn["Run
one execution
(plan + apply)"] Lv["Live component
the revision and values
it now runs"] Cs --> Ch --> Rn --> Lv ``` * A **Changeset** is a reviewable batch of changes scoped to one environment. Many can be open at once, like branches. * A **Change** is one staged edit to one component: create, update, destroy, or orphan. * A **Run** is one execution of a changeset. Planning starts it, and plan and apply are its two phases, not two runs. * When a component applies, it records the revision it now runs and the digest of its rendered values. A run walks the dependency graph in waves. It plans what it can, defers components whose inputs depend on another component's outputs, then on apply walks the graph one wave at a time: each upstream applies, its outputs are captured, and downstream components render against those outputs and apply. There is a single approval gate at the first apply; the rest of the wavefront cascades automatically. > **Warning:** A changeset is not an atomic transaction. Once an upstream component applies, that state has changed regardless of whether downstream components succeed. There is no automatic rollback of a partial apply. ## Where does the work run? Components describe *what*. The environment binds *where it runs* through **Agents**. An agent enrolls with Admiral, runs where it has access to its target, and pulls its own work. | Component kind | Engine | Runs via | | -------------- | --------------- | ------------------------------------------------------------------------------------------- | | infrastructure | terraform | **Terraform agent** runs where it has cloud access and pulls the Terraform bundle | | workload | helm / manifest | **Kubernetes agent** runs inside the target cluster and pulls the manifests Admiral renders | Terraform and Kubernetes are the two **kinds** of the one Agent concept. An agent never has Admiral reach into it; the direction of control is always agent-to-server. ## How do values reach a component? Two kinds of values feed rendering: * **Variables** are config you set, referenced in templates as `.var`. * **Outputs** are values a component emits once it deploys, referenced as `.component.NAME.OUTPUT`. They are how one component hands data to the next. Outputs flow along the dependency graph, and across kinds: a Terraform `infrastructure` component can emit a database endpoint that a Helm `workload` component reads as an input. The wave-based apply is what makes this real: an upstream applies, its outputs are captured, and the downstream renders against the actual values before it applies. > **Note:** This is what lets you keep components small and reusable and wire them together, carrying real values across the infrastructure-to-workload boundary instead of copying them by hand. When you plan, each component's values template renders against `.var`, `.component`, `.self`, and `.app` into immutable values. A component that reads another component's outputs renders again once that upstream applies. The component records their digest beside the revision it runs. ## Where to go next * [Applications & Components](https://admiral.io/docs/concepts/applications-and-components.md): The ownership hierarchy and per-environment desired state * [Sources & Catalog](https://admiral.io/docs/concepts/sources-and-catalog.md): Where a component's code comes from, and the optional template * [Registry](https://admiral.io/docs/concepts/registry.md): Push a repository you own, or pull a copy of an artifact you do not * [State](https://admiral.io/docs/concepts/state.md): One Terraform state per component, hosted or in your own backend * [Variables & Outputs](https://admiral.io/docs/concepts/variables-and-outputs.md): How configuration and cross-component data flow * [Changesets & Runs](https://admiral.io/docs/concepts/changesets-and-runs.md): How a staged change becomes a deployment * [Drift](https://admiral.io/docs/concepts/drift.md): A change outside the changeset, shown on review --- title: "State" canonical: "https://admiral.io/docs/concepts/state" description: "Admiral hosts one Terraform state per component in an environment, or a component keeps the backend it already uses." --- # State A Terraform component keeps its state in Admiral by default, or in the backend it already uses. A Helm or manifest component has no Terraform state. ## How is state organized? Each Terraform component in an environment has one state. An environment can hold many components published from the same registry entry, and each of those components has its own state. The address you see is the application, the environment, and the component, as in `my-api/prod/users-db`. On the wire the name is `__`, and the organization is your tenant. Admiral names do not contain `_`, so the three parts split back apart. State is stored against the component itself, so renaming the component does not move the state. ## How do a run and a person reach hosted state? Admiral serves the part of the HCP Terraform API that the Terraform `cloud` block uses to store and lock state, at `api.admiral.io`. Terraform and OpenTofu still plan and apply where they were started. Admiral stores the state. The HTTP backend is not offered. ```mermaid flowchart LR Person["Person
personal API key"] --> API["Admiral
cloud backend"] Agent["Terraform agent
per-run token"] --> API API --> State["One state
per Terraform component"] ``` A run and a person use that same backend. * Admiral writes the `cloud` block into the [run artifact](https://admiral.io/docs/security/secrets.md#how-do-i-keep-a-secret-out-of-admiral). The Terraform agent receives `TF_TOKEN_`, a credential Admiral issues, scoped to the one component state it is working on, and the token expires with the run. The agent's own token for Admiral is never the state credential. * A person uses a [personal API key](https://admiral.io/docs/access.md#personal-api-keys) limited to the Terraform API. It acts with that person's permissions, and the limit keeps it to the Terraform API. The `admiral` CLI will put that key on the machine as a Terraform credentials helper, so `terraform` finds it for `api.admiral.io` with no extra step. The helper ships with hosted state. ## Can I keep my own backend? Yes. A Terraform component can keep the backend it already uses, such as Amazon S3, Google Cloud Storage, Azure Blob Storage, or HCP Terraform. The Terraform agent reaches that backend with the credentials it already has on the machine it runs on, and Admiral never holds that state. The rest of this page is about hosted state. None of it applies to a backend you keep: the per-run token, state writes from people through Admiral, and the encryption Admiral applies to what it stores. ## Can I write state outside a changeset? You can read and write state outside a changeset. `state mv`, `import`, and `state rm` are ordinary work, and a platform that allowed state writes only through its own runs would have no way to do them. A write from outside a run moves the environment. Open changesets rebase onto that state, and an approval stands only when the new plan is identical to the one that was approved. The state lock follows the environment lock, so a partial apply that is holding the environment also refuses a person's write. Every state version records who wrote it, a run or a person. Existing state is adopted by a person with `terraform init -migrate-state` into this backend. ## Where to go next * [Secrets](https://admiral.io/docs/security/secrets.md): Why a secret fed to an ordinary input can land in state * [Authentication](https://admiral.io/docs/access.md): The personal API key a person uses to reach hosted state --- title: "Check an apply's plan" canonical: "https://admiral.io/docs/api/agent/AgentRuntimeAPI_CheckApplyPlan" --- # Check an apply's plan `POST https://api.admiral.io/v1/agent/jobs/check-plan` Scope: `agent:exec` ### Request body - `attempt` (Attempt, required): Attempt names the attempt a call belongs to. - `job_id` (string (uuid), required) - `attempt` (integer (int32)): Value at least 1. - `lease_token` (string): Length 16 to 128. - `plan` (PlanResult, required): PlanResult is a PLAN job's typed outcome. Its digest is the plan's identity: two plans with the same changes have the same digest. - `components` (array of ComponentPlan): Items at most 256. - `component` (string): Length at most 63. - `changes` (array of ResourceChange): Items at most 5000. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `action` (ResourceAction): enum.defined_only = true One of `NO_OP`, `CREATE`, `UPDATE`, `REPLACE`, `DESTROY`, `ORPHAN`. - `diff_digest` (string): `sha256:` of this resource's diff in the PlanDiff. Empty for NO_OP. Length at most 71. - `diff_digest` (string): `sha256:` of the PlanDiff uploaded for this attempt. Length at most 71. ### Response 200 Success - `proceed` (boolean) - `message` (string): Why not, when `proceed` is false. --- title: "Upload a plan's diffs" canonical: "https://admiral.io/docs/api/agent/AgentRuntimeAPI_UploadPlanDiff" --- # Upload a plan's diffs `POST https://api.admiral.io/v1/agent/jobs/plan-diff` Scope: `agent:exec` ### Request body - `attempt` (Attempt, required): Attempt names the attempt a call belongs to. - `job_id` (string (uuid), required) - `attempt` (integer (int32)): Value at least 1. - `lease_token` (string): Length 16 to 128. - `diff` (PlanDiff, required): PlanDiff is a plan's full diffs, stored apart from the job. - `resources` (array of ResourceDiff): Items at most 5000. - `component` (string): Length at most 63. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `diff` (string): Unified diff from the live object to the desired one, both normalized. A Secret's data shows each key as added, changed or removed, never a value. Length at most 1048576. ### Response 200 Success - `diff_digest` (string): `sha256:` of the diff as stored. --- title: "List agents" canonical: "https://admiral.io/docs/api/agents/AgentAPI_ListAgents" --- # List agents `GET https://api.admiral.io/v1/agents` Scope: `agent:read` ### Query parameters - `cluster_id` (string (uuid)): The cluster_id query parameter. - `application_id` (string (uuid)): Only agents this application's environments may select. - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. ### Response 200 Success - `agents` (array of Agent) - `id` (string): Read-only. - `cluster_id` (string): Read-only. - `name` (string) - `namespace` (string): Read-only. - `service_account` (string): Read-only. - `ceiling` (AgentCeiling): AgentCeiling is what the agent's owner allows it, whatever its RBAC allows. The plan refuses what falls outside it. - `allow_namespace_creation` (boolean) - `allowed_namespaces` (array of string): Glob patterns; empty allows every namespace. Items at most 64. - `denied_namespaces` (array of string): Glob patterns. A namespace that matches is refused even when `allowed_namespaces` matches it too. Items at most 64. - `health` (AgentHealth): One of `AGENT_HEALTH_UNSPECIFIED`, `NEW`, `ONLINE`, `OFFLINE`. Read-only. - `report` (AgentReport): What the agent last reported. Absent until it does. Read-only. - `agent_version` (string) - `protocol_version` (integer (int32)) - `kube_version` (string) - `api_versions` (array of string) - `capabilities` (AgentCapabilities): AgentCapabilities is what the agent's own RBAC lets it do, as it measured. - `can_create_namespaces` (boolean) - `writable_namespaces` (array of string): Namespaces it may write. Empty when `all_namespaces` is set. - `all_namespaces` (boolean) - `can_write_cluster_scoped` (boolean) - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `next_page_token` (string) --- title: "Create an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_CreateAgent" --- # Create an agent `POST https://api.admiral.io/v1/agents` Scope: `agent:write` ### Request body - `cluster_id` (string (uuid), required) - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `namespace` (string, required): The namespace and service account the agent runs as. Pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `service_account` (string, required): Pattern `^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$`. Length 1 to 253. - `ceiling` (AgentCeiling): AgentCeiling is what the agent's owner allows it, whatever its RBAC allows. The plan refuses what falls outside it. - `allow_namespace_creation` (boolean) - `allowed_namespaces` (array of string): Glob patterns; empty allows every namespace. Items at most 64. - `denied_namespaces` (array of string): Glob patterns. A namespace that matches is refused even when `allowed_namespaces` matches it too. Items at most 64. - `grants` (array of AgentGrant): Who may use it. Absent grants the organization when this is its first agent, and nobody otherwise. Items at most 64. - Exactly one of `organization`, `group_id`, `application_id`, `environment_id` is set. - `application_id` (string (uuid)) - `environment_id` (string (uuid)) - `group_id` (string (uuid)): Any member of the group can select the agent for an environment they can edit. - `organization` (boolean): Every environment in the organization. Must be `true`. - `enrollment_key` (boolean): Issue a single-use enrollment key with the agent. ### Response 200 Success - `agent` (Agent) - `id` (string): Read-only. - `cluster_id` (string): Read-only. - `name` (string) - `namespace` (string): Read-only. - `service_account` (string): Read-only. - `ceiling` (AgentCeiling): AgentCeiling is what the agent's owner allows it, whatever its RBAC allows. The plan refuses what falls outside it. - `allow_namespace_creation` (boolean) - `allowed_namespaces` (array of string): Glob patterns; empty allows every namespace. Items at most 64. - `denied_namespaces` (array of string): Glob patterns. A namespace that matches is refused even when `allowed_namespaces` matches it too. Items at most 64. - `health` (AgentHealth): One of `AGENT_HEALTH_UNSPECIFIED`, `NEW`, `ONLINE`, `OFFLINE`. Read-only. - `report` (AgentReport): What the agent last reported. Absent until it does. Read-only. - `agent_version` (string) - `protocol_version` (integer (int32)) - `kube_version` (string) - `api_versions` (array of string) - `capabilities` (AgentCapabilities): AgentCapabilities is what the agent's own RBAC lets it do, as it measured. - `can_create_namespaces` (boolean) - `writable_namespaces` (array of string): Namespaces it may write. Empty when `all_namespaces` is set. - `all_namespaces` (boolean) - `can_write_cluster_scoped` (boolean) - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `grants` (array of AgentGrant) - Exactly one of `organization`, `group_id`, `application_id`, `environment_id` is set. - `application_id` (string (uuid)) - `environment_id` (string (uuid)) - `group_id` (string (uuid)): Any member of the group can select the agent for an environment they can edit. - `organization` (boolean): Every environment in the organization. Must be `true`. - `enrollment_key` (EnrollmentKey): Set when asked for. Shown once. - `key` (string) - `expires_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Retrieve an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_GetAgent" --- # Retrieve an agent `GET https://api.admiral.io/v1/agents/{agent_id}` Scope: `agent:read` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Response 200 Success - `agent` (Agent) - `id` (string): Read-only. - `cluster_id` (string): Read-only. - `name` (string) - `namespace` (string): Read-only. - `service_account` (string): Read-only. - `ceiling` (AgentCeiling): AgentCeiling is what the agent's owner allows it, whatever its RBAC allows. The plan refuses what falls outside it. - `allow_namespace_creation` (boolean) - `allowed_namespaces` (array of string): Glob patterns; empty allows every namespace. Items at most 64. - `denied_namespaces` (array of string): Glob patterns. A namespace that matches is refused even when `allowed_namespaces` matches it too. Items at most 64. - `health` (AgentHealth): One of `AGENT_HEALTH_UNSPECIFIED`, `NEW`, `ONLINE`, `OFFLINE`. Read-only. - `report` (AgentReport): What the agent last reported. Absent until it does. Read-only. - `agent_version` (string) - `protocol_version` (integer (int32)) - `kube_version` (string) - `api_versions` (array of string) - `capabilities` (AgentCapabilities): AgentCapabilities is what the agent's own RBAC lets it do, as it measured. - `can_create_namespaces` (boolean) - `writable_namespaces` (array of string): Namespaces it may write. Empty when `all_namespaces` is set. - `all_namespaces` (boolean) - `can_write_cluster_scoped` (boolean) - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Update an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_UpdateAgent" --- # Update an agent `PATCH https://api.admiral.io/v1/agents/{agent_id}` Scope: `agent:write` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Request body - `name` (string): Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length at most 63. - `ceiling` (AgentCeiling): Replaces the ceiling when set. - `allow_namespace_creation` (boolean) - `allowed_namespaces` (array of string): Glob patterns; empty allows every namespace. Items at most 64. - `denied_namespaces` (array of string): Glob patterns. A namespace that matches is refused even when `allowed_namespaces` matches it too. Items at most 64. ### Response 200 Success - `agent` (Agent) - `id` (string): Read-only. - `cluster_id` (string): Read-only. - `name` (string) - `namespace` (string): Read-only. - `service_account` (string): Read-only. - `ceiling` (AgentCeiling): AgentCeiling is what the agent's owner allows it, whatever its RBAC allows. The plan refuses what falls outside it. - `allow_namespace_creation` (boolean) - `allowed_namespaces` (array of string): Glob patterns; empty allows every namespace. Items at most 64. - `denied_namespaces` (array of string): Glob patterns. A namespace that matches is refused even when `allowed_namespaces` matches it too. Items at most 64. - `health` (AgentHealth): One of `AGENT_HEALTH_UNSPECIFIED`, `NEW`, `ONLINE`, `OFFLINE`. Read-only. - `report` (AgentReport): What the agent last reported. Absent until it does. Read-only. - `agent_version` (string) - `protocol_version` (integer (int32)) - `kube_version` (string) - `api_versions` (array of string) - `capabilities` (AgentCapabilities): AgentCapabilities is what the agent's own RBAC lets it do, as it measured. - `can_create_namespaces` (boolean) - `writable_namespaces` (array of string): Namespaces it may write. Empty when `all_namespaces` is set. - `all_namespaces` (boolean) - `can_write_cluster_scoped` (boolean) - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Delete an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_DeleteAgent" --- # Delete an agent `DELETE https://api.admiral.io/v1/agents/{agent_id}` Scope: `agent:write` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Response 200 Success Type: DeleteAgentResponse. --- title: "Issue an enrollment key" canonical: "https://admiral.io/docs/api/agents/AgentAPI_CreateEnrollmentKey" --- # Issue an enrollment key `POST https://api.admiral.io/v1/agents/{agent_id}/enrollment-keys` Scope: `agent:write` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Response 200 Success - `enrollment_key` (EnrollmentKey) - `key` (string) - `expires_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "List who may use an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_ListAgentGrants" --- # List who may use an agent `GET https://api.admiral.io/v1/agents/{agent_id}/grants` Scope: `agent:read` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Response 200 Success - `grants` (array of AgentGrant) - Exactly one of `organization`, `group_id`, `application_id`, `environment_id` is set. - `application_id` (string (uuid)) - `environment_id` (string (uuid)) - `group_id` (string (uuid)): Any member of the group can select the agent for an environment they can edit. - `organization` (boolean): Every environment in the organization. Must be `true`. --- title: "Grant use of an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_GrantAgentUse" --- # Grant use of an agent `POST https://api.admiral.io/v1/agents/{agent_id}/grants` Scope: `agent:write` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Request body - `grant` (AgentGrant, required): AgentGrant lets environments select an agent. Set exactly one target; an agent can hold several grants. - Exactly one of `organization`, `group_id`, `application_id`, `environment_id` is set. - `application_id` (string (uuid)) - `environment_id` (string (uuid)) - `group_id` (string (uuid)): Any member of the group can select the agent for an environment they can edit. - `organization` (boolean): Every environment in the organization. Must be `true`. ### Response 200 Success Type: GrantAgentUseResponse. --- title: "Revoke use of an agent" canonical: "https://admiral.io/docs/api/agents/AgentAPI_RevokeAgentUse" --- # Revoke use of an agent `POST https://api.admiral.io/v1/agents/{agent_id}/grants/revoke` Scope: `agent:write` ### Path parameters - `agent_id` (string (uuid), required): The agent_id path parameter. ### Request body - `grant` (AgentGrant, required): AgentGrant lets environments select an agent. Set exactly one target; an agent can hold several grants. - Exactly one of `organization`, `group_id`, `application_id`, `environment_id` is set. - `application_id` (string (uuid)) - `environment_id` (string (uuid)) - `group_id` (string (uuid)): Any member of the group can select the agent for an environment they can edit. - `organization` (boolean): Every environment in the organization. Must be `true`. ### Response 200 Success Type: RevokeAgentUseResponse. --- title: "List applications" canonical: "https://admiral.io/docs/api/applications/ApplicationAPI_ListApplications" --- # List applications `GET https://api.admiral.io/v1/applications` Scope: `app:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `name`: filter by application name. - `labels.key`: filter by label key. Example: `field['name'] = 'inventory-api' AND field['labels.team'] = 'logistics'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of applications to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `applications` (array of Application): The list of applications. - `id` (string (uuid)): Unique identifier for the application (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "inventory-api"). Unique within the tenant. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the application's purpose (e.g., "Core inventory service tracking warehouse stock and fulfillment"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering applications (e.g., `{"team": "logistics", "tier": "critical"}`). - `created_by` (ActorRef): The user or agent who created this application (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the application was created. Read-only. - `updated_at` (Timestamp): When the application was last updated. Read-only. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Create an application" canonical: "https://admiral.io/docs/api/applications/ApplicationAPI_CreateApplication" --- # Create an application `POST https://api.admiral.io/v1/applications` Scope: `app:write` ### Request body - `name` (string, required): URL-safe, human-readable identifier (e.g., "inventory-api"). Unique within the tenant. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the application's purpose. Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering applications. ### Response 200 Success - `application` (Application): The created application. - `id` (string (uuid)): Unique identifier for the application (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "inventory-api"). Unique within the tenant. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the application's purpose (e.g., "Core inventory service tracking warehouse stock and fulfillment"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering applications (e.g., `{"team": "logistics", "tier": "critical"}`). - `created_by` (ActorRef): The user or agent who created this application (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the application was created. Read-only. - `updated_at` (Timestamp): When the application was last updated. Read-only. --- title: "Update an application" canonical: "https://admiral.io/docs/api/applications/ApplicationAPI_UpdateApplication" --- # Update an application `PATCH https://api.admiral.io/v1/applications/{application.id}` Scope: `app:write` ### Path parameters - `application.id` (string (uuid), required): Unique identifier for the application (UUID). Read-only. ### Request body - `update_mask` (FieldMask): The set of fields to update. Optional; if omitted, all populated fields are updated. Pass `*` for full replacement. Supported fields: `name`, `description`, `labels`. ### Response 200 Success - `application` (Application): The updated application. - `id` (string (uuid)): Unique identifier for the application (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "inventory-api"). Unique within the tenant. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the application's purpose (e.g., "Core inventory service tracking warehouse stock and fulfillment"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering applications (e.g., `{"team": "logistics", "tier": "critical"}`). - `created_by` (ActorRef): The user or agent who created this application (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the application was created. Read-only. - `updated_at` (Timestamp): When the application was last updated. Read-only. --- title: "Retrieve an application" canonical: "https://admiral.io/docs/api/applications/ApplicationAPI_GetApplication" --- # Retrieve an application `GET https://api.admiral.io/v1/applications/{application_id}` Scope: `app:read` ### Path parameters - `application_id` (string (uuid), required): The unique identifier of the application (UUID). ### Response 200 Success - `application` (Application): The retrieved application. - `id` (string (uuid)): Unique identifier for the application (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "inventory-api"). Unique within the tenant. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the application's purpose (e.g., "Core inventory service tracking warehouse stock and fulfillment"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering applications (e.g., `{"team": "logistics", "tier": "critical"}`). - `created_by` (ActorRef): The user or agent who created this application (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the application was created. Read-only. - `updated_at` (Timestamp): When the application was last updated. Read-only. --- title: "Delete an application" canonical: "https://admiral.io/docs/api/applications/ApplicationAPI_DeleteApplication" --- # Delete an application `DELETE https://api.admiral.io/v1/applications/{application_id}` Scope: `app:write` ### Path parameters - `application_id` (string (uuid), required): The unique identifier of the application to delete (UUID). ### Query parameters - `force` (boolean): When true, bypass the children-exist check and cascade-delete all environments and their runs (metadata records only). ### Response 200 Success Type: DeleteApplicationResponse. --- title: "List change sets" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_ListChangeSets" --- # List change sets `GET https://api.admiral.io/v1/changesets` Scope: `changeset:read` ### Query parameters - `environment_id` (string (uuid), required): The environment_id query parameter. - `status` (ChangeSetStatus): UNSPECIFIED lists every status. enum.defined_only = true One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. ### Response 200 Success - `change_sets` (array of ChangeSet) - `id` (string): `cs-` and twelve lowercase base36 characters. Read-only. - `application_id` (string): Read-only. - `environment_id` (string): Read-only. - `title` (string): Read-only. - `description` (string): Read-only. - `status` (ChangeSetStatus): One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. Read-only. - `head_revision` (integer (int32)): 0 until the first edit. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reverts_change_set_id` (string): Set on a change set made by RevertChangeSet: the change set it reverts. It may apply while that change set's partial apply holds the environment. Read-only. - `next_page_token` (string) --- title: "Create a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_CreateChangeSet" --- # Create a change set `POST https://api.admiral.io/v1/changesets` Scope: `changeset:write` ### Request body - `environment_id` (string (uuid), required) - `title` (string): Length at most 256. - `description` (string): Length at most 4096. - `edits` (array of Edit): Items at most 100. - Exactly one of `add_component`, `set_value`, `set_null`, `unset_value`, `set_pin`, `replace_values`, `remove_component`, `set_placement`, `set_depends_on` is set. - `add_component` (AddComponent): AddComponent creates a component instance from the registry. The name is reserved in the environment until the draft is discarded or the component is removed from it. - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `source` (RegistryRef, required): RegistryRef is a registry component and a tag or digest in it. A tag is resolved when the edit is made; only the revision is stored. - `namespace` (string): Empty means the default namespace. Pattern `^([a-z]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `reference` (string, required): A tag or a `sha256:` digest. Pattern `^(sha256:[0-9a-f]{64}|[A-Za-z0-9][A-Za-z0-9._+-]{0,127})$`. Length 1 to 128. - `values_json` (string): A JSON object. Empty means no values. Length at most 1048576. - `remove_component` (RemoveComponent): RemoveComponent drops a component this draft adds, or destroys a live one. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `replace_values` (ReplaceValues): ReplaceValues makes a component's values exactly this tree: an upload. Refused unless `from_revision` is the head the tree was downloaded at. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `tree_json` (string, required): A JSON object. Length 2 to 1048576. - `from_revision` (integer (int32)): The head revision GetComponentValues reported; 0 for a draft with none. Value at least 0. - `set_depends_on` (SetDependsOn): SetDependsOn replaces the components a component applies after. Empty clears it. A cycle is refused. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. - `depends_on` (array of string): Items at most 32. - `set_null` (SetNull): SetNull writes null at a path, which clears a chart default. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `path` (array of PathSegment): Items 1 to 32. - `key` (string, required): Length 1 to 256. - `set_pin` (SetPin): SetPin moves a component to another revision of the same registry component. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `reference` (string, required): A tag or a `sha256:` digest. Pattern `^(sha256:[0-9a-f]{64}|[A-Za-z0-9][A-Za-z0-9._+-]{0,127})$`. Length 1 to 128. - `set_placement` (SetPlacement): SetPlacement replaces where a component goes. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `placement` (Placement, required): Placement is where a component's objects go, per kind of target. A component carries at most the block for its kind. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `set_value` (SetValue): SetValue writes a value at a path, creating maps on the way, as `helm --set` does. A map value replaces what was there. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `path` (array of PathSegment): Items 1 to 32. - `key` (string, required): Length 1 to 256. - `value_json` (string, required): JSON text, not null: null is SetNull. Length 1 to 1048576. - `unset_value` (UnsetValue): UnsetValue removes a path, so the default applies. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `path` (array of PathSegment): Items 1 to 32. - `key` (string, required): Length 1 to 256. - `plan` (boolean): Ask for a plan of the revision the edits cut, as PlanChangeSet does. ### Response 200 Success - `change_set` (ChangeSet) - `id` (string): `cs-` and twelve lowercase base36 characters. Read-only. - `application_id` (string): Read-only. - `environment_id` (string): Read-only. - `title` (string): Read-only. - `description` (string): Read-only. - `status` (ChangeSetStatus): One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. Read-only. - `head_revision` (integer (int32)): 0 until the first edit. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reverts_change_set_id` (string): Set on a change set made by RevertChangeSet: the change set it reverts. It may apply while that change set's partial apply holds the environment. Read-only. - `revision` (Revision): Absent when the request carried no edits. - `number` (integer (int32)) - `change_set_id` (string) - `base_generation` (string (int64)): The environment's generation when the base was taken. - `cause` (RevisionCause): RevisionCause says why a revision was cut. Only EDIT is written until rebase exists. One of `REVISION_CAUSE_UNSPECIFIED`, `EDIT`, `REBASE`. - `violations` (array of Violation) - `component` (string) - `path` (string): Display form: `image.tag`, `ingress."a.b"`. - `message` (string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `entries` (array of Entry): Empty in a listing. - `component_id` (string) - `component` (string) - `action` (EntryAction): One of `ENTRY_ACTION_UNSPECIFIED`, `CREATE`, `UPDATE`, `DESTROY`. - `pin` (Pin): The revision the component is pinned to after this change set: set on CREATE and when the pin moves. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `base_digest` (string): Empty on CREATE. - `result_digest` (string): Empty on DESTROY. - `ops` (array of ValueOp) - `path` (array of PathSegment) - `key` (string, required): Length 1 to 256. - `op` (ValueOpKind): One of `VALUE_OP_KIND_UNSPECIFIED`, `SET`, `SET_NULL`, `REMOVE`. - `value_json` (string): JSON text; empty unless op is SET. - `from_present` (boolean): Whether the base had the key; a null there is present. - `from_value_json` (string): JSON text; empty when from_present is false. - `placement` (Placement): Where the component goes after this change set. Empty on DESTROY. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `depends_on` (array of string): Components this one applies after, after this change set. - `warnings` (array of string): Accepted, but worth saying: a deprecated pin, a check the contract could not make. - `prepare` (Prepare): Set when `plan` was asked for. - `revision` (integer (int32)) - `status` (PrepareStatus): PrepareStatus is where a revision's prepare stands. One of `PREPARE_STATUS_UNSPECIFIED`, `QUEUED`, `RUNNING`, `PREPARED`, `FAILED`, `SUPERSEDED`. - `artifact_digest` (string): `sha256:` of the run artifact; set once PREPARED. - `findings` (array of Finding) - `component` (string) - `code` (FindingCode): FindingCode names something a prepare noticed but did not refuse. One of `FINDING_CODE_UNSPECIFIED`, `LOOKUP_USED`, `NONDETERMINISTIC`, `NO_CAPABILITIES`, `SCOPE_GUESSED`. - `message` (string) - `details` (array of string): For NONDETERMINISTIC, each `Kind/namespace/name field` that differs. - `error` (PrepareError): Set when FAILED. - `class` (PrepareErrorClass): PrepareErrorClass says whether asking again can help. One of `PREPARE_ERROR_CLASS_UNSPECIFIED`, `RENDER`, `INFRA`. - `component` (string): Empty when the failure is not one component's. - `message` (string) - `requested_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `requested_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `requested_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `attempts` (integer (int32)) --- title: "Retrieve a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetChangeSet" --- # Retrieve a change set `GET https://api.admiral.io/v1/changesets/{change_set_id}` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Response 200 Success - `change_set` (ChangeSet) - `id` (string): `cs-` and twelve lowercase base36 characters. Read-only. - `application_id` (string): Read-only. - `environment_id` (string): Read-only. - `title` (string): Read-only. - `description` (string): Read-only. - `status` (ChangeSetStatus): One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. Read-only. - `head_revision` (integer (int32)): 0 until the first edit. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reverts_change_set_id` (string): Set on a change set made by RevertChangeSet: the change set it reverts. It may apply while that change set's partial apply holds the environment. Read-only. - `head` (Revision): Absent before the first edit. - `number` (integer (int32)) - `change_set_id` (string) - `base_generation` (string (int64)): The environment's generation when the base was taken. - `cause` (RevisionCause): RevisionCause says why a revision was cut. Only EDIT is written until rebase exists. One of `REVISION_CAUSE_UNSPECIFIED`, `EDIT`, `REBASE`. - `violations` (array of Violation) - `component` (string) - `path` (string): Display form: `image.tag`, `ingress."a.b"`. - `message` (string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `entries` (array of Entry): Empty in a listing. - `component_id` (string) - `component` (string) - `action` (EntryAction): One of `ENTRY_ACTION_UNSPECIFIED`, `CREATE`, `UPDATE`, `DESTROY`. - `pin` (Pin): The revision the component is pinned to after this change set: set on CREATE and when the pin moves. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `base_digest` (string): Empty on CREATE. - `result_digest` (string): Empty on DESTROY. - `ops` (array of ValueOp) - `path` (array of PathSegment) - `key` (string, required): Length 1 to 256. - `op` (ValueOpKind): One of `VALUE_OP_KIND_UNSPECIFIED`, `SET`, `SET_NULL`, `REMOVE`. - `value_json` (string): JSON text; empty unless op is SET. - `from_present` (boolean): Whether the base had the key; a null there is present. - `from_value_json` (string): JSON text; empty when from_present is false. - `placement` (Placement): Where the component goes after this change set. Empty on DESTROY. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `depends_on` (array of string): Components this one applies after, after this change set. - `latest_prepare` (Prepare): The latest revision asked to be planned; absent when none was. - `revision` (integer (int32)) - `status` (PrepareStatus): PrepareStatus is where a revision's prepare stands. One of `PREPARE_STATUS_UNSPECIFIED`, `QUEUED`, `RUNNING`, `PREPARED`, `FAILED`, `SUPERSEDED`. - `artifact_digest` (string): `sha256:` of the run artifact; set once PREPARED. - `findings` (array of Finding) - `component` (string) - `code` (FindingCode): FindingCode names something a prepare noticed but did not refuse. One of `FINDING_CODE_UNSPECIFIED`, `LOOKUP_USED`, `NONDETERMINISTIC`, `NO_CAPABILITIES`, `SCOPE_GUESSED`. - `message` (string) - `details` (array of string): For NONDETERMINISTIC, each `Kind/namespace/name field` that differs. - `error` (PrepareError): Set when FAILED. - `class` (PrepareErrorClass): PrepareErrorClass says whether asking again can help. One of `PREPARE_ERROR_CLASS_UNSPECIFIED`, `RENDER`, `INFRA`. - `component` (string): Empty when the failure is not one component's. - `message` (string) - `requested_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `requested_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `requested_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `attempts` (integer (int32)) - `plan_stale` (boolean): True when the head is newer than latest_prepare's revision. --- title: "Accept a partial apply" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_AcceptPartialApply" --- # Accept a partial apply `POST https://api.admiral.io/v1/changesets/{change_set_id}/accept-partial` Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Request body - `reason` (string, required): Length 1 to 1024. ### Response 200 Success - `apply` (Apply): Apply is a revision's apply: its APPLY job and what happened to each component, in apply order. - `revision` (integer (int32)) - `job_id` (string) - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `plan_digest` (string) - `components` (array of ComponentApply) - `component` (string) - `status` (JobStatus): QUEUED until reached, then SUCCEEDED or FAILED. One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `message` (string) - `applied_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `accepted_by` (ActorRef): Set when a partial apply was accepted as the environment's new state. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `accepted_reason` (string) - `accepted_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Apply a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_ApplyChangeSet" --- # Apply a change set `POST https://api.admiral.io/v1/changesets/{change_set_id}/apply` FAILED_PRECONDITION when the plan is not current or did not succeed, an approval is required and missing, the change set was cut from an older generation of the environment (rebase needed), or another change set holds the environment. Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Request body - `revision` (integer (int32), required): Value at least 1. - `plan_digest` (string, required): The plan being applied; refused unless it is the revision's current plan. Pattern `^sha256:[0-9a-f]{64}$`. ### Response 200 Success - `apply` (Apply): Apply is a revision's apply: its APPLY job and what happened to each component, in apply order. - `revision` (integer (int32)) - `job_id` (string) - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `plan_digest` (string) - `components` (array of ComponentApply) - `component` (string) - `status` (JobStatus): QUEUED until reached, then SUCCEEDED or FAILED. One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `message` (string) - `applied_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `accepted_by` (ActorRef): Set when a partial apply was accepted as the environment's new state. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `accepted_reason` (string) - `accepted_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Approve a change set's plan" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_ApproveChangeSet" --- # Approve a change set's plan `POST https://api.admiral.io/v1/changesets/{change_set_id}/approve` FAILED_PRECONDITION when `plan_digest` is not the revision's current plan. Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Request body - `revision` (integer (int32), required): Value at least 1. - `plan_digest` (string, required): Pattern `^sha256:[0-9a-f]{64}$`. - `reason` (string): Required for a self-approval. Length at most 1024. ### Response 200 Success - `approval` (Approval): Approval is a sign-off on one plan of a revision. - `revision` (integer (int32)) - `plan_digest` (string) - `approved_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `self_approval` (boolean): The approver revised the change set and was the only one able to approve. - `reason` (string) - `approved_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Retrieve a component's values" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetComponentValues" --- # Retrieve a component's values `GET https://api.admiral.io/v1/changesets/{change_set_id}/components/{component}/values` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `component` (string, required): The component path parameter. Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. ### Response 200 Success - `tree_json` (string): A JSON object. - `base_digest` (string): The values the change set started from; empty for a component it adds. - `result_digest` (string) - `head_revision` (integer (int32)) --- title: "Diff a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_DiffChangeSet" --- # Diff a change set `GET https://api.admiral.io/v1/changesets/{change_set_id}/diff` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Response 200 Success - `revision` (integer (int32)): The head revision diffed; 0 when there is none. - `components` (array of ComponentDiff) - `component` (string) - `action` (EntryAction): One of `ENTRY_ACTION_UNSPECIFIED`, `CREATE`, `UPDATE`, `DESTROY`. - `old_pin` (Pin): Absent on CREATE. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `new_pin` (Pin): Absent on DESTROY. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `paths` (array of PathDiff) - `path` (array of PathSegment) - `key` (string, required): Length 1 to 256. - `display_path` (string) - `before_present` (boolean) - `before_json` (string) - `after_present` (boolean) - `after_json` (string) - `violations` (array of Violation) - `component` (string) - `path` (string): Display form: `image.tag`, `ingress."a.b"`. - `message` (string) --- title: "Discard a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_DiscardChangeSet" --- # Discard a change set `POST https://api.admiral.io/v1/changesets/{change_set_id}/discard` Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Response 200 Success - `change_set` (ChangeSet) - `id` (string): `cs-` and twelve lowercase base36 characters. Read-only. - `application_id` (string): Read-only. - `environment_id` (string): Read-only. - `title` (string): Read-only. - `description` (string): Read-only. - `status` (ChangeSetStatus): One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. Read-only. - `head_revision` (integer (int32)): 0 until the first edit. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reverts_change_set_id` (string): Set on a change set made by RevertChangeSet: the change set it reverts. It may apply while that change set's partial apply holds the environment. Read-only. --- title: "Edit a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_EditChangeSet" --- # Edit a change set `POST https://api.admiral.io/v1/changesets/{change_set_id}/edit` FAILED_PRECONDITION when `if_revision` or an upload's `from_revision` is not the head (the message names the head), when the change set is not a draft, and when a pin names a revoked revision (the message carries the recorded reason). ALREADY_EXISTS when a component name is live or held by another draft (the message names which). A contract violation is accepted: it is stored on the revision and returned. Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Request body - `if_revision` (integer (int32)): When set, refused unless the head is this revision. Value at least 0. - `edits` (array of Edit): Items 1 to 100. - Exactly one of `add_component`, `set_value`, `set_null`, `unset_value`, `set_pin`, `replace_values`, `remove_component`, `set_placement`, `set_depends_on` is set. - `add_component` (AddComponent): AddComponent creates a component instance from the registry. The name is reserved in the environment until the draft is discarded or the component is removed from it. - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `source` (RegistryRef, required): RegistryRef is a registry component and a tag or digest in it. A tag is resolved when the edit is made; only the revision is stored. - `namespace` (string): Empty means the default namespace. Pattern `^([a-z]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `reference` (string, required): A tag or a `sha256:` digest. Pattern `^(sha256:[0-9a-f]{64}|[A-Za-z0-9][A-Za-z0-9._+-]{0,127})$`. Length 1 to 128. - `values_json` (string): A JSON object. Empty means no values. Length at most 1048576. - `remove_component` (RemoveComponent): RemoveComponent drops a component this draft adds, or destroys a live one. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `replace_values` (ReplaceValues): ReplaceValues makes a component's values exactly this tree: an upload. Refused unless `from_revision` is the head the tree was downloaded at. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `tree_json` (string, required): A JSON object. Length 2 to 1048576. - `from_revision` (integer (int32)): The head revision GetComponentValues reported; 0 for a draft with none. Value at least 0. - `set_depends_on` (SetDependsOn): SetDependsOn replaces the components a component applies after. Empty clears it. A cycle is refused. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. - `depends_on` (array of string): Items at most 32. - `set_null` (SetNull): SetNull writes null at a path, which clears a chart default. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `path` (array of PathSegment): Items 1 to 32. - `key` (string, required): Length 1 to 256. - `set_pin` (SetPin): SetPin moves a component to another revision of the same registry component. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `reference` (string, required): A tag or a `sha256:` digest. Pattern `^(sha256:[0-9a-f]{64}|[A-Za-z0-9][A-Za-z0-9._+-]{0,127})$`. Length 1 to 128. - `set_placement` (SetPlacement): SetPlacement replaces where a component goes. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `placement` (Placement, required): Placement is where a component's objects go, per kind of target. A component carries at most the block for its kind. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `set_value` (SetValue): SetValue writes a value at a path, creating maps on the way, as `helm --set` does. A map value replaces what was there. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `path` (array of PathSegment): Items 1 to 32. - `key` (string, required): Length 1 to 256. - `value_json` (string, required): JSON text, not null: null is SetNull. Length 1 to 1048576. - `unset_value` (UnsetValue): UnsetValue removes a path, so the default applies. - `component` (string, required): Pattern `^[a-z]([a-z0-9-]{0,51}[a-z0-9])?$`. Length 1 to 53. - `path` (array of PathSegment): Items 1 to 32. - `key` (string, required): Length 1 to 256. - `plan` (boolean): Ask for a plan of the revision this cuts, as PlanChangeSet does. ### Response 200 Success - `change_set` (ChangeSet) - `id` (string): `cs-` and twelve lowercase base36 characters. Read-only. - `application_id` (string): Read-only. - `environment_id` (string): Read-only. - `title` (string): Read-only. - `description` (string): Read-only. - `status` (ChangeSetStatus): One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. Read-only. - `head_revision` (integer (int32)): 0 until the first edit. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reverts_change_set_id` (string): Set on a change set made by RevertChangeSet: the change set it reverts. It may apply while that change set's partial apply holds the environment. Read-only. - `revision` (Revision) - `number` (integer (int32)) - `change_set_id` (string) - `base_generation` (string (int64)): The environment's generation when the base was taken. - `cause` (RevisionCause): RevisionCause says why a revision was cut. Only EDIT is written until rebase exists. One of `REVISION_CAUSE_UNSPECIFIED`, `EDIT`, `REBASE`. - `violations` (array of Violation) - `component` (string) - `path` (string): Display form: `image.tag`, `ingress."a.b"`. - `message` (string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `entries` (array of Entry): Empty in a listing. - `component_id` (string) - `component` (string) - `action` (EntryAction): One of `ENTRY_ACTION_UNSPECIFIED`, `CREATE`, `UPDATE`, `DESTROY`. - `pin` (Pin): The revision the component is pinned to after this change set: set on CREATE and when the pin moves. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `base_digest` (string): Empty on CREATE. - `result_digest` (string): Empty on DESTROY. - `ops` (array of ValueOp) - `path` (array of PathSegment) - `key` (string, required): Length 1 to 256. - `op` (ValueOpKind): One of `VALUE_OP_KIND_UNSPECIFIED`, `SET`, `SET_NULL`, `REMOVE`. - `value_json` (string): JSON text; empty unless op is SET. - `from_present` (boolean): Whether the base had the key; a null there is present. - `from_value_json` (string): JSON text; empty when from_present is false. - `placement` (Placement): Where the component goes after this change set. Empty on DESTROY. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `depends_on` (array of string): Components this one applies after, after this change set. - `warnings` (array of string) - `prepare` (Prepare): Set when `plan` was asked for. - `revision` (integer (int32)) - `status` (PrepareStatus): PrepareStatus is where a revision's prepare stands. One of `PREPARE_STATUS_UNSPECIFIED`, `QUEUED`, `RUNNING`, `PREPARED`, `FAILED`, `SUPERSEDED`. - `artifact_digest` (string): `sha256:` of the run artifact; set once PREPARED. - `findings` (array of Finding) - `component` (string) - `code` (FindingCode): FindingCode names something a prepare noticed but did not refuse. One of `FINDING_CODE_UNSPECIFIED`, `LOOKUP_USED`, `NONDETERMINISTIC`, `NO_CAPABILITIES`, `SCOPE_GUESSED`. - `message` (string) - `details` (array of string): For NONDETERMINISTIC, each `Kind/namespace/name field` that differs. - `error` (PrepareError): Set when FAILED. - `class` (PrepareErrorClass): PrepareErrorClass says whether asking again can help. One of `PREPARE_ERROR_CLASS_UNSPECIFIED`, `RENDER`, `INFRA`. - `component` (string): Empty when the failure is not one component's. - `message` (string) - `requested_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `requested_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `requested_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `attempts` (integer (int32)) --- title: "Plan a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_PlanChangeSet" --- # Plan a change set `POST https://api.admiral.io/v1/changesets/{change_set_id}/plan` FAILED_PRECONDITION when the change set is not a draft, has no revision, or `if_revision` is not the head (the message names the head). Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Request body - `if_revision` (integer (int32)): When set, refused unless the head is this revision. Value at least 1. ### Response 200 Success - `prepare` (Prepare): Prepare is a revision's render into its run artifact. - `revision` (integer (int32)) - `status` (PrepareStatus): PrepareStatus is where a revision's prepare stands. One of `PREPARE_STATUS_UNSPECIFIED`, `QUEUED`, `RUNNING`, `PREPARED`, `FAILED`, `SUPERSEDED`. - `artifact_digest` (string): `sha256:` of the run artifact; set once PREPARED. - `findings` (array of Finding) - `component` (string) - `code` (FindingCode): FindingCode names something a prepare noticed but did not refuse. One of `FINDING_CODE_UNSPECIFIED`, `LOOKUP_USED`, `NONDETERMINISTIC`, `NO_CAPABILITIES`, `SCOPE_GUESSED`. - `message` (string) - `details` (array of string): For NONDETERMINISTIC, each `Kind/namespace/name field` that differs. - `error` (PrepareError): Set when FAILED. - `class` (PrepareErrorClass): PrepareErrorClass says whether asking again can help. One of `PREPARE_ERROR_CLASS_UNSPECIFIED`, `RENDER`, `INFRA`. - `component` (string): Empty when the failure is not one component's. - `message` (string) - `requested_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `requested_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `requested_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `attempts` (integer (int32)) --- title: "Revert a change set" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_RevertChangeSet" --- # Revert a change set `POST https://api.admiral.io/v1/changesets/{change_set_id}/revert` Scope: `changeset:write` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Request body - `title` (string): Length at most 256. ### Response 200 Success - `change_set` (ChangeSet) - `id` (string): `cs-` and twelve lowercase base36 characters. Read-only. - `application_id` (string): Read-only. - `environment_id` (string): Read-only. - `title` (string): Read-only. - `description` (string): Read-only. - `status` (ChangeSetStatus): One of `CHANGE_SET_STATUS_UNSPECIFIED`, `DRAFT`, `DISCARDED`, `APPLYING`, `APPLIED`, `PARTIALLY_APPLIED`. Read-only. - `head_revision` (integer (int32)): 0 until the first edit. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reverts_change_set_id` (string): Set on a change set made by RevertChangeSet: the change set it reverts. It may apply while that change set's partial apply holds the environment. Read-only. --- title: "List a change set's revisions" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_ListRevisions" --- # List a change set's revisions `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. ### Query parameters - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. ### Response 200 Success - `revisions` (array of Revision) - `number` (integer (int32)) - `change_set_id` (string) - `base_generation` (string (int64)): The environment's generation when the base was taken. - `cause` (RevisionCause): RevisionCause says why a revision was cut. Only EDIT is written until rebase exists. One of `REVISION_CAUSE_UNSPECIFIED`, `EDIT`, `REBASE`. - `violations` (array of Violation) - `component` (string) - `path` (string): Display form: `image.tag`, `ingress."a.b"`. - `message` (string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `entries` (array of Entry): Empty in a listing. - `component_id` (string) - `component` (string) - `action` (EntryAction): One of `ENTRY_ACTION_UNSPECIFIED`, `CREATE`, `UPDATE`, `DESTROY`. - `pin` (Pin): The revision the component is pinned to after this change set: set on CREATE and when the pin moves. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `base_digest` (string): Empty on CREATE. - `result_digest` (string): Empty on DESTROY. - `ops` (array of ValueOp) - `path` (array of PathSegment) - `key` (string, required): Length 1 to 256. - `op` (ValueOpKind): One of `VALUE_OP_KIND_UNSPECIFIED`, `SET`, `SET_NULL`, `REMOVE`. - `value_json` (string): JSON text; empty unless op is SET. - `from_present` (boolean): Whether the base had the key; a null there is present. - `from_value_json` (string): JSON text; empty when from_present is false. - `placement` (Placement): Where the component goes after this change set. Empty on DESTROY. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `depends_on` (array of string): Components this one applies after, after this change set. - `next_page_token` (string) --- title: "Retrieve a change set revision" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetRevision" --- # Retrieve a change set revision `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions/{number}` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `number` (integer (int32), required): The number path parameter. Value at least 1. ### Response 200 Success - `revision` (Revision) - `number` (integer (int32)) - `change_set_id` (string) - `base_generation` (string (int64)): The environment's generation when the base was taken. - `cause` (RevisionCause): RevisionCause says why a revision was cut. Only EDIT is written until rebase exists. One of `REVISION_CAUSE_UNSPECIFIED`, `EDIT`, `REBASE`. - `violations` (array of Violation) - `component` (string) - `path` (string): Display form: `image.tag`, `ingress."a.b"`. - `message` (string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `entries` (array of Entry): Empty in a listing. - `component_id` (string) - `component` (string) - `action` (EntryAction): One of `ENTRY_ACTION_UNSPECIFIED`, `CREATE`, `UPDATE`, `DESTROY`. - `pin` (Pin): The revision the component is pinned to after this change set: set on CREATE and when the pin moves. - `revision_id` (string) - `digest` (string): `sha256:` of the bundle. - `namespace` (string) - `name` (string) - `base_digest` (string): Empty on CREATE. - `result_digest` (string): Empty on DESTROY. - `ops` (array of ValueOp) - `path` (array of PathSegment) - `key` (string, required): Length 1 to 256. - `op` (ValueOpKind): One of `VALUE_OP_KIND_UNSPECIFIED`, `SET`, `SET_NULL`, `REMOVE`. - `value_json` (string): JSON text; empty unless op is SET. - `from_present` (boolean): Whether the base had the key; a null there is present. - `from_value_json` (string): JSON text; empty when from_present is false. - `placement` (Placement): Where the component goes after this change set. Empty on DESTROY. - `kubernetes` (KubernetesPlacement): KubernetesPlacement is a workload component's namespace. - `namespace` (string): Empty means the environment's default namespace. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `extra_namespaces` (array of string): Namespaces the component may also write to, such as `kube-system` for a chart's leader-election Role. The plan refuses an object in any other. Items at most 16. - `depends_on` (array of string): Components this one applies after, after this change set. --- title: "Retrieve a revision's apply" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetApply" --- # Retrieve a revision's apply `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions/{revision}/apply` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `revision` (integer (int32), required): The revision path parameter. Value at least 1. ### Response 200 Success - `apply` (Apply): Apply is a revision's apply: its APPLY job and what happened to each component, in apply order. - `revision` (integer (int32)) - `job_id` (string) - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `plan_digest` (string) - `components` (array of ComponentApply) - `component` (string) - `status` (JobStatus): QUEUED until reached, then SUCCEEDED or FAILED. One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `message` (string) - `applied_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `accepted_by` (ActorRef): Set when a partial apply was accepted as the environment's new state. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `accepted_reason` (string) - `accepted_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Retrieve a revision's rendered artifact" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetArtifact" --- # Retrieve a revision's rendered artifact `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions/{revision}/artifact` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `revision` (integer (int32), required): The revision path parameter. Value at least 1. ### Response 200 Success - `artifact_digest` (string): `sha256:` of the artifact as stored, before masking. - `artifact` (string (byte)): The run artifact, a gzipped tar, with Secret values masked. --- title: "Retrieve a revision's plan" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetPlan" --- # Retrieve a revision's plan `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions/{revision}/plan` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `revision` (integer (int32), required): The revision path parameter. Value at least 1. ### Response 200 Success - `plan` (Plan): Plan is a prepared revision planned against its environment's cluster. - `revision` (integer (int32)) - `job_id` (string) - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `agent_id` (string): What the plan runs against. - `agent_name` (string) - `cluster_id` (string) - `cluster_name` (string) - `plan_digest` (string): `sha256:` of the changes: identical plans have identical digests. - `components` (array of ComponentPlan) - `component` (string): Length at most 63. - `changes` (array of ResourceChange): Items at most 5000. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `action` (ResourceAction): enum.defined_only = true One of `NO_OP`, `CREATE`, `UPDATE`, `REPLACE`, `DESTROY`, `ORPHAN`. - `diff_digest` (string): `sha256:` of this resource's diff in the PlanDiff. Empty for NO_OP. Length at most 71. - `message` (string): Why the plan failed, when it did. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `approvals` (array of Approval): Approvals of this plan. A different plan dismisses them. - `revision` (integer (int32)) - `plan_digest` (string) - `approved_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `self_approval` (boolean): The approver revised the change set and was the only one able to approve. - `reason` (string) - `approved_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Retrieve a plan's diffs" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetPlanDiff" --- # Retrieve a plan's diffs `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions/{revision}/plan/diff` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `revision` (integer (int32), required): The revision path parameter. Value at least 1. ### Response 200 Success - `diff` (PlanDiff): PlanDiff is a plan's full diffs, stored apart from the job. - `resources` (array of ResourceDiff): Items at most 5000. - `component` (string): Length at most 63. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `diff` (string): Unified diff from the live object to the desired one, both normalized. A Secret's data shows each key as added, changed or removed, never a value. Length at most 1048576. --- title: "Retrieve a revision's prepare" canonical: "https://admiral.io/docs/api/changesets/ChangeSetAPI_GetPrepare" --- # Retrieve a revision's prepare `GET https://api.admiral.io/v1/changesets/{change_set_id}/revisions/{revision}/prepare` Scope: `changeset:read` ### Path parameters - `change_set_id` (string, required): The change_set_id path parameter. Pattern `^cs-[0-9a-z]{12}$`. - `revision` (integer (int32), required): The revision path parameter. Value at least 1. ### Response 200 Success - `prepare` (Prepare): Prepare is a revision's render into its run artifact. - `revision` (integer (int32)) - `status` (PrepareStatus): PrepareStatus is where a revision's prepare stands. One of `PREPARE_STATUS_UNSPECIFIED`, `QUEUED`, `RUNNING`, `PREPARED`, `FAILED`, `SUPERSEDED`. - `artifact_digest` (string): `sha256:` of the run artifact; set once PREPARED. - `findings` (array of Finding) - `component` (string) - `code` (FindingCode): FindingCode names something a prepare noticed but did not refuse. One of `FINDING_CODE_UNSPECIFIED`, `LOOKUP_USED`, `NONDETERMINISTIC`, `NO_CAPABILITIES`, `SCOPE_GUESSED`. - `message` (string) - `details` (array of string): For NONDETERMINISTIC, each `Kind/namespace/name field` that differs. - `error` (PrepareError): Set when FAILED. - `class` (PrepareErrorClass): PrepareErrorClass says whether asking again can help. One of `PREPARE_ERROR_CLASS_UNSPECIFIED`, `RENDER`, `INFRA`. - `component` (string): Empty when the failure is not one component's. - `message` (string) - `requested_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `requested_by_kind` (ActorKind): ActorKind is what cut a revision: a person, a machine's key, or Admiral itself. One of `ACTOR_KIND_UNSPECIFIED`, `USER`, `SERVICE_ACCOUNT`, `SYSTEM`. - `requested_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `attempts` (integer (int32)) --- title: "List clusters" canonical: "https://admiral.io/docs/api/clusters/AgentAPI_ListClusters" --- # List clusters `GET https://api.admiral.io/v1/clusters` Scope: `agent:read` ### Query parameters - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. ### Response 200 Success - `clusters` (array of Cluster) - `id` (string): Read-only. - `name` (string) - `status` (ClusterStatus): One of `CLUSTER_STATUS_UNSPECIFIED`, `PENDING`, `TRUSTED`. Read-only. - `issuer_url` (string): Set when the cluster's issuer is public; keys are fetched from it. Read-only. - `key_ids` (array of string): Read-only. - `keys_updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reported_key_ids` (array of string): Key ids an agent reported that are not trusted. An agent's report is never applied; an admin reviews it and accepts with SetClusterTrust. Read-only. - `keys_reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `next_page_token` (string) --- title: "Connect a cluster" canonical: "https://admiral.io/docs/api/clusters/AgentAPI_CreateCluster" --- # Connect a cluster `POST https://api.admiral.io/v1/clusters` Scope: `agent:write` ### Request body - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `trust` (ClusterTrust): Absent leaves the cluster PENDING for an agent to enroll. - At most one of `accept_reported`, `issuer_url`, `jwks_json` is set. - `accept_reported` (boolean): Trust the key set an agent last reported. Only on SetClusterTrust. Must be `true`. - `issuer_url` (string (uri)): An https URL whose /.well-known/openid-configuration names the keys. string.prefix = "https://" Length at most 2048. - `jwks_json` (string): A JSON Web Key Set, as the cluster serves it at /openid/v1/jwks. Length 2 to 65536. ### Response 200 Success - `cluster` (Cluster) - `id` (string): Read-only. - `name` (string) - `status` (ClusterStatus): One of `CLUSTER_STATUS_UNSPECIFIED`, `PENDING`, `TRUSTED`. Read-only. - `issuer_url` (string): Set when the cluster's issuer is public; keys are fetched from it. Read-only. - `key_ids` (array of string): Read-only. - `keys_updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reported_key_ids` (array of string): Key ids an agent reported that are not trusted. An agent's report is never applied; an admin reviews it and accepts with SetClusterTrust. Read-only. - `keys_reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Retrieve a cluster" canonical: "https://admiral.io/docs/api/clusters/AgentAPI_GetCluster" --- # Retrieve a cluster `GET https://api.admiral.io/v1/clusters/{cluster_id}` Scope: `agent:read` ### Path parameters - `cluster_id` (string (uuid), required): The cluster_id path parameter. ### Response 200 Success - `cluster` (Cluster) - `id` (string): Read-only. - `name` (string) - `status` (ClusterStatus): One of `CLUSTER_STATUS_UNSPECIFIED`, `PENDING`, `TRUSTED`. Read-only. - `issuer_url` (string): Set when the cluster's issuer is public; keys are fetched from it. Read-only. - `key_ids` (array of string): Read-only. - `keys_updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reported_key_ids` (array of string): Key ids an agent reported that are not trusted. An agent's report is never applied; an admin reviews it and accepts with SetClusterTrust. Read-only. - `keys_reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Delete a cluster" canonical: "https://admiral.io/docs/api/clusters/AgentAPI_DeleteCluster" --- # Delete a cluster `DELETE https://api.admiral.io/v1/clusters/{cluster_id}` Scope: `agent:write` ### Path parameters - `cluster_id` (string (uuid), required): The cluster_id path parameter. ### Response 200 Success Type: DeleteClusterResponse. --- title: "Set how a cluster is trusted" canonical: "https://admiral.io/docs/api/clusters/AgentAPI_SetClusterTrust" --- # Set how a cluster is trusted `POST https://api.admiral.io/v1/clusters/{cluster_id}/trust` Scope: `agent:write` ### Path parameters - `cluster_id` (string (uuid), required): The cluster_id path parameter. ### Request body - `trust` (ClusterTrust, required): ClusterTrust is how a cluster's tokens are verified. - At most one of `accept_reported`, `issuer_url`, `jwks_json` is set. - `accept_reported` (boolean): Trust the key set an agent last reported. Only on SetClusterTrust. Must be `true`. - `issuer_url` (string (uri)): An https URL whose /.well-known/openid-configuration names the keys. string.prefix = "https://" Length at most 2048. - `jwks_json` (string): A JSON Web Key Set, as the cluster serves it at /openid/v1/jwks. Length 2 to 65536. ### Response 200 Success - `cluster` (Cluster) - `id` (string): Read-only. - `name` (string) - `status` (ClusterStatus): One of `CLUSTER_STATUS_UNSPECIFIED`, `PENDING`, `TRUSTED`. Read-only. - `issuer_url` (string): Set when the cluster's issuer is public; keys are fetched from it. Read-only. - `key_ids` (array of string): Read-only. - `keys_updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `reported_key_ids` (array of string): Key ids an agent reported that are not trusted. An agent's report is never applied; an admin reviews it and accepts with SetClusterTrust. Read-only. - `keys_reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "List components" canonical: "https://admiral.io/docs/api/components/RegistryAPI_ListComponents" --- # List components `GET https://api.admiral.io/v1/components` Scope: `component:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `name`: filter by name. - `description`: filter by description. - `labels`: filter by label key/value. Example: `field['labels']['team'] = 'payments'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of components to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `components` (array of Component): Listed without their tags; GetComponent carries those. - `id` (string): Unique identifier (UUID). Read-only. - `name` (string): The name as it is written: `cloud-sql`, or `payments/cloud-sql` once team namespaces exist. Unique within the tenant. Immutable. Read-only. - `description` (string): Length at most 1024. - `labels` (map of string to string): Key-value metadata for filtering (e.g. `{"team": "payments", "runtime": "terraform"}`), the same labels every Admiral resource carries. - `tags` (array of Tag): Every tag on the component, by name. Read-only. - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only. - `digest` (string): The revision it names, as `sha256:`. Read-only. - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Publish a component revision" canonical: "https://admiral.io/docs/api/components/RegistryAPI_PublishComponent" --- # Publish a component revision `POST https://api.admiral.io/v1/components/publish` The bundle is a gzipped tar of the component root, carried inline and capped at 64 MiB; a fully vendored tree that exceeds it will get a resumable upload path of its own. The server normalizes the bytes (strips `.git`, canonicalizes entry order and timestamps), digests them, runs the publish gate, stores the blob and answers with the revision. If the digest already exists under the name, the existing revision is returned with `unchanged` set and nothing is written, which is what makes a publish-everything CI recipe safe. Any tags named in the request are set on the resulting revision. Repointing a semver tag is refused with FAILED_PRECONDITION and the whole publish fails; the bytes are not kept. Scope: `component:publish` ### Request body - `name` (string, required): The component name to publish under. Created on first use. Bare (`cloud-sql`), which resolves to the default namespace. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `kind` (ComponentKind): The kind, when the caller knows better than inspection. UNSPECIFIED means detect. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. - `tags` (array of string): Tags to set on the resulting revision (e.g. `v1.2.0`, `latest`). Items at most 16. - `description` (string): Description and labels for the component. Applied when the publish creates the component; ignored when it already exists, since a publish is not the place to edit metadata. UpdateComponent is. Length at most 1024. - `labels` (map of string to string) - `provenance` (Provenance): What the caller knows about where the bytes came from. The server records the kind as LOCAL for a CLI upload whatever is claimed here; the uri, ref, commit, path and dirty flag are kept as the caller's assertion. - `kind` (ProvenanceKind): ProvenanceKind is how the bytes arrived. One of `PROVENANCE_KIND_UNSPECIFIED`, `LOCAL`, `GIT`, `PULL`. - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. Empty for a local publish with no remote. - `ref` (string): The ref that was asked for (tag, branch, chart version), when any. - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version. - `path` (string): The path within the source the bundle was taken from. Empty means the root. - `dirty` (boolean): The working copy carried uncommitted changes when it was published. Only meaningful for LOCAL, and only ever true when the CLI said so. - `pins` (array of Pin): Every remote module or chart the closure step vendored into the bundle, pinned to what it resolved. - `source` (string): The source as the bundle declared it, before rewriting. - `constraint` (string): The constraint that was asked for, when any. - `resolved` (string): What it resolved to: an exact version or commit. - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only. - `id` (string) - `name` (string) - `hosts` (array of string): The hosts it was presented to during this pull. - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this revision can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096. - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256. - `bundle` (string (byte), required): The bundle: a gzipped tar of the component root. At most 64 MiB. Length 1 to 67108864. ### Response 200 Success - `component` (Component): Component is a registry entry: a name, and the revisions and tags beneath it. - `id` (string): Unique identifier (UUID). Read-only. - `name` (string): The name as it is written: `cloud-sql`, or `payments/cloud-sql` once team namespaces exist. Unique within the tenant. Immutable. Read-only. - `description` (string): Length at most 1024. - `labels` (map of string to string): Key-value metadata for filtering (e.g. `{"team": "payments", "runtime": "terraform"}`), the same labels every Admiral resource carries. - `tags` (array of Tag): Every tag on the component, by name. Read-only. - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only. - `digest` (string): The revision it names, as `sha256:`. Read-only. - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `revision` (Revision): Revision is one published artifact. Immutable except for its status. - `id` (string): Unique identifier (UUID). Internal handle; references use the digest. Read-only. - `component_id` (string): The component this revision belongs to (UUID). Read-only. - `digest` (string): The identity: SHA-256 of the normalized bundle, as `sha256:`. Read-only. - `kind` (ComponentKind): ComponentKind is what a revision's bundle is, detected by inspection at publish: a Chart.yaml means HELM, .tf files mean TERRAFORM, anything else that is Kubernetes YAML means MANIFESTS. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. Read-only. - `size_bytes` (string (int64)): Size of the stored bundle in bytes. Read-only. - `contract` (Contract): The inputs and outputs the bundle exposes. Inferred from the bundle at publish; curated by a publisher once the contract format lands. Read-only. - `inputs` (array of ContractInput) - `name` (string) - `type` (string): The type as the bundle declares it: a Terraform type expression, or for a chart one of bool, number, string, list, object or null. A chart's full constraint is in schema. - `description` (string) - `required` (boolean): True when the bundle gives it no default. - `default` (Value): The declared default, when there is one. - `sensitive` (boolean): The value is a secret: never rendered in review, and resolved by the runner from a reference rather than stored in the change set. - `ephemeral` (boolean): The value must not land in plan or state (Terraform 1.10+ ephemeral inputs). Implies sensitive. - `nullable` (boolean): Whether null is an accepted value. Unset when the bundle does not say, which is a chart input with no schema. - `deprecated` (string): The bundle's own deprecation message for this input. - `validations` (array of ContractValidation): A Terraform variable's validation blocks, in declaration order. - `condition` (string) - `error_message` (string) - `schema` (map of string to Value): The JSON Schema a chart's values.schema.json declares for this input, verbatim, so a value can be checked the way Helm will check it. - `outputs` (array of ContractOutput) - `name` (string) - `description` (string) - `sensitive` (boolean) - `provenance` (Provenance): Where the bytes came from. Read-only. - `kind` (ProvenanceKind): ProvenanceKind is how the bytes arrived. One of `PROVENANCE_KIND_UNSPECIFIED`, `LOCAL`, `GIT`, `PULL`. - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. Empty for a local publish with no remote. - `ref` (string): The ref that was asked for (tag, branch, chart version), when any. - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version. - `path` (string): The path within the source the bundle was taken from. Empty means the root. - `dirty` (boolean): The working copy carried uncommitted changes when it was published. Only meaningful for LOCAL, and only ever true when the CLI said so. - `pins` (array of Pin): Every remote module or chart the closure step vendored into the bundle, pinned to what it resolved. - `source` (string): The source as the bundle declared it, before rewriting. - `constraint` (string): The constraint that was asked for, when any. - `resolved` (string): What it resolved to: an exact version or commit. - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only. - `id` (string) - `name` (string) - `hosts` (array of string): The hosts it was presented to during this pull. - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this revision can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096. - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256. - `findings` (array of Finding): What the publish gate found. Informational findings do not block a publish; a revision with findings is published with them attached, and the findings delta between two revisions is what an upgrade review reads. Read-only. - `severity` (FindingSeverity): FindingSeverity ranks what the publish gate found. One of `FINDING_SEVERITY_UNSPECIFIED`, `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. - `source` (string): What produced it: `provider-constraint`, `checkov`, `trivy`, `image-ref`. - `code` (string): The producer's own identifier for the rule, when it has one (e.g. `CKV_AWS_18`). - `message` (string) - `path` (string): Where in the bundle, when it applies. - `status` (RevisionStatus): RevisionStatus is a revision's lifecycle. There is no deleted state. One of `REVISION_STATUS_UNSPECIFIED`, `PUBLISHED`, `DEPRECATED`, `REVOKED`. Read-only. - `status_changed_at` (Timestamp): When and why the status last changed. Unset on a revision that has only ever been PUBLISHED. Read-only. - `status_reason` (string): Read-only. - `tags` (array of string): The tags currently naming this revision. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `unchanged` (boolean): True when the digest was already published under this name and nothing was written. Tags in the request were still applied. --- title: "Pull and publish an artifact from a registry, repository or URL" canonical: "https://admiral.io/docs/api/components/RegistryAPI_PullComponent" --- # Pull and publish an artifact from a registry, repository or URL `POST https://api.admiral.io/v1/components/pull` Scope: `component:publish` ### Request body - `name` (string): Empty means the artifact's own name: the chart's, the module's, the repository's or directory's. Bare, which resolves to the default namespace. Pattern `^([a-z]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `source` (PullSource, required): PullSource names an artifact to pull. One variant. The kind of the resulting component follows from it: a chart from OCI or a Helm repository, a module from a module registry, whatever inspection finds in a git tree or an archive. - At most one of `archive`, `git_tree`, `helm_chart`, `oci_chart`, `registry_module` is set. - `archive` (Archive): An archive at a URL, unpacked by its extension. - `url` (string (uri), required): Length at most 512. - `git_tree` (GitTree): A git repository at a ref, optionally a directory of it. - `url` (string (uri), required): `https://github.com/acme/infra.git`, `ssh://git@github.com/acme/infra.git`. Length at most 512. - `ref` (string): A branch, tag or commit. Empty is the default branch. Length at most 256. - `path` (string): A directory within the repository. Empty is the root. string.not_contains = ".." Length at most 512. - `helm_chart` (HelmChart): A chart in an HTTP repository: the repository URL, the chart's name in its index, and an exact version. - `repository` (string (uri), required): Length at most 512. - `chart` (string, required): Pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$`. Length at most 63. - `version` (string, required): Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`. - `oci_chart` (OCIChart): A chart in an OCI registry: `oci://ghcr.io/argoproj/argo-helm/argo-cd` at a version, which is its tag. - `reference` (string, required): string.prefix = "oci://" Length 7 to 512. - `version` (string, required): Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`. - `registry_module` (RegistryModule): A module in a module registry: the address as a module call would write it (`GoogleCloudPlatform/cloud-armor/google`, optionally host-qualified, optionally `//subdir`) and a version constraint, which resolves to the newest version satisfying it at pull time, or exactly one version. - `address` (string, required): Length 5 to 512. - `version` (string): Length at most 128. - `credential_ids` (array of string (uuid)): The credentials this pull may present, chosen by the caller. Each is presented only where its type fits and its `allowed_hosts` permit. A fetch that reaches a host none of them covers fails naming the host. Items at most 16. - `tags` (array of string): Tags to set on the resulting revision. A chart's version and a module's resolved version are applied as tags whether or not named. Items at most 16. - `description` (string): Applied when the pull creates the component; ignored otherwise. Length at most 1024. - `labels` (map of string to string) ### Response 200 Success - `component` (Component): Component is a registry entry: a name, and the revisions and tags beneath it. - `id` (string): Unique identifier (UUID). Read-only. - `name` (string): The name as it is written: `cloud-sql`, or `payments/cloud-sql` once team namespaces exist. Unique within the tenant. Immutable. Read-only. - `description` (string): Length at most 1024. - `labels` (map of string to string): Key-value metadata for filtering (e.g. `{"team": "payments", "runtime": "terraform"}`), the same labels every Admiral resource carries. - `tags` (array of Tag): Every tag on the component, by name. Read-only. - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only. - `digest` (string): The revision it names, as `sha256:`. Read-only. - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `revision` (Revision): Revision is one published artifact. Immutable except for its status. - `id` (string): Unique identifier (UUID). Internal handle; references use the digest. Read-only. - `component_id` (string): The component this revision belongs to (UUID). Read-only. - `digest` (string): The identity: SHA-256 of the normalized bundle, as `sha256:`. Read-only. - `kind` (ComponentKind): ComponentKind is what a revision's bundle is, detected by inspection at publish: a Chart.yaml means HELM, .tf files mean TERRAFORM, anything else that is Kubernetes YAML means MANIFESTS. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. Read-only. - `size_bytes` (string (int64)): Size of the stored bundle in bytes. Read-only. - `contract` (Contract): The inputs and outputs the bundle exposes. Inferred from the bundle at publish; curated by a publisher once the contract format lands. Read-only. - `inputs` (array of ContractInput) - `name` (string) - `type` (string): The type as the bundle declares it: a Terraform type expression, or for a chart one of bool, number, string, list, object or null. A chart's full constraint is in schema. - `description` (string) - `required` (boolean): True when the bundle gives it no default. - `default` (Value): The declared default, when there is one. - `sensitive` (boolean): The value is a secret: never rendered in review, and resolved by the runner from a reference rather than stored in the change set. - `ephemeral` (boolean): The value must not land in plan or state (Terraform 1.10+ ephemeral inputs). Implies sensitive. - `nullable` (boolean): Whether null is an accepted value. Unset when the bundle does not say, which is a chart input with no schema. - `deprecated` (string): The bundle's own deprecation message for this input. - `validations` (array of ContractValidation): A Terraform variable's validation blocks, in declaration order. - `condition` (string) - `error_message` (string) - `schema` (map of string to Value): The JSON Schema a chart's values.schema.json declares for this input, verbatim, so a value can be checked the way Helm will check it. - `outputs` (array of ContractOutput) - `name` (string) - `description` (string) - `sensitive` (boolean) - `provenance` (Provenance): Where the bytes came from. Read-only. - `kind` (ProvenanceKind): ProvenanceKind is how the bytes arrived. One of `PROVENANCE_KIND_UNSPECIFIED`, `LOCAL`, `GIT`, `PULL`. - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. Empty for a local publish with no remote. - `ref` (string): The ref that was asked for (tag, branch, chart version), when any. - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version. - `path` (string): The path within the source the bundle was taken from. Empty means the root. - `dirty` (boolean): The working copy carried uncommitted changes when it was published. Only meaningful for LOCAL, and only ever true when the CLI said so. - `pins` (array of Pin): Every remote module or chart the closure step vendored into the bundle, pinned to what it resolved. - `source` (string): The source as the bundle declared it, before rewriting. - `constraint` (string): The constraint that was asked for, when any. - `resolved` (string): What it resolved to: an exact version or commit. - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only. - `id` (string) - `name` (string) - `hosts` (array of string): The hosts it was presented to during this pull. - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this revision can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096. - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256. - `findings` (array of Finding): What the publish gate found. Informational findings do not block a publish; a revision with findings is published with them attached, and the findings delta between two revisions is what an upgrade review reads. Read-only. - `severity` (FindingSeverity): FindingSeverity ranks what the publish gate found. One of `FINDING_SEVERITY_UNSPECIFIED`, `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. - `source` (string): What produced it: `provider-constraint`, `checkov`, `trivy`, `image-ref`. - `code` (string): The producer's own identifier for the rule, when it has one (e.g. `CKV_AWS_18`). - `message` (string) - `path` (string): Where in the bundle, when it applies. - `status` (RevisionStatus): RevisionStatus is a revision's lifecycle. There is no deleted state. One of `REVISION_STATUS_UNSPECIFIED`, `PUBLISHED`, `DEPRECATED`, `REVOKED`. Read-only. - `status_changed_at` (Timestamp): When and why the status last changed. Unset on a revision that has only ever been PUBLISHED. Read-only. - `status_reason` (string): Read-only. - `tags` (array of string): The tags currently naming this revision. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `unchanged` (boolean): The resolution was already published under this name; nothing was written. --- title: "Update a component" canonical: "https://admiral.io/docs/api/components/RegistryAPI_UpdateComponent" --- # Update a component `PATCH https://api.admiral.io/v1/components/{component_id}` Scope: `component:write` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. ### Request body - `description` (string): Length at most 1024. - `labels` (ComponentLabels): Replaces the label set entirely when present. - `labels` (map of string to string) ### Response 200 Success - `component` (Component): Component is a registry entry: a name, and the revisions and tags beneath it. - `id` (string): Unique identifier (UUID). Read-only. - `name` (string): The name as it is written: `cloud-sql`, or `payments/cloud-sql` once team namespaces exist. Unique within the tenant. Immutable. Read-only. - `description` (string): Length at most 1024. - `labels` (map of string to string): Key-value metadata for filtering (e.g. `{"team": "payments", "runtime": "terraform"}`), the same labels every Admiral resource carries. - `tags` (array of Tag): Every tag on the component, by name. Read-only. - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only. - `digest` (string): The revision it names, as `sha256:`. Read-only. - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Retire a component" canonical: "https://admiral.io/docs/api/components/RegistryAPI_DeleteComponent" --- # Retire a component `DELETE https://api.admiral.io/v1/components/{component_id}` Scope: `component:write` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. ### Response 200 Success Type: DeleteComponentResponse. --- title: "List a component's revisions" canonical: "https://admiral.io/docs/api/components/RegistryAPI_ListRevisions" --- # List a component's revisions `GET https://api.admiral.io/v1/components/{component_id}/revisions` Scope: `component:read` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. ### Query parameters - `filter` (string): Filter expression. Filterable fields: - `kind`: TERRAFORM, HELM, MANIFESTS. - `status`: PUBLISHED, DEPRECATED, REVOKED. Example: `field['status'] = 'PUBLISHED'` Length at most 1024. - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. ### Response 200 Success - `revisions` (array of Revision) - `id` (string): Unique identifier (UUID). Internal handle; references use the digest. Read-only. - `component_id` (string): The component this revision belongs to (UUID). Read-only. - `digest` (string): The identity: SHA-256 of the normalized bundle, as `sha256:`. Read-only. - `kind` (ComponentKind): ComponentKind is what a revision's bundle is, detected by inspection at publish: a Chart.yaml means HELM, .tf files mean TERRAFORM, anything else that is Kubernetes YAML means MANIFESTS. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. Read-only. - `size_bytes` (string (int64)): Size of the stored bundle in bytes. Read-only. - `contract` (Contract): The inputs and outputs the bundle exposes. Inferred from the bundle at publish; curated by a publisher once the contract format lands. Read-only. - `inputs` (array of ContractInput) - `name` (string) - `type` (string): The type as the bundle declares it: a Terraform type expression, or for a chart one of bool, number, string, list, object or null. A chart's full constraint is in schema. - `description` (string) - `required` (boolean): True when the bundle gives it no default. - `default` (Value): The declared default, when there is one. - `sensitive` (boolean): The value is a secret: never rendered in review, and resolved by the runner from a reference rather than stored in the change set. - `ephemeral` (boolean): The value must not land in plan or state (Terraform 1.10+ ephemeral inputs). Implies sensitive. - `nullable` (boolean): Whether null is an accepted value. Unset when the bundle does not say, which is a chart input with no schema. - `deprecated` (string): The bundle's own deprecation message for this input. - `validations` (array of ContractValidation): A Terraform variable's validation blocks, in declaration order. - `condition` (string) - `error_message` (string) - `schema` (map of string to Value): The JSON Schema a chart's values.schema.json declares for this input, verbatim, so a value can be checked the way Helm will check it. - `outputs` (array of ContractOutput) - `name` (string) - `description` (string) - `sensitive` (boolean) - `provenance` (Provenance): Where the bytes came from. Read-only. - `kind` (ProvenanceKind): ProvenanceKind is how the bytes arrived. One of `PROVENANCE_KIND_UNSPECIFIED`, `LOCAL`, `GIT`, `PULL`. - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. Empty for a local publish with no remote. - `ref` (string): The ref that was asked for (tag, branch, chart version), when any. - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version. - `path` (string): The path within the source the bundle was taken from. Empty means the root. - `dirty` (boolean): The working copy carried uncommitted changes when it was published. Only meaningful for LOCAL, and only ever true when the CLI said so. - `pins` (array of Pin): Every remote module or chart the closure step vendored into the bundle, pinned to what it resolved. - `source` (string): The source as the bundle declared it, before rewriting. - `constraint` (string): The constraint that was asked for, when any. - `resolved` (string): What it resolved to: an exact version or commit. - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only. - `id` (string) - `name` (string) - `hosts` (array of string): The hosts it was presented to during this pull. - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this revision can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096. - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256. - `findings` (array of Finding): What the publish gate found. Informational findings do not block a publish; a revision with findings is published with them attached, and the findings delta between two revisions is what an upgrade review reads. Read-only. - `severity` (FindingSeverity): FindingSeverity ranks what the publish gate found. One of `FINDING_SEVERITY_UNSPECIFIED`, `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. - `source` (string): What produced it: `provider-constraint`, `checkov`, `trivy`, `image-ref`. - `code` (string): The producer's own identifier for the rule, when it has one (e.g. `CKV_AWS_18`). - `message` (string) - `path` (string): Where in the bundle, when it applies. - `status` (RevisionStatus): RevisionStatus is a revision's lifecycle. There is no deleted state. One of `REVISION_STATUS_UNSPECIFIED`, `PUBLISHED`, `DEPRECATED`, `REVOKED`. Read-only. - `status_changed_at` (Timestamp): When and why the status last changed. Unset on a revision that has only ever been PUBLISHED. Read-only. - `status_reason` (string): Read-only. - `tags` (array of string): The tags currently naming this revision. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `next_page_token` (string) --- title: "Set a revision's status" canonical: "https://admiral.io/docs/api/components/RegistryAPI_SetRevisionStatus" --- # Set a revision's status `POST https://api.admiral.io/v1/components/{component_id}/revisions/{digest}/set-status` Scope: `component:write` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. - `digest` (string, required): `sha256:`. A digest, not a tag: the status belongs to the bytes, and a floating tag might name different bytes by the time anyone reads the reason. Pattern `^sha256:[0-9a-f]{64}$`. ### Request body - `status` (RevisionStatus, required): enum.defined_only = true One of `PUBLISHED`, `DEPRECATED`, `REVOKED`. - `reason` (string, required): Shown to anyone who adopts or tries to adopt the revision, and to every environment running it. Length 1 to 1024. ### Response 200 Success - `revision` (Revision): Revision is one published artifact. Immutable except for its status. - `id` (string): Unique identifier (UUID). Internal handle; references use the digest. Read-only. - `component_id` (string): The component this revision belongs to (UUID). Read-only. - `digest` (string): The identity: SHA-256 of the normalized bundle, as `sha256:`. Read-only. - `kind` (ComponentKind): ComponentKind is what a revision's bundle is, detected by inspection at publish: a Chart.yaml means HELM, .tf files mean TERRAFORM, anything else that is Kubernetes YAML means MANIFESTS. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. Read-only. - `size_bytes` (string (int64)): Size of the stored bundle in bytes. Read-only. - `contract` (Contract): The inputs and outputs the bundle exposes. Inferred from the bundle at publish; curated by a publisher once the contract format lands. Read-only. - `inputs` (array of ContractInput) - `name` (string) - `type` (string): The type as the bundle declares it: a Terraform type expression, or for a chart one of bool, number, string, list, object or null. A chart's full constraint is in schema. - `description` (string) - `required` (boolean): True when the bundle gives it no default. - `default` (Value): The declared default, when there is one. - `sensitive` (boolean): The value is a secret: never rendered in review, and resolved by the runner from a reference rather than stored in the change set. - `ephemeral` (boolean): The value must not land in plan or state (Terraform 1.10+ ephemeral inputs). Implies sensitive. - `nullable` (boolean): Whether null is an accepted value. Unset when the bundle does not say, which is a chart input with no schema. - `deprecated` (string): The bundle's own deprecation message for this input. - `validations` (array of ContractValidation): A Terraform variable's validation blocks, in declaration order. - `condition` (string) - `error_message` (string) - `schema` (map of string to Value): The JSON Schema a chart's values.schema.json declares for this input, verbatim, so a value can be checked the way Helm will check it. - `outputs` (array of ContractOutput) - `name` (string) - `description` (string) - `sensitive` (boolean) - `provenance` (Provenance): Where the bytes came from. Read-only. - `kind` (ProvenanceKind): ProvenanceKind is how the bytes arrived. One of `PROVENANCE_KIND_UNSPECIFIED`, `LOCAL`, `GIT`, `PULL`. - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. Empty for a local publish with no remote. - `ref` (string): The ref that was asked for (tag, branch, chart version), when any. - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version. - `path` (string): The path within the source the bundle was taken from. Empty means the root. - `dirty` (boolean): The working copy carried uncommitted changes when it was published. Only meaningful for LOCAL, and only ever true when the CLI said so. - `pins` (array of Pin): Every remote module or chart the closure step vendored into the bundle, pinned to what it resolved. - `source` (string): The source as the bundle declared it, before rewriting. - `constraint` (string): The constraint that was asked for, when any. - `resolved` (string): What it resolved to: an exact version or commit. - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only. - `id` (string) - `name` (string) - `hosts` (array of string): The hosts it was presented to during this pull. - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this revision can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096. - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256. - `findings` (array of Finding): What the publish gate found. Informational findings do not block a publish; a revision with findings is published with them attached, and the findings delta between two revisions is what an upgrade review reads. Read-only. - `severity` (FindingSeverity): FindingSeverity ranks what the publish gate found. One of `FINDING_SEVERITY_UNSPECIFIED`, `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. - `source` (string): What produced it: `provider-constraint`, `checkov`, `trivy`, `image-ref`. - `code` (string): The producer's own identifier for the rule, when it has one (e.g. `CKV_AWS_18`). - `message` (string) - `path` (string): Where in the bundle, when it applies. - `status` (RevisionStatus): RevisionStatus is a revision's lifecycle. There is no deleted state. One of `REVISION_STATUS_UNSPECIFIED`, `PUBLISHED`, `DEPRECATED`, `REVOKED`. Read-only. - `status_changed_at` (Timestamp): When and why the status last changed. Unset on a revision that has only ever been PUBLISHED. Read-only. - `status_reason` (string): Read-only. - `tags` (array of string): The tags currently naming this revision. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Retrieve a revision" canonical: "https://admiral.io/docs/api/components/RegistryAPI_GetRevision" --- # Retrieve a revision `GET https://api.admiral.io/v1/components/{component_id}/revisions/{reference}` Scope: `component:read` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. - `reference` (string, required): A tag name (`v1.2.0`, `latest`) or a digest (`sha256:`). A digest is recognised by its prefix; everything else is looked up as a tag. Pattern `^(sha256:[0-9a-f]{64}|[A-Za-z0-9][A-Za-z0-9._+-]{0,127})$`. Length 1 to 128. ### Response 200 Success - `revision` (Revision): Revision is one published artifact. Immutable except for its status. - `id` (string): Unique identifier (UUID). Internal handle; references use the digest. Read-only. - `component_id` (string): The component this revision belongs to (UUID). Read-only. - `digest` (string): The identity: SHA-256 of the normalized bundle, as `sha256:`. Read-only. - `kind` (ComponentKind): ComponentKind is what a revision's bundle is, detected by inspection at publish: a Chart.yaml means HELM, .tf files mean TERRAFORM, anything else that is Kubernetes YAML means MANIFESTS. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. Read-only. - `size_bytes` (string (int64)): Size of the stored bundle in bytes. Read-only. - `contract` (Contract): The inputs and outputs the bundle exposes. Inferred from the bundle at publish; curated by a publisher once the contract format lands. Read-only. - `inputs` (array of ContractInput) - `name` (string) - `type` (string): The type as the bundle declares it: a Terraform type expression, or for a chart one of bool, number, string, list, object or null. A chart's full constraint is in schema. - `description` (string) - `required` (boolean): True when the bundle gives it no default. - `default` (Value): The declared default, when there is one. - `sensitive` (boolean): The value is a secret: never rendered in review, and resolved by the runner from a reference rather than stored in the change set. - `ephemeral` (boolean): The value must not land in plan or state (Terraform 1.10+ ephemeral inputs). Implies sensitive. - `nullable` (boolean): Whether null is an accepted value. Unset when the bundle does not say, which is a chart input with no schema. - `deprecated` (string): The bundle's own deprecation message for this input. - `validations` (array of ContractValidation): A Terraform variable's validation blocks, in declaration order. - `condition` (string) - `error_message` (string) - `schema` (map of string to Value): The JSON Schema a chart's values.schema.json declares for this input, verbatim, so a value can be checked the way Helm will check it. - `outputs` (array of ContractOutput) - `name` (string) - `description` (string) - `sensitive` (boolean) - `provenance` (Provenance): Where the bytes came from. Read-only. - `kind` (ProvenanceKind): ProvenanceKind is how the bytes arrived. One of `PROVENANCE_KIND_UNSPECIFIED`, `LOCAL`, `GIT`, `PULL`. - `uri` (string): The repository or location the bytes were read from: a git remote URL, a Helm repository URL, an OCI reference. Empty for a local publish with no remote. - `ref` (string): The ref that was asked for (tag, branch, chart version), when any. - `commit` (string): What the ref resolved to: a commit SHA, or the exact chart version. - `path` (string): The path within the source the bundle was taken from. Empty means the root. - `dirty` (boolean): The working copy carried uncommitted changes when it was published. Only meaningful for LOCAL, and only ever true when the CLI said so. - `pins` (array of Pin): Every remote module or chart the closure step vendored into the bundle, pinned to what it resolved. - `source` (string): The source as the bundle declared it, before rewriting. - `constraint` (string): The constraint that was asked for, when any. - `resolved` (string): What it resolved to: an exact version or commit. - `credentials` (array of PresentedCredential): The credentials the platform presented while fetching, for PULL: which secret reached which hosts. Lineage, not a grant; a later pull attaches its own. Set by the server; ignored on a publish request. Read-only. - `id` (string) - `name` (string) - `hosts` (array of string): The hosts it was presented to during this pull. - `commit_message` (string): The message of the commit that produced these bytes, as written, so a reader deciding whether to move to this revision can see what changed. Captured at publish because it cannot be recovered after a force-push or once the source is gone. Empty when there is no commit, or upstream carried no notes. Length at most 4096. - `commit_author` (string): Who wrote that commit, by name. Not the email address. Length at most 256. - `findings` (array of Finding): What the publish gate found. Informational findings do not block a publish; a revision with findings is published with them attached, and the findings delta between two revisions is what an upgrade review reads. Read-only. - `severity` (FindingSeverity): FindingSeverity ranks what the publish gate found. One of `FINDING_SEVERITY_UNSPECIFIED`, `INFO`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. - `source` (string): What produced it: `provider-constraint`, `checkov`, `trivy`, `image-ref`. - `code` (string): The producer's own identifier for the rule, when it has one (e.g. `CKV_AWS_18`). - `message` (string) - `path` (string): Where in the bundle, when it applies. - `status` (RevisionStatus): RevisionStatus is a revision's lifecycle. There is no deleted state. One of `REVISION_STATUS_UNSPECIFIED`, `PUBLISHED`, `DEPRECATED`, `REVOKED`. Read-only. - `status_changed_at` (Timestamp): When and why the status last changed. Unset on a revision that has only ever been PUBLISHED. Read-only. - `status_reason` (string): Read-only. - `tags` (array of string): The tags currently naming this revision. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Delete a tag" canonical: "https://admiral.io/docs/api/components/RegistryAPI_DeleteTag" --- # Delete a tag `DELETE https://api.admiral.io/v1/components/{component_id}/tags/{name}` Scope: `component:write` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. - `name` (string, required): The name path parameter. Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`. Length 1 to 128. ### Response 200 Success Type: DeleteTagResponse. --- title: "Set a tag" canonical: "https://admiral.io/docs/api/components/RegistryAPI_SetTag" --- # Set a tag `PUT https://api.admiral.io/v1/components/{component_id}/tags/{name}` Scope: `component:publish` ### Path parameters - `component_id` (string (uuid), required): The component_id path parameter. - `name` (string, required): The name path parameter. Pattern `^[A-Za-z0-9][A-Za-z0-9._+-]{0,127}$`. Length 1 to 128. ### Request body - `digest` (string, required): The revision to name, as `sha256:`. Pattern `^sha256:[0-9a-f]{64}$`. ### Response 200 Success - `tag` (Tag): Tag is a name pointing at a revision. - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only. - `digest` (string): The revision it names, as `sha256:`. Read-only. - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Retrieve a component" canonical: "https://admiral.io/docs/api/components/RegistryAPI_GetComponent" --- # Retrieve a component `GET https://api.admiral.io/v1/components/{name}` Scope: `component:read` ### Path parameters - `name` (string, required): `cloud-sql`, or `namespace/cloud-sql`. Pattern `^([a-z]([a-z0-9-]{0,61}[a-z0-9])?/)?[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 127. ### Response 200 Success - `component` (Component): Component is a registry entry: a name, and the revisions and tags beneath it. - `id` (string): Unique identifier (UUID). Read-only. - `name` (string): The name as it is written: `cloud-sql`, or `payments/cloud-sql` once team namespaces exist. Unique within the tenant. Immutable. Read-only. - `description` (string): Length at most 1024. - `labels` (map of string to string): Key-value metadata for filtering (e.g. `{"team": "payments", "runtime": "terraform"}`), the same labels every Admiral resource carries. - `tags` (array of Tag): Every tag on the component, by name. Read-only. - `name` (string): As written after the colon in `cloud-sql:v1.2.0`. Read-only. - `digest` (string): The revision it names, as `sha256:`. Read-only. - `immutable` (boolean): True for a semver tag: it never moves once assigned. Decided from the name, so two tags with the same name are always the same class. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "List credentials" canonical: "https://admiral.io/docs/api/credentials/CredentialAPI_ListCredentials" --- # List credentials `GET https://api.admiral.io/v1/credentials` Scope: `credential:read` ### Query parameters - `filter` (string): Reserved for a filter expression; nothing reads it yet. Length at most 1024. - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. - `type` (CredentialType): Only credentials of this type, when set. enum.defined_only = true One of `CREDENTIAL_TYPE_UNSPECIFIED`, `CREDENTIAL_TYPE_SSH_KEY`, `CREDENTIAL_TYPE_BASIC_AUTH`, `CREDENTIAL_TYPE_BEARER_TOKEN`, `CREDENTIAL_TYPE_GITHUB_APP`. ### Response 200 Success - `credentials` (array of Credential) - `id` (string (uuid)): Read-only. - `name` (string): Unique within the tenant. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Length at most 1024. - `type` (CredentialType): (IMMUTABLE) Immutable after creation. One of `CREDENTIAL_TYPE_UNSPECIFIED`, `CREDENTIAL_TYPE_SSH_KEY`, `CREDENTIAL_TYPE_BASIC_AUTH`, `CREDENTIAL_TYPE_BEARER_TOKEN`, `CREDENTIAL_TYPE_GITHUB_APP`. - `auth_config` (AuthConfig): Write-only. Empty in every response. - At most one of `basic_auth`, `bearer_token`, `github_app`, `ssh_key` is set. - `basic_auth` (BasicAuth): BasicAuth is a username and password, or a username and a token that the host takes as a password (a registry-scoped token, an app password). - `username` (string): Length 1 to 256. - `password` (string): Write-only. Length at most 4096. - `bearer_token` (BearerTokenAuth): BearerTokenAuth is one token. - `token` (string): Write-only. Length at most 4096. - `github_app` (GitHubAppAuth): GitHubAppAuth identifies a GitHub App installation and holds the app's private key, from which the platform mints installation tokens. - `app_id` (string (int64)): The app's numeric id, from the app's settings page. - `installation_id` (string (int64)): The installation's numeric id, from the installation's URL. - `private_key` (string): The app's PEM-encoded RSA private key. Write-only. Length at most 16384. - `api_url` (string (uri)): The REST API base, for GitHub Enterprise Server: `https://github.acme.example/api/v3`. Empty is `https://api.github.com`. Length at most 512. - `ssh_key` (SSHKeyAuth): SSHKeyAuth is a PEM-encoded private key and its passphrase, if any. - `private_key` (string): Write-only. Length at most 16384. - `passphrase` (string): Write-only. Length at most 1024. - `labels` (map of string to string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `allowed_hosts` (array of string): Hosts this credential may be presented to, as a guard: empty means any host its type fits; set means the platform refuses to present it anywhere else, whatever it is attached to. Hostnames, optionally with a port: `github.acme.example`, `harbor.acme.example:8443`. No scheme, no path. Items at most 32. - `next_page_token` (string) --- title: "Create a credential" canonical: "https://admiral.io/docs/api/credentials/CredentialAPI_CreateCredential" --- # Create a credential `POST https://api.admiral.io/v1/credentials` The `type` and the populated `auth_config` variant must agree. Scope: `credential:write` ### Request body - `name` (string, required): Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Length at most 1024. - `type` (CredentialType, required): enum.defined_only = true One of `CREDENTIAL_TYPE_SSH_KEY`, `CREDENTIAL_TYPE_BASIC_AUTH`, `CREDENTIAL_TYPE_BEARER_TOKEN`, `CREDENTIAL_TYPE_GITHUB_APP`. - `auth_config` (AuthConfig, required): AuthConfig is the secret, one variant matching the credential's type. - At most one of `basic_auth`, `bearer_token`, `github_app`, `ssh_key` is set. - `basic_auth` (BasicAuth): BasicAuth is a username and password, or a username and a token that the host takes as a password (a registry-scoped token, an app password). - `username` (string): Length 1 to 256. - `password` (string): Write-only. Length at most 4096. - `bearer_token` (BearerTokenAuth): BearerTokenAuth is one token. - `token` (string): Write-only. Length at most 4096. - `github_app` (GitHubAppAuth): GitHubAppAuth identifies a GitHub App installation and holds the app's private key, from which the platform mints installation tokens. - `app_id` (string (int64)): The app's numeric id, from the app's settings page. - `installation_id` (string (int64)): The installation's numeric id, from the installation's URL. - `private_key` (string): The app's PEM-encoded RSA private key. Write-only. Length at most 16384. - `api_url` (string (uri)): The REST API base, for GitHub Enterprise Server: `https://github.acme.example/api/v3`. Empty is `https://api.github.com`. Length at most 512. - `ssh_key` (SSHKeyAuth): SSHKeyAuth is a PEM-encoded private key and its passphrase, if any. - `private_key` (string): Write-only. Length at most 16384. - `passphrase` (string): Write-only. Length at most 1024. - `labels` (map of string to string) - `allowed_hosts` (array of string): Items at most 32. ### Response 200 Success - `credential` (Credential): Credential is a registered credential's metadata. The secret is set through `auth_config` and never read back; responses carry it empty. - `id` (string (uuid)): Read-only. - `name` (string): Unique within the tenant. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Length at most 1024. - `type` (CredentialType): (IMMUTABLE) Immutable after creation. One of `CREDENTIAL_TYPE_UNSPECIFIED`, `CREDENTIAL_TYPE_SSH_KEY`, `CREDENTIAL_TYPE_BASIC_AUTH`, `CREDENTIAL_TYPE_BEARER_TOKEN`, `CREDENTIAL_TYPE_GITHUB_APP`. - `auth_config` (AuthConfig): Write-only. Empty in every response. - At most one of `basic_auth`, `bearer_token`, `github_app`, `ssh_key` is set. - `basic_auth` (BasicAuth): BasicAuth is a username and password, or a username and a token that the host takes as a password (a registry-scoped token, an app password). - `username` (string): Length 1 to 256. - `password` (string): Write-only. Length at most 4096. - `bearer_token` (BearerTokenAuth): BearerTokenAuth is one token. - `token` (string): Write-only. Length at most 4096. - `github_app` (GitHubAppAuth): GitHubAppAuth identifies a GitHub App installation and holds the app's private key, from which the platform mints installation tokens. - `app_id` (string (int64)): The app's numeric id, from the app's settings page. - `installation_id` (string (int64)): The installation's numeric id, from the installation's URL. - `private_key` (string): The app's PEM-encoded RSA private key. Write-only. Length at most 16384. - `api_url` (string (uri)): The REST API base, for GitHub Enterprise Server: `https://github.acme.example/api/v3`. Empty is `https://api.github.com`. Length at most 512. - `ssh_key` (SSHKeyAuth): SSHKeyAuth is a PEM-encoded private key and its passphrase, if any. - `private_key` (string): Write-only. Length at most 16384. - `passphrase` (string): Write-only. Length at most 1024. - `labels` (map of string to string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `allowed_hosts` (array of string): Hosts this credential may be presented to, as a guard: empty means any host its type fits; set means the platform refuses to present it anywhere else, whatever it is attached to. Hostnames, optionally with a port: `github.acme.example`, `harbor.acme.example:8443`. No scheme, no path. Items at most 32. --- title: "Update a credential" canonical: "https://admiral.io/docs/api/credentials/CredentialAPI_UpdateCredential" --- # Update a credential `PATCH https://api.admiral.io/v1/credentials/{credential.id}` Scope: `credential:write` ### Path parameters - `credential.id` (string (uuid), required): The credential.id path parameter. Read-only. ### Request body - `update_mask` (FieldMask): Paths from `description`, `labels`, `allowed_hosts`, `auth_config`. Empty means every updatable field the message carries. ### Response 200 Success - `credential` (Credential): Credential is a registered credential's metadata. The secret is set through `auth_config` and never read back; responses carry it empty. - `id` (string (uuid)): Read-only. - `name` (string): Unique within the tenant. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Length at most 1024. - `type` (CredentialType): (IMMUTABLE) Immutable after creation. One of `CREDENTIAL_TYPE_UNSPECIFIED`, `CREDENTIAL_TYPE_SSH_KEY`, `CREDENTIAL_TYPE_BASIC_AUTH`, `CREDENTIAL_TYPE_BEARER_TOKEN`, `CREDENTIAL_TYPE_GITHUB_APP`. - `auth_config` (AuthConfig): Write-only. Empty in every response. - At most one of `basic_auth`, `bearer_token`, `github_app`, `ssh_key` is set. - `basic_auth` (BasicAuth): BasicAuth is a username and password, or a username and a token that the host takes as a password (a registry-scoped token, an app password). - `username` (string): Length 1 to 256. - `password` (string): Write-only. Length at most 4096. - `bearer_token` (BearerTokenAuth): BearerTokenAuth is one token. - `token` (string): Write-only. Length at most 4096. - `github_app` (GitHubAppAuth): GitHubAppAuth identifies a GitHub App installation and holds the app's private key, from which the platform mints installation tokens. - `app_id` (string (int64)): The app's numeric id, from the app's settings page. - `installation_id` (string (int64)): The installation's numeric id, from the installation's URL. - `private_key` (string): The app's PEM-encoded RSA private key. Write-only. Length at most 16384. - `api_url` (string (uri)): The REST API base, for GitHub Enterprise Server: `https://github.acme.example/api/v3`. Empty is `https://api.github.com`. Length at most 512. - `ssh_key` (SSHKeyAuth): SSHKeyAuth is a PEM-encoded private key and its passphrase, if any. - `private_key` (string): Write-only. Length at most 16384. - `passphrase` (string): Write-only. Length at most 1024. - `labels` (map of string to string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `allowed_hosts` (array of string): Hosts this credential may be presented to, as a guard: empty means any host its type fits; set means the platform refuses to present it anywhere else, whatever it is attached to. Hostnames, optionally with a port: `github.acme.example`, `harbor.acme.example:8443`. No scheme, no path. Items at most 32. --- title: "Get a credential" canonical: "https://admiral.io/docs/api/credentials/CredentialAPI_GetCredential" --- # Get a credential `GET https://api.admiral.io/v1/credentials/{credential_id}` Scope: `credential:read` ### Path parameters - `credential_id` (string (uuid), required): The credential_id path parameter. ### Response 200 Success - `credential` (Credential): Credential is a registered credential's metadata. The secret is set through `auth_config` and never read back; responses carry it empty. - `id` (string (uuid)): Read-only. - `name` (string): Unique within the tenant. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Length at most 1024. - `type` (CredentialType): (IMMUTABLE) Immutable after creation. One of `CREDENTIAL_TYPE_UNSPECIFIED`, `CREDENTIAL_TYPE_SSH_KEY`, `CREDENTIAL_TYPE_BASIC_AUTH`, `CREDENTIAL_TYPE_BEARER_TOKEN`, `CREDENTIAL_TYPE_GITHUB_APP`. - `auth_config` (AuthConfig): Write-only. Empty in every response. - At most one of `basic_auth`, `bearer_token`, `github_app`, `ssh_key` is set. - `basic_auth` (BasicAuth): BasicAuth is a username and password, or a username and a token that the host takes as a password (a registry-scoped token, an app password). - `username` (string): Length 1 to 256. - `password` (string): Write-only. Length at most 4096. - `bearer_token` (BearerTokenAuth): BearerTokenAuth is one token. - `token` (string): Write-only. Length at most 4096. - `github_app` (GitHubAppAuth): GitHubAppAuth identifies a GitHub App installation and holds the app's private key, from which the platform mints installation tokens. - `app_id` (string (int64)): The app's numeric id, from the app's settings page. - `installation_id` (string (int64)): The installation's numeric id, from the installation's URL. - `private_key` (string): The app's PEM-encoded RSA private key. Write-only. Length at most 16384. - `api_url` (string (uri)): The REST API base, for GitHub Enterprise Server: `https://github.acme.example/api/v3`. Empty is `https://api.github.com`. Length at most 512. - `ssh_key` (SSHKeyAuth): SSHKeyAuth is a PEM-encoded private key and its passphrase, if any. - `private_key` (string): Write-only. Length at most 16384. - `passphrase` (string): Write-only. Length at most 1024. - `labels` (map of string to string) - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this; use the plain string `created_by` UUID on request messages instead. Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `allowed_hosts` (array of string): Hosts this credential may be presented to, as a guard: empty means any host its type fits; set means the platform refuses to present it anywhere else, whatever it is attached to. Hostnames, optionally with a port: `github.acme.example`, `harbor.acme.example:8443`. No scheme, no path. Items at most 32. --- title: "Delete a credential" canonical: "https://admiral.io/docs/api/credentials/CredentialAPI_DeleteCredential" --- # Delete a credential `DELETE https://api.admiral.io/v1/credentials/{credential_id}` Scope: `credential:write` ### Path parameters - `credential_id` (string (uuid), required): The credential_id path parameter. ### Response 200 Success Type: DeleteCredentialResponse. --- title: "List environments" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_ListEnvironments" --- # List environments `GET https://api.admiral.io/v1/environments` Scope: `env:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `application_id`: filter by parent application (UUID). - `name`: filter by environment name. - `labels.key`: filter by label key. Example: `field['application_id'] = '' AND field['name'] = 'prod'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of environments to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `environments` (array of Environment): The list of environments. - `id` (string (uuid)): Unique identifier for the environment (UUID). Read-only. - `application_id` (string (uuid)): The application this environment belongs to (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "prod", "staging-us-east"). Unique within the application. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the environment's purpose (e.g., "US East production serving live traffic" or "Shared staging for QA validation before prod promotion"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering environments (e.g., `{"region": "us-east-1", "tier": "production"}`). - `has_pending_changes` (boolean): Whether the environment has configuration changes that have not yet been deployed. Server-derived by comparing current resolved config (variables, component settings, overrides, source versions) against the last successful run's snapshot. False if no successful run exists yet (a fresh environment with no runs returns false; use `last_deployed_at` to distinguish "clean" from "never deployed"). Read-only. - `last_deployed_at` (Timestamp): When the last successful run for this environment completed. Absent if no successful run has occurred yet. Read-only. - `created_by` (ActorRef): The user or agent who created this environment (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the environment was created. Read-only. - `updated_at` (Timestamp): When the environment was last updated. Read-only. - `kubernetes` (KubernetesTarget): Where workload components go. Omitted fields keep their defaults. - `namespace` (string): The namespace a component renders into unless it names its own. Set to `-` when the environment is created if left empty; at most 63 characters. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `create_namespaces` (boolean): Whether a missing namespace is created at apply. The agent's own setting and its RBAC can still refuse. Defaults to true on create. - `capabilities` (KubernetesCapabilities): What the cluster reported, rendered against at prepare. Absent until an agent reports. Read-only. - `kube_version` (string): e.g. `v1.31.2`. - `api_versions` (array of string): Group/version strings, e.g. `monitoring.coreos.com/v1`. - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `agent_id` (string (uuid)): The agent this environment deploys through. It must be one the agent's owner granted to the tenant, a team, or this application. Empty selects none; capabilities then come from no cluster. - `approval_required` (boolean): Whether applying a change set here needs an approval. Off by default. - `generation` (string (int64)): Moves each time an apply changes the environment. A change set records the generation it was cut from. Read-only. - `held_by_change_set_id` (string): The change set whose partial apply holds the environment. Nothing else applies until it is resolved. Read-only. - `prune` (boolean): Whether an apply deletes objects a component no longer renders, and the objects of a component it removes. Off, they are orphaned: left in the cluster and no longer managed. An object annotated `admiral.io/prune: "false"` is orphaned either way. Defaults to true on create. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Create an environment" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_CreateEnvironment" --- # Create an environment `POST https://api.admiral.io/v1/environments` Scope: `env:write` ### Request body - `application_id` (string (uuid), required): The application to create this environment for (UUID). - `name` (string, required): URL-safe, human-readable identifier (e.g., "prod", "staging-us-east"). Unique within the application. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the environment's purpose. Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering environments. - `kubernetes` (KubernetesTarget): Where workload components go. - `namespace` (string): The namespace a component renders into unless it names its own. Set to `-` when the environment is created if left empty; at most 63 characters. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `create_namespaces` (boolean): Whether a missing namespace is created at apply. The agent's own setting and its RBAC can still refuse. Defaults to true on create. - `capabilities` (KubernetesCapabilities): What the cluster reported, rendered against at prepare. Absent until an agent reports. Read-only. - `kube_version` (string): e.g. `v1.31.2`. - `api_versions` (array of string): Group/version strings, e.g. `monitoring.coreos.com/v1`. - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `agent_id` (string (uuid)): The agent this environment deploys through. It must be one the agent's owner granted to the tenant, a team, or this application. Empty selects none; capabilities then come from no cluster. ### Response 200 Success - `environment` (Environment): The created environment. - `id` (string (uuid)): Unique identifier for the environment (UUID). Read-only. - `application_id` (string (uuid)): The application this environment belongs to (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "prod", "staging-us-east"). Unique within the application. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the environment's purpose (e.g., "US East production serving live traffic" or "Shared staging for QA validation before prod promotion"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering environments (e.g., `{"region": "us-east-1", "tier": "production"}`). - `has_pending_changes` (boolean): Whether the environment has configuration changes that have not yet been deployed. Server-derived by comparing current resolved config (variables, component settings, overrides, source versions) against the last successful run's snapshot. False if no successful run exists yet (a fresh environment with no runs returns false; use `last_deployed_at` to distinguish "clean" from "never deployed"). Read-only. - `last_deployed_at` (Timestamp): When the last successful run for this environment completed. Absent if no successful run has occurred yet. Read-only. - `created_by` (ActorRef): The user or agent who created this environment (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the environment was created. Read-only. - `updated_at` (Timestamp): When the environment was last updated. Read-only. - `kubernetes` (KubernetesTarget): Where workload components go. Omitted fields keep their defaults. - `namespace` (string): The namespace a component renders into unless it names its own. Set to `-` when the environment is created if left empty; at most 63 characters. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `create_namespaces` (boolean): Whether a missing namespace is created at apply. The agent's own setting and its RBAC can still refuse. Defaults to true on create. - `capabilities` (KubernetesCapabilities): What the cluster reported, rendered against at prepare. Absent until an agent reports. Read-only. - `kube_version` (string): e.g. `v1.31.2`. - `api_versions` (array of string): Group/version strings, e.g. `monitoring.coreos.com/v1`. - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `agent_id` (string (uuid)): The agent this environment deploys through. It must be one the agent's owner granted to the tenant, a team, or this application. Empty selects none; capabilities then come from no cluster. - `approval_required` (boolean): Whether applying a change set here needs an approval. Off by default. - `generation` (string (int64)): Moves each time an apply changes the environment. A change set records the generation it was cut from. Read-only. - `held_by_change_set_id` (string): The change set whose partial apply holds the environment. Nothing else applies until it is resolved. Read-only. - `prune` (boolean): Whether an apply deletes objects a component no longer renders, and the objects of a component it removes. Off, they are orphaned: left in the cluster and no longer managed. An object annotated `admiral.io/prune: "false"` is orphaned either way. Defaults to true on create. --- title: "Update an environment" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_UpdateEnvironment" --- # Update an environment `PATCH https://api.admiral.io/v1/environments/{environment.id}` Scope: `env:write` ### Path parameters - `environment.id` (string (uuid), required): Unique identifier for the environment (UUID). Read-only. ### Request body - `update_mask` (FieldMask): The set of fields to update. Optional; if omitted, all populated fields are updated. Pass `*` for full replacement. Supported fields: `name`, `description`, `labels`, `kubernetes.namespace`, `kubernetes.create_namespaces`, `kubernetes.agent_id`, `approval_required`, `prune`. ### Response 200 Success - `environment` (Environment): The updated environment. - `id` (string (uuid)): Unique identifier for the environment (UUID). Read-only. - `application_id` (string (uuid)): The application this environment belongs to (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "prod", "staging-us-east"). Unique within the application. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the environment's purpose (e.g., "US East production serving live traffic" or "Shared staging for QA validation before prod promotion"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering environments (e.g., `{"region": "us-east-1", "tier": "production"}`). - `has_pending_changes` (boolean): Whether the environment has configuration changes that have not yet been deployed. Server-derived by comparing current resolved config (variables, component settings, overrides, source versions) against the last successful run's snapshot. False if no successful run exists yet (a fresh environment with no runs returns false; use `last_deployed_at` to distinguish "clean" from "never deployed"). Read-only. - `last_deployed_at` (Timestamp): When the last successful run for this environment completed. Absent if no successful run has occurred yet. Read-only. - `created_by` (ActorRef): The user or agent who created this environment (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the environment was created. Read-only. - `updated_at` (Timestamp): When the environment was last updated. Read-only. - `kubernetes` (KubernetesTarget): Where workload components go. Omitted fields keep their defaults. - `namespace` (string): The namespace a component renders into unless it names its own. Set to `-` when the environment is created if left empty; at most 63 characters. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `create_namespaces` (boolean): Whether a missing namespace is created at apply. The agent's own setting and its RBAC can still refuse. Defaults to true on create. - `capabilities` (KubernetesCapabilities): What the cluster reported, rendered against at prepare. Absent until an agent reports. Read-only. - `kube_version` (string): e.g. `v1.31.2`. - `api_versions` (array of string): Group/version strings, e.g. `monitoring.coreos.com/v1`. - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `agent_id` (string (uuid)): The agent this environment deploys through. It must be one the agent's owner granted to the tenant, a team, or this application. Empty selects none; capabilities then come from no cluster. - `approval_required` (boolean): Whether applying a change set here needs an approval. Off by default. - `generation` (string (int64)): Moves each time an apply changes the environment. A change set records the generation it was cut from. Read-only. - `held_by_change_set_id` (string): The change set whose partial apply holds the environment. Nothing else applies until it is resolved. Read-only. - `prune` (boolean): Whether an apply deletes objects a component no longer renders, and the objects of a component it removes. Off, they are orphaned: left in the cluster and no longer managed. An object annotated `admiral.io/prune: "false"` is orphaned either way. Defaults to true on create. --- title: "Retrieve an environment" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_GetEnvironment" --- # Retrieve an environment `GET https://api.admiral.io/v1/environments/{environment_id}` Scope: `env:read` ### Path parameters - `environment_id` (string (uuid), required): The unique identifier of the environment (UUID). ### Response 200 Success - `environment` (Environment): The retrieved environment. - `id` (string (uuid)): Unique identifier for the environment (UUID). Read-only. - `application_id` (string (uuid)): The application this environment belongs to (UUID). Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "prod", "staging-us-east"). Unique within the application. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the environment's purpose (e.g., "US East production serving live traffic" or "Shared staging for QA validation before prod promotion"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering environments (e.g., `{"region": "us-east-1", "tier": "production"}`). - `has_pending_changes` (boolean): Whether the environment has configuration changes that have not yet been deployed. Server-derived by comparing current resolved config (variables, component settings, overrides, source versions) against the last successful run's snapshot. False if no successful run exists yet (a fresh environment with no runs returns false; use `last_deployed_at` to distinguish "clean" from "never deployed"). Read-only. - `last_deployed_at` (Timestamp): When the last successful run for this environment completed. Absent if no successful run has occurred yet. Read-only. - `created_by` (ActorRef): The user or agent who created this environment (server-populated from token). Read-only. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the environment was created. Read-only. - `updated_at` (Timestamp): When the environment was last updated. Read-only. - `kubernetes` (KubernetesTarget): Where workload components go. Omitted fields keep their defaults. - `namespace` (string): The namespace a component renders into unless it names its own. Set to `-` when the environment is created if left empty; at most 63 characters. Pattern `^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$`. Length at most 63. - `create_namespaces` (boolean): Whether a missing namespace is created at apply. The agent's own setting and its RBAC can still refuse. Defaults to true on create. - `capabilities` (KubernetesCapabilities): What the cluster reported, rendered against at prepare. Absent until an agent reports. Read-only. - `kube_version` (string): e.g. `v1.31.2`. - `api_versions` (array of string): Group/version strings, e.g. `monitoring.coreos.com/v1`. - `reported_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `agent_id` (string (uuid)): The agent this environment deploys through. It must be one the agent's owner granted to the tenant, a team, or this application. Empty selects none; capabilities then come from no cluster. - `approval_required` (boolean): Whether applying a change set here needs an approval. Off by default. - `generation` (string (int64)): Moves each time an apply changes the environment. A change set records the generation it was cut from. Read-only. - `held_by_change_set_id` (string): The change set whose partial apply holds the environment. Nothing else applies until it is resolved. Read-only. - `prune` (boolean): Whether an apply deletes objects a component no longer renders, and the objects of a component it removes. Off, they are orphaned: left in the cluster and no longer managed. An object annotated `admiral.io/prune: "false"` is orphaned either way. Defaults to true on create. --- title: "Delete an environment" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_DeleteEnvironment" --- # Delete an environment `DELETE https://api.admiral.io/v1/environments/{environment_id}` Scope: `env:write` ### Path parameters - `environment_id` (string (uuid), required): The unique identifier of the environment to delete (UUID). ### Query parameters - `force` (boolean): When true, bypass the children-exist check and cascade-delete all run records (metadata only). ### Response 200 Success Type: DeleteEnvironmentResponse. --- title: "List components deployed to an environment" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_ListEnvironmentComponents" --- # List components deployed to an environment `GET https://api.admiral.io/v1/environments/{environment_id}/components` Components without a SUCCEEDED revision (e.g. CREATE entries that failed mid-plan) still appear, with `last_revision_status` and `last_deployed_at` empty. Scope: `env:read` ### Path parameters - `environment_id` (string (uuid), required): The environment whose components should be listed (UUID). ### Response 200 Success - `components` (array of EnvironmentComponent): Active (not soft-deleted) components attached to the environment, sorted by name. - `name` (string): Component name (stable identifier set at creation). - `kind` (ComponentKind): What the component's pinned revision is (TERRAFORM, HELM, MANIFESTS), denormalized from the registry. One of `COMPONENT_KIND_UNSPECIFIED`, `TERRAFORM`, `HELM`, `MANIFESTS`. - `ref` (string): The git ref / version selector the component deploys. - `last_revision_id` (string): ID of the last-succeeded revision for this component in this env, if any (UUID). Empty when the component has never reached SUCCEEDED. - `last_revision_status` (RevisionStatus): Status of the last revision (SUCCEEDED when populated). UNSPECIFIED means the component has no last-succeeded revision yet. One of `REVISION_STATUS_UNSPECIFIED`, `REVISION_STATUS_PENDING`, `REVISION_STATUS_QUEUED`, `REVISION_STATUS_PLANNING`, `REVISION_STATUS_PLANNED`, `REVISION_STATUS_APPLYING`, `REVISION_STATUS_SUCCEEDED`, `REVISION_STATUS_FAILED`, `REVISION_STATUS_BLOCKED`, `REVISION_STATUS_CANCELED`, `REVISION_STATUS_SUPERSEDED`, `REVISION_STATUS_DEFERRED`, `REVISION_STATUS_STALE`, `REVISION_STATUS_AWAITING_APPROVAL`. - `last_deployed_at` (Timestamp): When the last-succeeded revision completed. --- title: "List variables for an environment" canonical: "https://admiral.io/docs/api/environments/EnvironmentAPI_ListEnvironmentVariables" --- # List variables for an environment `GET https://api.admiral.io/v1/environments/{environment_id}/variables` Sensitive variable values are masked in the response. Scope: `var:read` ### Path parameters - `environment_id` (string (uuid), required): The environment whose variables should be listed (UUID). ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `key`: filter by variable key (supports prefix matching via ~=). - `sensitive`: filter by sensitivity flag. - `type`: filter by variable type (STRING, NUMBER, BOOLEAN, COMPLEX). - `source`: filter by source (USER, INFRASTRUCTURE). Example: `field['source'] = 'USER' AND field['sensitive'] = false` Length at most 1024. - `page_size` (integer (int32)): Maximum number of variables to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `variables` (array of Variable): The variables scoped to this environment. Sensitive values are masked. - `id` (string (uuid)): Unique identifier for the variable (UUID). - `key` (string): The variable name. For user-created variables, must be a valid environment variable identifier (e.g., "DATABASE_URL", "API_KEY"). Infrastructure output variables use dot-namespaced keys (e.g., "vpc.vpc_id", "database.endpoint") and are system-managed. Pattern `^[A-Za-z_][A-Za-z0-9_.]{0,62}$`. Length 1 to 63. - `value` (string): The variable value. Always stored as a string; use `type` to indicate how to interpret it. Masked or empty for sensitive variables in responses. For COMPLEX type, this is a JSON-encoded string (e.g., '["a","b"]' or '{"key":"value"}'). The rendering engine converts it to the target format (HCL for Terraform, YAML for Helm). - `sensitive` (boolean): Whether the variable value is encrypted at rest and masked in API responses. - `type` (VariableType): How the value should be interpreted by the rendering engine and displayed in the UI. Defaults to STRING if not specified. One of `VARIABLE_TYPE_UNSPECIFIED`, `VARIABLE_TYPE_STRING`, `VARIABLE_TYPE_NUMBER`, `VARIABLE_TYPE_BOOLEAN`, `VARIABLE_TYPE_COMPLEX`. - `description` (string): Optional description of the variable's purpose (e.g., "Maximum replica count for production scaling" or "RDS instance class per environment"). Length at most 1024. - `application_id` (string (uuid)): The application this variable belongs to (UUID). Always set; variables are env-scoped and inherit their app from the environment. - `environment_id` (string (uuid)): The environment this variable is scoped to (UUID). Always set; variables are env-scoped. - `source` (VariableSource): How the variable was created. USER for change-set-managed variables, INFRASTRUCTURE for variables produced by engine output capture (Terraform or OpenTofu). Server-populated. One of `VARIABLE_SOURCE_UNSPECIFIED`, `VARIABLE_SOURCE_USER`, `VARIABLE_SOURCE_INFRASTRUCTURE`. - `created_by` (ActorRef): The user or agent who created this variable (server-populated from token). - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the variable was created. - `updated_at` (Timestamp): When the variable was last updated. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "List invitations" canonical: "https://admiral.io/docs/api/invitations/InvitationAPI_ListInvitations" --- # List invitations `GET https://api.admiral.io/v1/invitations` Scope: `user:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `email`: filter by address. - `status`: filter by lifecycle status. Example: `field['status'] = 'PENDING'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of invitations to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `invitations` (array of Invitation) - `id` (string): Unique identifier (UUID). Read-only. - `email` (string): The address the invitation was sent to. Read-only. - `role` (UserRole): The role the person holds once they join. ADMIN or MEMBER. One of `USER_ROLE_UNSPECIFIED`, `USER_ROLE_OWNER`, `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`, `USER_ROLE_APP_CREATOR`. Read-only. - `status` (InvitationStatus): InvitationStatus is where an invitation is in its life. One of `INVITATION_STATUS_UNSPECIFIED`, `INVITATION_STATUS_PENDING`, `INVITATION_STATUS_ACCEPTED`, `INVITATION_STATUS_EXPIRED`, `INVITATION_STATUS_REVOKED`. Read-only. - `invited_by` (string): The member who issued it (UUID). Absent when it was issued by an operator from outside the tenant. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `expires_at` (Timestamp): After this instant the link no longer works. Read-only. - `accepted_at` (Timestamp): When it was redeemed, and who it became. Both set together, only on ACCEPTED. Read-only. - `accepted_user_id` (string): Read-only. - `revoked_at` (Timestamp): When it was withdrawn or retired. Only on REVOKED. Read-only. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Invite someone into the current tenant" canonical: "https://admiral.io/docs/api/invitations/InvitationAPI_CreateInvitation" --- # Invite someone into the current tenant `POST https://api.admiral.io/v1/invitations` A live invitation for the same address is retired and replaced, so a retry or a "send it again" is this same call. ALREADY_EXISTS when the address is already a member. INVALID_ARGUMENT for a role that cannot be granted by invitation: OWNER moves by transfer, and APP_CREATOR is a capability rather than a role. Scope: `user:write` ### Request body - `email` (string (email), required): Where the mail goes, and the address the user will be created with. Length at most 254. - `role` (UserRole, required): The role to hold on joining. ADMIN or MEMBER. enum.defined_only = true One of `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`. ### Response 200 Success - `invitation` (Invitation): Invitation is one person invited into the caller's tenant. Never carries the link or its token. - `id` (string): Unique identifier (UUID). Read-only. - `email` (string): The address the invitation was sent to. Read-only. - `role` (UserRole): The role the person holds once they join. ADMIN or MEMBER. One of `USER_ROLE_UNSPECIFIED`, `USER_ROLE_OWNER`, `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`, `USER_ROLE_APP_CREATOR`. Read-only. - `status` (InvitationStatus): InvitationStatus is where an invitation is in its life. One of `INVITATION_STATUS_UNSPECIFIED`, `INVITATION_STATUS_PENDING`, `INVITATION_STATUS_ACCEPTED`, `INVITATION_STATUS_EXPIRED`, `INVITATION_STATUS_REVOKED`. Read-only. - `invited_by` (string): The member who issued it (UUID). Absent when it was issued by an operator from outside the tenant. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `expires_at` (Timestamp): After this instant the link no longer works. Read-only. - `accepted_at` (Timestamp): When it was redeemed, and who it became. Both set together, only on ACCEPTED. Read-only. - `accepted_user_id` (string): Read-only. - `revoked_at` (Timestamp): When it was withdrawn or retired. Only on REVOKED. Read-only. --- title: "Withdraw an invitation" canonical: "https://admiral.io/docs/api/invitations/InvitationAPI_RevokeInvitation" --- # Withdraw an invitation `POST https://api.admiral.io/v1/invitations/{invitation_id}/revoke` Scope: `user:write` ### Path parameters - `invitation_id` (string (uuid), required): The invitation (UUID), from CreateInvitation or ListInvitations. ### Response 200 Success - `invitation` (Invitation): Invitation is one person invited into the caller's tenant. Never carries the link or its token. - `id` (string): Unique identifier (UUID). Read-only. - `email` (string): The address the invitation was sent to. Read-only. - `role` (UserRole): The role the person holds once they join. ADMIN or MEMBER. One of `USER_ROLE_UNSPECIFIED`, `USER_ROLE_OWNER`, `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`, `USER_ROLE_APP_CREATOR`. Read-only. - `status` (InvitationStatus): InvitationStatus is where an invitation is in its life. One of `INVITATION_STATUS_UNSPECIFIED`, `INVITATION_STATUS_PENDING`, `INVITATION_STATUS_ACCEPTED`, `INVITATION_STATUS_EXPIRED`, `INVITATION_STATUS_REVOKED`. Read-only. - `invited_by` (string): The member who issued it (UUID). Absent when it was issued by an operator from outside the tenant. Read-only. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `expires_at` (Timestamp): After this instant the link no longer works. Read-only. - `accepted_at` (Timestamp): When it was redeemed, and who it became. Both set together, only on ACCEPTED. Read-only. - `accepted_user_id` (string): Read-only. - `revoked_at` (Timestamp): When it was withdrawn or retired. Only on REVOKED. Read-only. --- title: "List jobs" canonical: "https://admiral.io/docs/api/jobs/AgentAPI_ListJobs" --- # List jobs `GET https://api.admiral.io/v1/jobs` Scope: `agent:read` ### Query parameters - `agent_id` (string (uuid)): The agent_id query parameter. - `environment_id` (string (uuid)): The environment_id query parameter. - `status` (JobStatus): UNSPECIFIED lists every status. enum.defined_only = true One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `page_size` (integer (int32)): The page_size query parameter. Value 0 to 100. - `page_token` (string): The page_token query parameter. ### Response 200 Success - `jobs` (array of Job) - `id` (string) - `kind` (JobKind): One of `JOB_KIND_UNSPECIFIED`, `PROBE`, `PLAN`, `APPLY`. - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `agent_id` (string) - `environment_id` (string) - `change_set_id` (string): `cs-` id; empty for a PROBE. - `revision` (integer (int32)) - `artifact_digest` (string): `sha256:` of the run artifact the job runs. - `attempt` (integer (int32)) - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `result` (JobResult) - `status` (JobStatus): SUCCEEDED, FAILED or CANCELLED. One of `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `steps` (array of Step) - `component` (string) - `status` (JobStatus): enum.defined_only = true One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `plan` (PlanResult): Set by a PLAN. - `components` (array of ComponentPlan): Items at most 256. - `component` (string): Length at most 63. - `changes` (array of ResourceChange): Items at most 5000. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `action` (ResourceAction): enum.defined_only = true One of `NO_OP`, `CREATE`, `UPDATE`, `REPLACE`, `DESTROY`, `ORPHAN`. - `diff_digest` (string): `sha256:` of this resource's diff in the PlanDiff. Empty for NO_OP. Length at most 71. - `diff_digest` (string): `sha256:` of the PlanDiff uploaded for this attempt. Length at most 71. - `inventory` (array of ComponentInventory): Set by an APPLY: what each component it reached left in the cluster, including one that failed partway. - `component` (string) - `resources` (array of ResourceRef) - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `started_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `next_page_token` (string) --- title: "Retrieve a job" canonical: "https://admiral.io/docs/api/jobs/AgentAPI_GetJob" --- # Retrieve a job `GET https://api.admiral.io/v1/jobs/{job_id}` Scope: `agent:read` ### Path parameters - `job_id` (string (uuid), required): The job_id path parameter. ### Response 200 Success - `job` (Job) - `id` (string) - `kind` (JobKind): One of `JOB_KIND_UNSPECIFIED`, `PROBE`, `PLAN`, `APPLY`. - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `agent_id` (string) - `environment_id` (string) - `change_set_id` (string): `cs-` id; empty for a PROBE. - `revision` (integer (int32)) - `artifact_digest` (string): `sha256:` of the run artifact the job runs. - `attempt` (integer (int32)) - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `result` (JobResult) - `status` (JobStatus): SUCCEEDED, FAILED or CANCELLED. One of `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `steps` (array of Step) - `component` (string) - `status` (JobStatus): enum.defined_only = true One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `plan` (PlanResult): Set by a PLAN. - `components` (array of ComponentPlan): Items at most 256. - `component` (string): Length at most 63. - `changes` (array of ResourceChange): Items at most 5000. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `action` (ResourceAction): enum.defined_only = true One of `NO_OP`, `CREATE`, `UPDATE`, `REPLACE`, `DESTROY`, `ORPHAN`. - `diff_digest` (string): `sha256:` of this resource's diff in the PlanDiff. Empty for NO_OP. Length at most 71. - `diff_digest` (string): `sha256:` of the PlanDiff uploaded for this attempt. Length at most 71. - `inventory` (array of ComponentInventory): Set by an APPLY: what each component it reached left in the cluster, including one that failed partway. - `component` (string) - `resources` (array of ResourceRef) - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `started_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "Cancel a job" canonical: "https://admiral.io/docs/api/jobs/AgentAPI_CancelJob" --- # Cancel a job `POST https://api.admiral.io/v1/jobs/{job_id}/cancel` Scope: `agent:write` ### Path parameters - `job_id` (string (uuid), required): The job_id path parameter. ### Response 200 Success - `job` (Job) - `id` (string) - `kind` (JobKind): One of `JOB_KIND_UNSPECIFIED`, `PROBE`, `PLAN`, `APPLY`. - `status` (JobStatus): One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `agent_id` (string) - `environment_id` (string) - `change_set_id` (string): `cs-` id; empty for a PROBE. - `revision` (integer (int32)) - `artifact_digest` (string): `sha256:` of the run artifact the job runs. - `attempt` (integer (int32)) - `wait_reason` (WaitReason): Set while QUEUED. One of `WAIT_REASON_UNSPECIFIED`, `NO_AGENT_SELECTED`, `AGENT_NOT_GRANTED`, `AGENT_OFFLINE`, `AGENT_AT_CAPACITY`, `AGENT_TOO_OLD`, `ENVIRONMENT_BUSY`, `BACKOFF`, `CLUSTER_PENDING`. - `result` (JobResult) - `status` (JobStatus): SUCCEEDED, FAILED or CANCELLED. One of `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `steps` (array of Step) - `component` (string) - `status` (JobStatus): enum.defined_only = true One of `JOB_STATUS_UNSPECIFIED`, `QUEUED`, `OFFERED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. - `message` (string) - `plan` (PlanResult): Set by a PLAN. - `components` (array of ComponentPlan): Items at most 256. - `component` (string): Length at most 63. - `changes` (array of ResourceChange): Items at most 5000. - `resource` (ResourceRef): ResourceRef names one Kubernetes object. - `action` (ResourceAction): enum.defined_only = true One of `NO_OP`, `CREATE`, `UPDATE`, `REPLACE`, `DESTROY`, `ORPHAN`. - `diff_digest` (string): `sha256:` of this resource's diff in the PlanDiff. Empty for NO_OP. Length at most 71. - `diff_digest` (string): `sha256:` of the PlanDiff uploaded for this attempt. Length at most 71. - `inventory` (array of ComponentInventory): Set by an APPLY: what each component it reached left in the cluster, including one that failed partway. - `component` (string) - `resources` (array of ResourceRef) - `api_version` (string): Length at most 253. - `kind` (string): Length at most 63. - `namespace` (string): Empty for a cluster-scoped object. Length at most 63. - `name` (string): Length at most 253. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `started_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. - `finished_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. --- title: "List runs" canonical: "https://admiral.io/docs/api/runs/RunAPI_ListRuns" --- # List runs `GET https://api.admiral.io/v1/runs` Common filter fields: `application_id`, `environment_id`, `status`. Use to view run history for an environment. Scope: `run:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `application_id`: runs for a specific application (UUID). - `environment_id`: runs to a specific environment (UUID). - `status`: filter by run status (PENDING, PLANNING, APPLYING, SUCCEEDED, ...). - `change_set_id`: runs for a specific change set (UUID). Example: `field['environment_id'] = '' AND field['status'] = 'SUCCEEDED'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of runs to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `runs` (array of Run): The list of runs, ordered from newest to oldest. - `id` (string (uuid)): Unique identifier for the run (UUID). - `application_id` (string (uuid)): The application being deployed (UUID). - `environment_id` (string (uuid)): The target environment (UUID). - `status` (RunStatus): Composite status derived from all component revisions. One of `RUN_STATUS_UNSPECIFIED`, `RUN_STATUS_PENDING`, `RUN_STATUS_QUEUED`, `RUN_STATUS_PLANNING`, `RUN_STATUS_PLANNED`, `RUN_STATUS_APPLYING`, `RUN_STATUS_SUCCEEDED`, `RUN_STATUS_PARTIALLY_FAILED`, `RUN_STATUS_FAILED`, `RUN_STATUS_CANCELED`, `RUN_STATUS_SUPERSEDED`, `RUN_STATUS_STALE`, `RUN_STATUS_AWAITING_APPROVAL`. - `triggered_by` (ActorRef): The user or agent that triggered the run (server-populated from token). - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `message` (string): Optional message describing the run (e.g., "Deploying v2.1.0 with new caching layer" or "Rolling back to stable after API errors"). Length at most 1024. - `source_run_id` (string): If this run was created as a rollback from a prior run, this field contains the source run's UUID. Empty for normal runs. - `change_set_id` (string): The changeset that was deployed (UUID). Absent for pre-changeset runs and reconcile (no-changeset) runs. - `revision_summary` (RevisionSummary): Summary counts for quick status display. - `total` (integer (int32)): Total number of component revisions in this run. - `succeeded` (integer (int32)): Number of revisions that completed successfully. - `failed` (integer (int32)): Number of revisions that failed. - `blocked` (integer (int32)): Number of revisions that are blocked by upstream failures. - `running` (integer (int32)): Number of revisions currently running (planning or applying). - `canceled` (integer (int32)): Number of revisions that were canceled. - `pending` (integer (int32)): Number of revisions that have not started yet. - `completed_at` (Timestamp): When the run finished (all revisions completed, failed, or canceled). Absent while the run is in progress. - `display_id` (string): Typed display identifier of the form `run-<12-char-suffix>` (e.g., `run-3k7m9p2q4rvw`). Server-generated, indexed, and stable. Prefer this over `id` for user-facing references; lookups accept either form. - `application_name` (string): Display name of the parent application. Denormalized for display. Read-only; ignored on writes. - `environment_name` (string): Display name of the parent environment. Denormalized for display. Read-only; ignored on writes. - `change_set_display_id` (string): Display ID of the changeset this run deployed (`cs-`). Denormalized for display. Empty when `change_set_id` is empty (pre-changeset runs, reconcile runs). Read-only. - `change_set_title` (string): Title of the changeset this run deployed. Denormalized for display. Empty when `change_set_id` is empty. Read-only. - `created_at` (Timestamp): When the run was created. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Create a run" canonical: "https://admiral.io/docs/api/runs/RunAPI_CreateRun" --- # Create a run `POST https://api.admiral.io/v1/runs` The server resolves all components (with environment overrides applied), builds the dependency DAG, and begins rendering and executing revisions. Concurrency: only one run can be active per application+environment at a time. If a run is already in an active state (PENDING, QUEUED, PLANNING, PLANNED, or APPLYING), the new run is queued and will start automatically when the current run completes or is canceled. Scope: `run:write` ### Request body - `application_id` (string (uuid), required): The application to run (UUID). - `environment_id` (string (uuid), required): The target environment (UUID). - `message` (string): Optional message describing this run. Length at most 1024. - `source_run_id` (string): Optional: run from a prior run's configuration snapshots instead of from the current component HEAD. When set, each revision is seeded from the source run's revision for the same component (catalog_item_id, version, resolved_values, source_id, working_directory). This is the rollback mechanism: re-plan and re-apply a known-good configuration against the current infrastructure state. - `change_set_id` (string): Optional: run the entries and variable changes captured in a change set. When set, the component set and variable overlay are sourced from the change set instead of the application's full component list. The change set must be OPEN and target the same (application, environment). ### Response 200 Success - `run` (Run): The created run. Status will be PENDING initially. - `id` (string (uuid)): Unique identifier for the run (UUID). - `application_id` (string (uuid)): The application being deployed (UUID). - `environment_id` (string (uuid)): The target environment (UUID). - `status` (RunStatus): Composite status derived from all component revisions. One of `RUN_STATUS_UNSPECIFIED`, `RUN_STATUS_PENDING`, `RUN_STATUS_QUEUED`, `RUN_STATUS_PLANNING`, `RUN_STATUS_PLANNED`, `RUN_STATUS_APPLYING`, `RUN_STATUS_SUCCEEDED`, `RUN_STATUS_PARTIALLY_FAILED`, `RUN_STATUS_FAILED`, `RUN_STATUS_CANCELED`, `RUN_STATUS_SUPERSEDED`, `RUN_STATUS_STALE`, `RUN_STATUS_AWAITING_APPROVAL`. - `triggered_by` (ActorRef): The user or agent that triggered the run (server-populated from token). - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `message` (string): Optional message describing the run (e.g., "Deploying v2.1.0 with new caching layer" or "Rolling back to stable after API errors"). Length at most 1024. - `source_run_id` (string): If this run was created as a rollback from a prior run, this field contains the source run's UUID. Empty for normal runs. - `change_set_id` (string): The changeset that was deployed (UUID). Absent for pre-changeset runs and reconcile (no-changeset) runs. - `revision_summary` (RevisionSummary): Summary counts for quick status display. - `total` (integer (int32)): Total number of component revisions in this run. - `succeeded` (integer (int32)): Number of revisions that completed successfully. - `failed` (integer (int32)): Number of revisions that failed. - `blocked` (integer (int32)): Number of revisions that are blocked by upstream failures. - `running` (integer (int32)): Number of revisions currently running (planning or applying). - `canceled` (integer (int32)): Number of revisions that were canceled. - `pending` (integer (int32)): Number of revisions that have not started yet. - `completed_at` (Timestamp): When the run finished (all revisions completed, failed, or canceled). Absent while the run is in progress. - `display_id` (string): Typed display identifier of the form `run-<12-char-suffix>` (e.g., `run-3k7m9p2q4rvw`). Server-generated, indexed, and stable. Prefer this over `id` for user-facing references; lookups accept either form. - `application_name` (string): Display name of the parent application. Denormalized for display. Read-only; ignored on writes. - `environment_name` (string): Display name of the parent environment. Denormalized for display. Read-only; ignored on writes. - `change_set_display_id` (string): Display ID of the changeset this run deployed (`cs-`). Denormalized for display. Empty when `change_set_id` is empty (pre-changeset runs, reconcile runs). Read-only. - `change_set_title` (string): Title of the changeset this run deployed. Denormalized for display. Empty when `change_set_id` is empty. Read-only. - `created_at` (Timestamp): When the run was created. --- title: "Retrieve a run" canonical: "https://admiral.io/docs/api/runs/RunAPI_GetRun" --- # Retrieve a run `GET https://api.admiral.io/v1/runs/{run_id}` Scope: `run:read` ### Path parameters - `run_id` (string, required): Identifier of the run. Either a UUID or a `run-` display ID. Length at least 1. ### Response 200 Success - `run` (Run): The run record with current status. - `id` (string (uuid)): Unique identifier for the run (UUID). - `application_id` (string (uuid)): The application being deployed (UUID). - `environment_id` (string (uuid)): The target environment (UUID). - `status` (RunStatus): Composite status derived from all component revisions. One of `RUN_STATUS_UNSPECIFIED`, `RUN_STATUS_PENDING`, `RUN_STATUS_QUEUED`, `RUN_STATUS_PLANNING`, `RUN_STATUS_PLANNED`, `RUN_STATUS_APPLYING`, `RUN_STATUS_SUCCEEDED`, `RUN_STATUS_PARTIALLY_FAILED`, `RUN_STATUS_FAILED`, `RUN_STATUS_CANCELED`, `RUN_STATUS_SUPERSEDED`, `RUN_STATUS_STALE`, `RUN_STATUS_AWAITING_APPROVAL`. - `triggered_by` (ActorRef): The user or agent that triggered the run (server-populated from token). - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `message` (string): Optional message describing the run (e.g., "Deploying v2.1.0 with new caching layer" or "Rolling back to stable after API errors"). Length at most 1024. - `source_run_id` (string): If this run was created as a rollback from a prior run, this field contains the source run's UUID. Empty for normal runs. - `change_set_id` (string): The changeset that was deployed (UUID). Absent for pre-changeset runs and reconcile (no-changeset) runs. - `revision_summary` (RevisionSummary): Summary counts for quick status display. - `total` (integer (int32)): Total number of component revisions in this run. - `succeeded` (integer (int32)): Number of revisions that completed successfully. - `failed` (integer (int32)): Number of revisions that failed. - `blocked` (integer (int32)): Number of revisions that are blocked by upstream failures. - `running` (integer (int32)): Number of revisions currently running (planning or applying). - `canceled` (integer (int32)): Number of revisions that were canceled. - `pending` (integer (int32)): Number of revisions that have not started yet. - `completed_at` (Timestamp): When the run finished (all revisions completed, failed, or canceled). Absent while the run is in progress. - `display_id` (string): Typed display identifier of the form `run-<12-char-suffix>` (e.g., `run-3k7m9p2q4rvw`). Server-generated, indexed, and stable. Prefer this over `id` for user-facing references; lookups accept either form. - `application_name` (string): Display name of the parent application. Denormalized for display. Read-only; ignored on writes. - `environment_name` (string): Display name of the parent environment. Denormalized for display. Read-only; ignored on writes. - `change_set_display_id` (string): Display ID of the changeset this run deployed (`cs-`). Denormalized for display. Empty when `change_set_id` is empty (pre-changeset runs, reconcile runs). Read-only. - `change_set_title` (string): Title of the changeset this run deployed. Denormalized for display. Empty when `change_set_id` is empty. Read-only. - `created_at` (Timestamp): When the run was created. --- title: "Apply a planned run" canonical: "https://admiral.io/docs/api/runs/RunAPI_ApplyRun" --- # Apply a planned run `POST https://api.admiral.io/v1/runs/{run_id}/apply` Scope: `run:write` ### Path parameters - `run_id` (string, required): Identifier of the run to apply. UUID or `run-` display ID. Length at least 1. ### Request body - `message` (string): Optional message describing the apply (e.g., "Approved by @martin"). Length at most 1024. ### Response 200 Success - `run` (Run): The run with status advanced to APPLYING. Revisions that were PLANNED are now APPLYING. - `id` (string (uuid)): Unique identifier for the run (UUID). - `application_id` (string (uuid)): The application being deployed (UUID). - `environment_id` (string (uuid)): The target environment (UUID). - `status` (RunStatus): Composite status derived from all component revisions. One of `RUN_STATUS_UNSPECIFIED`, `RUN_STATUS_PENDING`, `RUN_STATUS_QUEUED`, `RUN_STATUS_PLANNING`, `RUN_STATUS_PLANNED`, `RUN_STATUS_APPLYING`, `RUN_STATUS_SUCCEEDED`, `RUN_STATUS_PARTIALLY_FAILED`, `RUN_STATUS_FAILED`, `RUN_STATUS_CANCELED`, `RUN_STATUS_SUPERSEDED`, `RUN_STATUS_STALE`, `RUN_STATUS_AWAITING_APPROVAL`. - `triggered_by` (ActorRef): The user or agent that triggered the run (server-populated from token). - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `message` (string): Optional message describing the run (e.g., "Deploying v2.1.0 with new caching layer" or "Rolling back to stable after API errors"). Length at most 1024. - `source_run_id` (string): If this run was created as a rollback from a prior run, this field contains the source run's UUID. Empty for normal runs. - `change_set_id` (string): The changeset that was deployed (UUID). Absent for pre-changeset runs and reconcile (no-changeset) runs. - `revision_summary` (RevisionSummary): Summary counts for quick status display. - `total` (integer (int32)): Total number of component revisions in this run. - `succeeded` (integer (int32)): Number of revisions that completed successfully. - `failed` (integer (int32)): Number of revisions that failed. - `blocked` (integer (int32)): Number of revisions that are blocked by upstream failures. - `running` (integer (int32)): Number of revisions currently running (planning or applying). - `canceled` (integer (int32)): Number of revisions that were canceled. - `pending` (integer (int32)): Number of revisions that have not started yet. - `completed_at` (Timestamp): When the run finished (all revisions completed, failed, or canceled). Absent while the run is in progress. - `display_id` (string): Typed display identifier of the form `run-<12-char-suffix>` (e.g., `run-3k7m9p2q4rvw`). Server-generated, indexed, and stable. Prefer this over `id` for user-facing references; lookups accept either form. - `application_name` (string): Display name of the parent application. Denormalized for display. Read-only; ignored on writes. - `environment_name` (string): Display name of the parent environment. Denormalized for display. Read-only; ignored on writes. - `change_set_display_id` (string): Display ID of the changeset this run deployed (`cs-`). Denormalized for display. Empty when `change_set_id` is empty (pre-changeset runs, reconcile runs). Read-only. - `change_set_title` (string): Title of the changeset this run deployed. Denormalized for display. Empty when `change_set_id` is empty. Read-only. - `created_at` (Timestamp): When the run was created. --- title: "Cancel a run" canonical: "https://admiral.io/docs/api/runs/RunAPI_CancelRun" --- # Cancel a run `POST https://api.admiral.io/v1/runs/{run_id}/cancel` Scope: `run:write` ### Path parameters - `run_id` (string, required): Identifier of the run to cancel. UUID or `run-` display ID. Length at least 1. ### Request body - `reason` (string): Optional reason for cancellation. Length at most 1024. ### Response 200 Success - `run` (Run): The canceled run. - `id` (string (uuid)): Unique identifier for the run (UUID). - `application_id` (string (uuid)): The application being deployed (UUID). - `environment_id` (string (uuid)): The target environment (UUID). - `status` (RunStatus): Composite status derived from all component revisions. One of `RUN_STATUS_UNSPECIFIED`, `RUN_STATUS_PENDING`, `RUN_STATUS_QUEUED`, `RUN_STATUS_PLANNING`, `RUN_STATUS_PLANNED`, `RUN_STATUS_APPLYING`, `RUN_STATUS_SUCCEEDED`, `RUN_STATUS_PARTIALLY_FAILED`, `RUN_STATUS_FAILED`, `RUN_STATUS_CANCELED`, `RUN_STATUS_SUPERSEDED`, `RUN_STATUS_STALE`, `RUN_STATUS_AWAITING_APPROVAL`. - `triggered_by` (ActorRef): The user or agent that triggered the run (server-populated from token). - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `message` (string): Optional message describing the run (e.g., "Deploying v2.1.0 with new caching layer" or "Rolling back to stable after API errors"). Length at most 1024. - `source_run_id` (string): If this run was created as a rollback from a prior run, this field contains the source run's UUID. Empty for normal runs. - `change_set_id` (string): The changeset that was deployed (UUID). Absent for pre-changeset runs and reconcile (no-changeset) runs. - `revision_summary` (RevisionSummary): Summary counts for quick status display. - `total` (integer (int32)): Total number of component revisions in this run. - `succeeded` (integer (int32)): Number of revisions that completed successfully. - `failed` (integer (int32)): Number of revisions that failed. - `blocked` (integer (int32)): Number of revisions that are blocked by upstream failures. - `running` (integer (int32)): Number of revisions currently running (planning or applying). - `canceled` (integer (int32)): Number of revisions that were canceled. - `pending` (integer (int32)): Number of revisions that have not started yet. - `completed_at` (Timestamp): When the run finished (all revisions completed, failed, or canceled). Absent while the run is in progress. - `display_id` (string): Typed display identifier of the form `run-<12-char-suffix>` (e.g., `run-3k7m9p2q4rvw`). Server-generated, indexed, and stable. Prefer this over `id` for user-facing references; lookups accept either form. - `application_name` (string): Display name of the parent application. Denormalized for display. Read-only; ignored on writes. - `environment_name` (string): Display name of the parent environment. Denormalized for display. Read-only; ignored on writes. - `change_set_display_id` (string): Display ID of the changeset this run deployed (`cs-`). Denormalized for display. Empty when `change_set_id` is empty (pre-changeset runs, reconcile runs). Read-only. - `change_set_title` (string): Title of the changeset this run deployed. Denormalized for display. Empty when `change_set_id` is empty. Read-only. - `created_at` (Timestamp): When the run was created. --- title: "List revisions" canonical: "https://admiral.io/docs/api/runs/RunAPI_ListRevisions" --- # List revisions `GET https://api.admiral.io/v1/runs/{run_id}/revisions` Scope: `run:read` ### Path parameters - `run_id` (string, required): Identifier of the run. UUID or `run-` display ID. Length at least 1. ### Query parameters - `page_size` (integer (int32)): Maximum number of revisions to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `revisions` (array of Revision): The list of revisions, ordered by dependency graph (upstream first). - `id` (string (uuid)): Unique identifier for the revision (UUID). - `run_id` (string (uuid)): The run this revision belongs to (UUID). - `component_id` (string (uuid)): The component this revision is for (UUID). - `component_name` (string): Component name at the time of run (immutable semantic key). - `kind` (RevisionKind): Component kind at the time of run (after override resolution). One of `REVISION_KIND_UNSPECIFIED`, `REVISION_KIND_INFRASTRUCTURE`, `REVISION_KIND_WORKLOAD`. - `status` (RevisionStatus): Lifecycle status of this revision. One of `REVISION_STATUS_UNSPECIFIED`, `REVISION_STATUS_PENDING`, `REVISION_STATUS_QUEUED`, `REVISION_STATUS_PLANNING`, `REVISION_STATUS_PLANNED`, `REVISION_STATUS_APPLYING`, `REVISION_STATUS_SUCCEEDED`, `REVISION_STATUS_FAILED`, `REVISION_STATUS_BLOCKED`, `REVISION_STATUS_CANCELED`, `REVISION_STATUS_SUPERSEDED`, `REVISION_STATUS_DEFERRED`, `REVISION_STATUS_STALE`, `REVISION_STATUS_AWAITING_APPROVAL`. - `change_type` (RevisionChangeType): What type of change this revision represents relative to the previously deployed state. One of `REVISION_CHANGE_TYPE_UNSPECIFIED`, `REVISION_CHANGE_TYPE_CREATE`, `REVISION_CHANGE_TYPE_UPDATE`, `REVISION_CHANGE_TYPE_DESTROY`, `REVISION_CHANGE_TYPE_RECREATE`, `REVISION_CHANGE_TYPE_IMPORT`, `REVISION_CHANGE_TYPE_NO_CHANGE`. - `previous_revision_id` (string): The last succeeded revision for this (component, environment) at the time this revision was created. Null for CREATE revisions. - `source_id` (string): The source the module pointed to at the time of this revision (UUID). Snapshotted so a rollback can re-fetch from the original source even if the module's source binding is later edited. Execution today resolves fetch location through the live module; this field is the audit anchor. - `ref` (string): The git ref / version selector deployed (the component's ref at snapshot). - `resolved_values` (string): The resolved values template snapshot: the values_template with all variable references and component output references fully resolved. Stored for audit: shows exactly what inputs were used. Sensitive variable values are masked in API responses. - `depends_on` (array of string): Component IDs that this revision depends on. Populated from the resolved depends_on list plus implicit dependencies from template expressions. - `blocked_by` (array of string): Component IDs that are blocking this revision. Only populated when status is BLOCKED; indicates which upstream components failed. - `plan_summary` (ChangeSummary): The normalized change counts (creates/updates/deletes/noops) this revision's plan computed. Populated after planning. Engine-agnostic. - `creates` (integer (int32)): Number of resources to be created. - `updates` (integer (int32)): Number of resources to be updated in place. - `deletes` (integer (int32)): Number of resources to be deleted. - `noops` (integer (int32)): Number of resources left unchanged (no-op). - `available_phases` (array of RevisionPhase): Phase labels for which a transcript has been stored, in the order they ran. Populated as each phase completes (a revision that planned and then applied carries `[REVISION_PHASE_PLAN, REVISION_PHASE_APPLY]`). Fetch a phase's transcript via `GET /api/v1/runs/{run_id}/revisions/{revision_id}/{phase}`. - `error_message` (string): Error message if the revision failed. Empty on success. - `retry_count` (integer (int32)): Number of retry attempts. Starts at 0 for the initial attempt. - `started_at` (Timestamp): When the revision started execution (transitioned from PENDING/QUEUED). - `completed_at` (Timestamp): When the revision finished (succeeded, failed, or canceled). - `working_directory` (string): Subdirectory within the delivered archive where the executor runs. Empty means the archive root. Populated from the catalog item's path field at snapshot time so that relative references resolve correctly. - `created_at` (Timestamp): When the revision was created (same as run created_at). - `resolved_commit` (string): The concrete commit this revision resolved its ref to and pinned -- the reproducibility anchor. `ref` is the intent (e.g. `main`); this is what actually deployed. Populated when resolution is wired (a later WP). - `type` (string): The deploy/engine type this revision runs (TERRAFORM/HELM/KUSTOMIZE/ MANIFEST), denormalized from the component at snapshot. Selects the executor: the orchestration layer routes by this type, not by kind. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Retrieve a revision" canonical: "https://admiral.io/docs/api/runs/RunAPI_GetRevision" --- # Retrieve a revision `GET https://api.admiral.io/v1/runs/{run_id}/revisions/{revision_id}` Scope: `run:read` ### Path parameters - `run_id` (string, required): The run. UUID or `run-` display ID. Length at least 1. - `revision_id` (string (uuid), required): The revision (UUID). ### Response 200 Success - `revision` (Revision): The revision record with current status and artifacts. - `id` (string (uuid)): Unique identifier for the revision (UUID). - `run_id` (string (uuid)): The run this revision belongs to (UUID). - `component_id` (string (uuid)): The component this revision is for (UUID). - `component_name` (string): Component name at the time of run (immutable semantic key). - `kind` (RevisionKind): Component kind at the time of run (after override resolution). One of `REVISION_KIND_UNSPECIFIED`, `REVISION_KIND_INFRASTRUCTURE`, `REVISION_KIND_WORKLOAD`. - `status` (RevisionStatus): Lifecycle status of this revision. One of `REVISION_STATUS_UNSPECIFIED`, `REVISION_STATUS_PENDING`, `REVISION_STATUS_QUEUED`, `REVISION_STATUS_PLANNING`, `REVISION_STATUS_PLANNED`, `REVISION_STATUS_APPLYING`, `REVISION_STATUS_SUCCEEDED`, `REVISION_STATUS_FAILED`, `REVISION_STATUS_BLOCKED`, `REVISION_STATUS_CANCELED`, `REVISION_STATUS_SUPERSEDED`, `REVISION_STATUS_DEFERRED`, `REVISION_STATUS_STALE`, `REVISION_STATUS_AWAITING_APPROVAL`. - `change_type` (RevisionChangeType): What type of change this revision represents relative to the previously deployed state. One of `REVISION_CHANGE_TYPE_UNSPECIFIED`, `REVISION_CHANGE_TYPE_CREATE`, `REVISION_CHANGE_TYPE_UPDATE`, `REVISION_CHANGE_TYPE_DESTROY`, `REVISION_CHANGE_TYPE_RECREATE`, `REVISION_CHANGE_TYPE_IMPORT`, `REVISION_CHANGE_TYPE_NO_CHANGE`. - `previous_revision_id` (string): The last succeeded revision for this (component, environment) at the time this revision was created. Null for CREATE revisions. - `source_id` (string): The source the module pointed to at the time of this revision (UUID). Snapshotted so a rollback can re-fetch from the original source even if the module's source binding is later edited. Execution today resolves fetch location through the live module; this field is the audit anchor. - `ref` (string): The git ref / version selector deployed (the component's ref at snapshot). - `resolved_values` (string): The resolved values template snapshot: the values_template with all variable references and component output references fully resolved. Stored for audit: shows exactly what inputs were used. Sensitive variable values are masked in API responses. - `depends_on` (array of string): Component IDs that this revision depends on. Populated from the resolved depends_on list plus implicit dependencies from template expressions. - `blocked_by` (array of string): Component IDs that are blocking this revision. Only populated when status is BLOCKED; indicates which upstream components failed. - `plan_summary` (ChangeSummary): The normalized change counts (creates/updates/deletes/noops) this revision's plan computed. Populated after planning. Engine-agnostic. - `creates` (integer (int32)): Number of resources to be created. - `updates` (integer (int32)): Number of resources to be updated in place. - `deletes` (integer (int32)): Number of resources to be deleted. - `noops` (integer (int32)): Number of resources left unchanged (no-op). - `available_phases` (array of RevisionPhase): Phase labels for which a transcript has been stored, in the order they ran. Populated as each phase completes (a revision that planned and then applied carries `[REVISION_PHASE_PLAN, REVISION_PHASE_APPLY]`). Fetch a phase's transcript via `GET /api/v1/runs/{run_id}/revisions/{revision_id}/{phase}`. - `error_message` (string): Error message if the revision failed. Empty on success. - `retry_count` (integer (int32)): Number of retry attempts. Starts at 0 for the initial attempt. - `started_at` (Timestamp): When the revision started execution (transitioned from PENDING/QUEUED). - `completed_at` (Timestamp): When the revision finished (succeeded, failed, or canceled). - `working_directory` (string): Subdirectory within the delivered archive where the executor runs. Empty means the archive root. Populated from the catalog item's path field at snapshot time so that relative references resolve correctly. - `created_at` (Timestamp): When the revision was created (same as run created_at). - `resolved_commit` (string): The concrete commit this revision resolved its ref to and pinned -- the reproducibility anchor. `ref` is the intent (e.g. `main`); this is what actually deployed. Populated when resolution is wired (a later WP). - `type` (string): The deploy/engine type this revision runs (TERRAFORM/HELM/KUSTOMIZE/ MANIFEST), denormalized from the component at snapshot. Selects the executor: the orchestration layer routes by this type, not by kind. --- title: "Retry a revision" canonical: "https://admiral.io/docs/api/runs/RunAPI_RetryRevision" --- # Retry a revision `POST https://api.admiral.io/v1/runs/{run_id}/revisions/{revision_id}/retry` Scope: `run:write` ### Path parameters - `run_id` (string, required): The run. UUID or `run-` display ID. Length at least 1. - `revision_id` (string (uuid), required): The revision to retry (UUID). Must be in FAILED status. ### Response 200 Success - `revision` (Revision): The retried revision. Status resets and retry_count is incremented. Downstream revisions that were BLOCKED will automatically unblock if this revision succeeds. - `id` (string (uuid)): Unique identifier for the revision (UUID). - `run_id` (string (uuid)): The run this revision belongs to (UUID). - `component_id` (string (uuid)): The component this revision is for (UUID). - `component_name` (string): Component name at the time of run (immutable semantic key). - `kind` (RevisionKind): Component kind at the time of run (after override resolution). One of `REVISION_KIND_UNSPECIFIED`, `REVISION_KIND_INFRASTRUCTURE`, `REVISION_KIND_WORKLOAD`. - `status` (RevisionStatus): Lifecycle status of this revision. One of `REVISION_STATUS_UNSPECIFIED`, `REVISION_STATUS_PENDING`, `REVISION_STATUS_QUEUED`, `REVISION_STATUS_PLANNING`, `REVISION_STATUS_PLANNED`, `REVISION_STATUS_APPLYING`, `REVISION_STATUS_SUCCEEDED`, `REVISION_STATUS_FAILED`, `REVISION_STATUS_BLOCKED`, `REVISION_STATUS_CANCELED`, `REVISION_STATUS_SUPERSEDED`, `REVISION_STATUS_DEFERRED`, `REVISION_STATUS_STALE`, `REVISION_STATUS_AWAITING_APPROVAL`. - `change_type` (RevisionChangeType): What type of change this revision represents relative to the previously deployed state. One of `REVISION_CHANGE_TYPE_UNSPECIFIED`, `REVISION_CHANGE_TYPE_CREATE`, `REVISION_CHANGE_TYPE_UPDATE`, `REVISION_CHANGE_TYPE_DESTROY`, `REVISION_CHANGE_TYPE_RECREATE`, `REVISION_CHANGE_TYPE_IMPORT`, `REVISION_CHANGE_TYPE_NO_CHANGE`. - `previous_revision_id` (string): The last succeeded revision for this (component, environment) at the time this revision was created. Null for CREATE revisions. - `source_id` (string): The source the module pointed to at the time of this revision (UUID). Snapshotted so a rollback can re-fetch from the original source even if the module's source binding is later edited. Execution today resolves fetch location through the live module; this field is the audit anchor. - `ref` (string): The git ref / version selector deployed (the component's ref at snapshot). - `resolved_values` (string): The resolved values template snapshot: the values_template with all variable references and component output references fully resolved. Stored for audit: shows exactly what inputs were used. Sensitive variable values are masked in API responses. - `depends_on` (array of string): Component IDs that this revision depends on. Populated from the resolved depends_on list plus implicit dependencies from template expressions. - `blocked_by` (array of string): Component IDs that are blocking this revision. Only populated when status is BLOCKED; indicates which upstream components failed. - `plan_summary` (ChangeSummary): The normalized change counts (creates/updates/deletes/noops) this revision's plan computed. Populated after planning. Engine-agnostic. - `creates` (integer (int32)): Number of resources to be created. - `updates` (integer (int32)): Number of resources to be updated in place. - `deletes` (integer (int32)): Number of resources to be deleted. - `noops` (integer (int32)): Number of resources left unchanged (no-op). - `available_phases` (array of RevisionPhase): Phase labels for which a transcript has been stored, in the order they ran. Populated as each phase completes (a revision that planned and then applied carries `[REVISION_PHASE_PLAN, REVISION_PHASE_APPLY]`). Fetch a phase's transcript via `GET /api/v1/runs/{run_id}/revisions/{revision_id}/{phase}`. - `error_message` (string): Error message if the revision failed. Empty on success. - `retry_count` (integer (int32)): Number of retry attempts. Starts at 0 for the initial attempt. - `started_at` (Timestamp): When the revision started execution (transitioned from PENDING/QUEUED). - `completed_at` (Timestamp): When the revision finished (succeeded, failed, or canceled). - `working_directory` (string): Subdirectory within the delivered archive where the executor runs. Empty means the archive root. Populated from the catalog item's path field at snapshot time so that relative references resolve correctly. - `created_at` (Timestamp): When the revision was created (same as run created_at). - `resolved_commit` (string): The concrete commit this revision resolved its ref to and pinned -- the reproducibility anchor. `ref` is the intent (e.g. `main`); this is what actually deployed. Populated when resolution is wired (a later WP). - `type` (string): The deploy/engine type this revision runs (TERRAFORM/HELM/KUSTOMIZE/ MANIFEST), denormalized from the component at snapshot. Selects the executor: the orchestration layer routes by this type, not by kind. --- title: "Get the current tenant" canonical: "https://admiral.io/docs/api/tenant/TenantAPI_GetTenant" --- # Get the current tenant `GET https://api.admiral.io/v1/tenant` Scope: `tenant:read` ### Response 200 Success - `tenant` (Tenant): Tenant is the account as its own members see it: its identity, its lifecycle state, and the settings they control. Operational detail about how the account is run is not part of this view. - `id` (string): Unique identifier (UUID). Read-only. - `slug` (string): URL-safe identifier, unique across Admiral. Fixed at creation. Read-only. - `display_name` (string): Human-readable name. Length at most 256. - `status` (TenantStatus): Lifecycle state. One of `TENANT_STATUS_UNSPECIFIED`, `TENANT_STATUS_PENDING`, `TENANT_STATUS_ACTIVE`, `TENANT_STATUS_SUSPENDED`. Read-only. - `labels` (map of string to string): Free-form labels for the customer's own use. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Update the current tenant" canonical: "https://admiral.io/docs/api/tenant/TenantAPI_UpdateTenant" --- # Update the current tenant `PATCH https://api.admiral.io/v1/tenant` Only `display_name` and `labels` are mutable. `slug` is part of the account's identity and `status` is set by lifecycle operations, neither of which a tenant performs on itself. Scope: `tenant:write` ### Request body - `display_name` (string): New display name. Omit to leave unchanged. Length at most 256. - `labels` (map of string to string): Replaces all labels when present. Omit to leave unchanged. - `update_mask` (FieldMask): Which fields to apply. Present for forward compatibility as the mutable surface grows. ### Response 200 Success - `tenant` (Tenant): Tenant is the account as its own members see it: its identity, its lifecycle state, and the settings they control. Operational detail about how the account is run is not part of this view. - `id` (string): Unique identifier (UUID). Read-only. - `slug` (string): URL-safe identifier, unique across Admiral. Fixed at creation. Read-only. - `display_name` (string): Human-readable name. Length at most 256. - `status` (TenantStatus): Lifecycle state. One of `TENANT_STATUS_UNSPECIFIED`, `TENANT_STATUS_PENDING`, `TENANT_STATUS_ACTIVE`, `TENANT_STATUS_SUSPENDED`. Read-only. - `labels` (map of string to string): Free-form labels for the customer's own use. - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. --- title: "Retrieve current user profile" canonical: "https://admiral.io/docs/api/user/UserAPI_GetMe" --- # Retrieve current user profile `GET https://api.admiral.io/v1/user/me` Scope: any authenticated key (no specific scope required). ### Response 200 Success - `user` (User): The user profile. - `id` (string (uuid)): Unique identifier for the user (UUID). - `email` (string): User's email address. - `email_verified` (boolean): Whether the email has been verified by the IdP. - `display_name` (string): User's display name for UI purposes. - `given_name` (string): User's given (first) name. - `family_name` (string): User's family (last) name. - `avatar_url` (string): URL to the user's avatar image. - `created_at` (Timestamp): When the user was created. - `updated_at` (Timestamp): When the user was last updated. - `role` (UserRole): The user's standing in the tenant. One of `USER_ROLE_UNSPECIFIED`, `USER_ROLE_OWNER`, `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`, `USER_ROLE_APP_CREATOR`. Read-only. - `status` (UserStatus): Whether the user can currently sign in. One of `USER_STATUS_UNSPECIFIED`, `USER_STATUS_ACTIVE`, `USER_STATUS_SUSPENDED`. Read-only. --- title: "List personal access tokens" canonical: "https://admiral.io/docs/api/user/UserAPI_ListApiKeys" --- # List personal access tokens `GET https://api.admiral.io/v1/user/tokens` Scope: `token:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `name`: filter by key name. - `status`: filter by key status (ACTIVE, REVOKED). Example: `field['status'] = 'ACTIVE'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of keys to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `api_keys` (array of ApiKey): The list of keys. Secrets are never included. - `id` (string (uuid)): Unique identifier for the key (UUID). - `tenant_id` (string (uuid)): The tenant this key belongs to (UUID), and the `tid` of every access token minted from it. Load-bearing on the resolve path and an echo everywhere else: resolving a raw key is the one lookup that has no tenant in hand and must return one, where every lifecycle call already knows the tenant from the caller. The key belongs to one tenant for its whole life, so the two can never disagree. - `name` (string): URL-safe, human-readable identifier for the key (e.g., "ci-deploy-key"). Unique within the parent resource. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `key_prefix` (string): Non-secret prefix of the key. The five-character brand (`admp_` when bound to a user, `adms_` when bound to a service account) followed by a short sample of characters from the secret body (e.g., "adms_pL2m"). URL-safe and safe to log and display. Use for incident response and audit trails without exposing the secret. - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. A mint request may narrow them and may never widen them. - `status` (ApiKeyStatus): Current lifecycle status of the key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. - `binding_type` (BindingType): The kind of resource this key is bound to. One of `BINDING_TYPE_UNSPECIFIED`, `BINDING_TYPE_USER`, `BINDING_TYPE_SERVICE_ACCOUNT`. - `binding_id` (string): The ID of the resource this key is bound to (UUID): a user id or a service account id, per `binding_type`. Access tokens minted from this key carry it as their `sub`. - `expires_at` (Timestamp): When the key expires. If unset, the key does not expire. - `last_used_at` (Timestamp): When this key was last exchanged for an access token. NOT the time of the last API request made with it: minted tokens are cached and reused for their lifetime, so a key in continuous use is exchanged only when the token minted from it runs out. Reads as "still in use", at a granularity of the access-token lifetime, which is the question this field exists to answer before revoking one. - `revoked_at` (Timestamp): When the key was revoked. Only set when status is REVOKED. - `created_by` (ActorRef): The user who created this key. When bound to a user, this is the key's owner; when bound to a service account, the administrator who issued it. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the key was created. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Create a personal access token" canonical: "https://admiral.io/docs/api/user/UserAPI_CreateApiKey" --- # Create a personal access token `POST https://api.admiral.io/v1/user/tokens` Scope: `token:write` ### Request body - `name` (string, required): URL-safe, human-readable identifier for the key (e.g., "postman-testing"). Unique per user within the tenant. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `scopes` (array of string): The scopes to grant this key. Must be scopes assignable to a user-bound key. The server enforces that issued scopes are a subset of the caller's own scopes. A key cannot grant more access than the user holds. Items at most 255. - `expires_at` (Timestamp): Optional expiration time. If unset, the key does not expire. Tenant policies may enforce a maximum lifetime. ### Response 200 Success - `api_key` (ApiKey): The created key metadata. - `id` (string (uuid)): Unique identifier for the key (UUID). - `tenant_id` (string (uuid)): The tenant this key belongs to (UUID), and the `tid` of every access token minted from it. Load-bearing on the resolve path and an echo everywhere else: resolving a raw key is the one lookup that has no tenant in hand and must return one, where every lifecycle call already knows the tenant from the caller. The key belongs to one tenant for its whole life, so the two can never disagree. - `name` (string): URL-safe, human-readable identifier for the key (e.g., "ci-deploy-key"). Unique within the parent resource. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `key_prefix` (string): Non-secret prefix of the key. The five-character brand (`admp_` when bound to a user, `adms_` when bound to a service account) followed by a short sample of characters from the secret body (e.g., "adms_pL2m"). URL-safe and safe to log and display. Use for incident response and audit trails without exposing the secret. - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. A mint request may narrow them and may never widen them. - `status` (ApiKeyStatus): Current lifecycle status of the key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. - `binding_type` (BindingType): The kind of resource this key is bound to. One of `BINDING_TYPE_UNSPECIFIED`, `BINDING_TYPE_USER`, `BINDING_TYPE_SERVICE_ACCOUNT`. - `binding_id` (string): The ID of the resource this key is bound to (UUID): a user id or a service account id, per `binding_type`. Access tokens minted from this key carry it as their `sub`. - `expires_at` (Timestamp): When the key expires. If unset, the key does not expire. - `last_used_at` (Timestamp): When this key was last exchanged for an access token. NOT the time of the last API request made with it: minted tokens are cached and reused for their lifetime, so a key in continuous use is exchanged only when the token minted from it runs out. Reads as "still in use", at a granularity of the access-token lifetime, which is the question this field exists to answer before revoking one. - `revoked_at` (Timestamp): When the key was revoked. Only set when status is REVOKED. - `created_by` (ActorRef): The user who created this key. When bound to a user, this is the key's owner; when bound to a service account, the administrator who issued it. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the key was created. - `plain_text_key` (string): The raw secret (e.g., "admp_7kH3mNqR2xFb..."). This value is shown exactly once and cannot be retrieved again. Store it securely. --- title: "Retrieve a personal access token" canonical: "https://admiral.io/docs/api/user/UserAPI_GetApiKey" --- # Retrieve a personal access token `GET https://api.admiral.io/v1/user/tokens/{token_id}` Scope: `token:read` ### Path parameters - `token_id` (string (uuid), required): The unique identifier of the key (UUID). ### Response 200 Success - `api_key` (ApiKey): The key metadata. The key secret is never included. - `id` (string (uuid)): Unique identifier for the key (UUID). - `tenant_id` (string (uuid)): The tenant this key belongs to (UUID), and the `tid` of every access token minted from it. Load-bearing on the resolve path and an echo everywhere else: resolving a raw key is the one lookup that has no tenant in hand and must return one, where every lifecycle call already knows the tenant from the caller. The key belongs to one tenant for its whole life, so the two can never disagree. - `name` (string): URL-safe, human-readable identifier for the key (e.g., "ci-deploy-key"). Unique within the parent resource. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `key_prefix` (string): Non-secret prefix of the key. The five-character brand (`admp_` when bound to a user, `adms_` when bound to a service account) followed by a short sample of characters from the secret body (e.g., "adms_pL2m"). URL-safe and safe to log and display. Use for incident response and audit trails without exposing the secret. - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. A mint request may narrow them and may never widen them. - `status` (ApiKeyStatus): Current lifecycle status of the key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. - `binding_type` (BindingType): The kind of resource this key is bound to. One of `BINDING_TYPE_UNSPECIFIED`, `BINDING_TYPE_USER`, `BINDING_TYPE_SERVICE_ACCOUNT`. - `binding_id` (string): The ID of the resource this key is bound to (UUID): a user id or a service account id, per `binding_type`. Access tokens minted from this key carry it as their `sub`. - `expires_at` (Timestamp): When the key expires. If unset, the key does not expire. - `last_used_at` (Timestamp): When this key was last exchanged for an access token. NOT the time of the last API request made with it: minted tokens are cached and reused for their lifetime, so a key in continuous use is exchanged only when the token minted from it runs out. Reads as "still in use", at a granularity of the access-token lifetime, which is the question this field exists to answer before revoking one. - `revoked_at` (Timestamp): When the key was revoked. Only set when status is REVOKED. - `created_by` (ActorRef): The user who created this key. When bound to a user, this is the key's owner; when bound to a service account, the administrator who issued it. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the key was created. --- title: "Update a personal access token" canonical: "https://admiral.io/docs/api/user/UserAPI_UpdateApiKey" --- # Update a personal access token `PATCH https://api.admiral.io/v1/user/tokens/{token_id}` Scope: `token:write` ### Path parameters - `token_id` (string (uuid), required): The unique identifier of the key to update (UUID). ### Request body - `name` (string): New name for the key. Must follow the same naming rules as creation. Omit to leave the name unchanged. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `scopes` (array of string): New scopes for the key. Replaces all existing scopes. The server enforces that issued scopes are a subset of the caller's own scopes. A key cannot grant more access than the user holds. Omit to leave scopes unchanged. Items at most 255. ### Response 200 Success - `api_key` (ApiKey): The updated key metadata. - `id` (string (uuid)): Unique identifier for the key (UUID). - `tenant_id` (string (uuid)): The tenant this key belongs to (UUID), and the `tid` of every access token minted from it. Load-bearing on the resolve path and an echo everywhere else: resolving a raw key is the one lookup that has no tenant in hand and must return one, where every lifecycle call already knows the tenant from the caller. The key belongs to one tenant for its whole life, so the two can never disagree. - `name` (string): URL-safe, human-readable identifier for the key (e.g., "ci-deploy-key"). Unique within the parent resource. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `key_prefix` (string): Non-secret prefix of the key. The five-character brand (`admp_` when bound to a user, `adms_` when bound to a service account) followed by a short sample of characters from the secret body (e.g., "adms_pL2m"). URL-safe and safe to log and display. Use for incident response and audit trails without exposing the secret. - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. A mint request may narrow them and may never widen them. - `status` (ApiKeyStatus): Current lifecycle status of the key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. - `binding_type` (BindingType): The kind of resource this key is bound to. One of `BINDING_TYPE_UNSPECIFIED`, `BINDING_TYPE_USER`, `BINDING_TYPE_SERVICE_ACCOUNT`. - `binding_id` (string): The ID of the resource this key is bound to (UUID): a user id or a service account id, per `binding_type`. Access tokens minted from this key carry it as their `sub`. - `expires_at` (Timestamp): When the key expires. If unset, the key does not expire. - `last_used_at` (Timestamp): When this key was last exchanged for an access token. NOT the time of the last API request made with it: minted tokens are cached and reused for their lifetime, so a key in continuous use is exchanged only when the token minted from it runs out. Reads as "still in use", at a granularity of the access-token lifetime, which is the question this field exists to answer before revoking one. - `revoked_at` (Timestamp): When the key was revoked. Only set when status is REVOKED. - `created_by` (ActorRef): The user who created this key. When bound to a user, this is the key's owner; when bound to a service account, the administrator who issued it. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the key was created. --- title: "Revoke a personal access token" canonical: "https://admiral.io/docs/api/user/UserAPI_RevokeApiKey" --- # Revoke a personal access token `POST https://api.admiral.io/v1/user/tokens/{token_id}/revoke` Scope: `token:write` ### Path parameters - `token_id` (string (uuid), required): The unique identifier of the key to revoke (UUID). ### Response 200 Success - `api_key` (ApiKey): The key metadata with updated status. - `id` (string (uuid)): Unique identifier for the key (UUID). - `tenant_id` (string (uuid)): The tenant this key belongs to (UUID), and the `tid` of every access token minted from it. Load-bearing on the resolve path and an echo everywhere else: resolving a raw key is the one lookup that has no tenant in hand and must return one, where every lifecycle call already knows the tenant from the caller. The key belongs to one tenant for its whole life, so the two can never disagree. - `name` (string): URL-safe, human-readable identifier for the key (e.g., "ci-deploy-key"). Unique within the parent resource. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `key_prefix` (string): Non-secret prefix of the key. The five-character brand (`admp_` when bound to a user, `adms_` when bound to a service account) followed by a short sample of characters from the secret body (e.g., "adms_pL2m"). URL-safe and safe to log and display. Use for incident response and audit trails without exposing the secret. - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. A mint request may narrow them and may never widen them. - `status` (ApiKeyStatus): Current lifecycle status of the key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. - `binding_type` (BindingType): The kind of resource this key is bound to. One of `BINDING_TYPE_UNSPECIFIED`, `BINDING_TYPE_USER`, `BINDING_TYPE_SERVICE_ACCOUNT`. - `binding_id` (string): The ID of the resource this key is bound to (UUID): a user id or a service account id, per `binding_type`. Access tokens minted from this key carry it as their `sub`. - `expires_at` (Timestamp): When the key expires. If unset, the key does not expire. - `last_used_at` (Timestamp): When this key was last exchanged for an access token. NOT the time of the last API request made with it: minted tokens are cached and reused for their lifetime, so a key in continuous use is exchanged only when the token minted from it runs out. Reads as "still in use", at a granularity of the access-token lifetime, which is the question this field exists to answer before revoking one. - `revoked_at` (Timestamp): When the key was revoked. Only set when status is REVOKED. - `created_by` (ActorRef): The user who created this key. When bound to a user, this is the key's owner; when bound to a service account, the administrator who issued it. - `id` (string): UUID of the user or service access token. - `display_name` (string): Human-readable name (e.g., "John Smith", "cluster-prod-agent"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the key was created. --- title: "List the members of the current tenant" canonical: "https://admiral.io/docs/api/users/UserAPI_ListUsers" --- # List the members of the current tenant `GET https://api.admiral.io/v1/users` Scope: `user:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `email`: filter by address. - `status`: filter by status. Example: `field['status'] = 'ACTIVE'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of users to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `users` (array of User) - `id` (string (uuid)): Unique identifier for the user (UUID). - `email` (string): User's email address. - `email_verified` (boolean): Whether the email has been verified by the IdP. - `display_name` (string): User's display name for UI purposes. - `given_name` (string): User's given (first) name. - `family_name` (string): User's family (last) name. - `avatar_url` (string): URL to the user's avatar image. - `created_at` (Timestamp): When the user was created. - `updated_at` (Timestamp): When the user was last updated. - `role` (UserRole): The user's standing in the tenant. One of `USER_ROLE_UNSPECIFIED`, `USER_ROLE_OWNER`, `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`, `USER_ROLE_APP_CREATOR`. Read-only. - `status` (UserStatus): Whether the user can currently sign in. One of `USER_STATUS_UNSPECIFIED`, `USER_STATUS_ACTIVE`, `USER_STATUS_SUSPENDED`. Read-only. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results. --- title: "Retrieve a user by ID" canonical: "https://admiral.io/docs/api/users/UserAPI_GetUser" --- # Retrieve a user by ID `GET https://api.admiral.io/v1/users/{user_id}` Scope: `user:read` ### Path parameters - `user_id` (string (uuid), required): The unique identifier of the user (UUID). ### Response 200 Success - `user` (User): The user profile. - `id` (string (uuid)): Unique identifier for the user (UUID). - `email` (string): User's email address. - `email_verified` (boolean): Whether the email has been verified by the IdP. - `display_name` (string): User's display name for UI purposes. - `given_name` (string): User's given (first) name. - `family_name` (string): User's family (last) name. - `avatar_url` (string): URL to the user's avatar image. - `created_at` (Timestamp): When the user was created. - `updated_at` (Timestamp): When the user was last updated. - `role` (UserRole): The user's standing in the tenant. One of `USER_ROLE_UNSPECIFIED`, `USER_ROLE_OWNER`, `USER_ROLE_ADMIN`, `USER_ROLE_MEMBER`, `USER_ROLE_APP_CREATOR`. Read-only. - `status` (UserStatus): Whether the user can currently sign in. One of `USER_STATUS_UNSPECIFIED`, `USER_STATUS_ACTIVE`, `USER_STATUS_SUSPENDED`. Read-only. --- title: "Fetch current Terraform state" canonical: "https://admiral.io/docs/api/state/get-state" --- # Fetch current Terraform state `GET https://api.admiral.io/api/v1/state/{component_id}/env/{environment_id}` Returns the current `.tfstate` document for the component+environment, or 204 when no state exists yet. Maps to the Terraform HTTP backend GET. Authenticate with a PAT/SAT (HTTP Basic password or Bearer token); requires the `state:read` scope. ### Response 200 The current Terraform state document. Type: object. ### Response 204 No state exists yet. ### Response 401 Unauthorized. ### Response 404 Component or environment not found. --- title: "Push Terraform state" canonical: "https://admiral.io/docs/api/state/post-state" --- # Push Terraform state `POST https://api.admiral.io/api/v1/state/{component_id}/env/{environment_id}` Stores a new state version; the body is the full `.tfstate` document. Maps to the Terraform HTTP backend POST. Authenticate with a PAT/SAT; requires the `state:write` scope. ### Query parameters - `ID` (string (uuid)): The held lock ID, when the state is locked. ### Request body Type: object. ### Response 200 State stored. ### Response 400 Invalid state document. ### Response 413 State document too large. ### Response 423 State is locked by a different lock ID. - `ID` (string): Lock identifier (UUID), generated by the Terraform client. - `Operation` (string): Terraform operation holding the lock (informational). - `Info` (string) - `Who` (string): Holder identity, typically "user@host" (informational). - `Version` (string): Terraform/OpenTofu client version (informational). - `Created` (string (date-time)) - `Path` (string)