Status and history¶

ankka services list shows every service in a project, one line each. ankka services get <name> shows one service in full. ankka services history <name> shows who changed it and when. All three read the control plane, which records both what you asked for and what the cluster last reported; see Desired and observed state.

Every command acts on the project named by --project (-p), or on the one saved with ankka config set project <id>.

List the services in a project¶

ankka services list

NAME  STATUS  INSTANCES  GEN  IMAGE                        HOSTNAME
cart  Ready   1/1        1    sample-shopping-cart:latest  https://cart-checkout.127.0.0.1.sslip.io:8443

Column	Meaning
`NAME`	The service's name, from its descriptor.
`STATUS`	Its lifecycle state, followed by `(unconfirmed)` when the reading is not current.
`INSTANCES`	Ready instances over desired instances.
`GEN`	The generation: how many applies and restarts the service has had.
`IMAGE`	The image the current descriptor names.
`HOSTNAME`	The URL it answers on outside the cluster, or `-` when it is not exposed.

The lifecycle states are listed in Service lifecycle states. The one to learn first is UpdateInProgress: the service is moving towards what its descriptor asks for and has not got there yet.

Show one service¶

ankka services get cart

name        cart
project     checkout
status      Ready
instances   1/1
generation  1
image       sample-shopping-cart:latest
hosting     embedded
hostname    https://cart-checkout.127.0.0.1.sslip.io:8443
database    provisioned

Field	Meaning
`status`	The lifecycle state, marked `(unconfirmed)` when it is not a current reading.
`instances`	Ready over desired. A paused or suspended service desires zero.
`generation`	Increments on every apply and every restart. A report about an older generation is ignored.
`hosting`	`embedded` for a service whose image is an ankka runtime, `process` for one that runs beside a sidecar.
`protocol`	For a process-hosted service, the sidecar protocol version it declared.
`hostname`	The external URL, `not exposed`, or a note that it is exposed but the control plane has no base domain configured.
`custom hostnames`	Each name under your own domain the service answers at: `pending`, `serving` or `rejected` with the reason, and the record to create. See Serve a service at your own domain.
`proof record`	The `TXT` record that proves the project controls a name it brings, shown with the custom hostnames.
`database`	What the platform did about the service's database, once something has reported: `waiting for database`, `provisioned`, `recovered existing data`, `supplied` or `database provisioning failed`.
`object storage`	What the platform did about the service's bucket, for a service that has object storage: `waiting for object storage`, `provisioned`, `recovered existing bucket`, `supplied` or `object storage provisioning failed`. Why it waits or failed is in `detail`, after `object storage:`.
`bucket`	The bucket the platform gives the service, when its descriptor asks for one.
`bucket address`	The bucket's address on the internet, when its descriptor asks that it be reachable.
`object store`	Which store the bucket is in: `garage`, or `gcs` for Google Cloud Storage.
`bucket location`	Where a bucket in Google Cloud Storage was made, as the cloud provider reported it.
`soft delete`	How many days a deleted object in a bucket in Google Cloud Storage can still be recovered.
`bucket <name>`	One line per named bucket: its exposure (`private`, `signed` or `public`), `supplied` for a bucket the service brings, or `kept` for one the descriptor no longer names; then its name in the store and, when it is reachable from outside, its address. A kept bucket ends `(no longer named)`: nothing in it is deleted, and naming it again gives it back.
`storage move`	Where a move of the bucket from Garage is: `waiting for its bucket in Google Cloud Storage`, `copying`, its write pause (since when, and how long it may last), `verifying`, `moved` or `move failed`, with why it failed in `detail`.
`detail`	Why the service is in its state, when there is something to say: a rollout problem, a refused version, an unreachable cluster, or a route the gateway has not accepted (`route rejected: <reason>`).

detail is shown only by get, which is why list marks unconfirmed readings in the status column itself.

Confirmed and unconfirmed¶

A status is confirmed when it is a report from the cluster about the service's current generation. It is unconfirmed when the control plane is restating what it last knew — because it cannot reach the cluster, for example, or because no operator has reported on the service at all. detail says which. An unconfirmed Ready means "was ready when last seen", not "is ready".

Script against the status¶

Every command takes -o json (--output json) and prints the status exactly as the control plane's API returns it:

ankka services get cart -o json | jq -r .lifecycle
# Ready

ankka services list -o json | jq -r '.[] | select(.lifecycle != "Ready") | .name'

The JSON has every field, including confirmed, exposed, paused and suspended, which the table folds into other columns. The field list is in Control plane HTTP API.

The CLI's exit code is 0 when the command succeeded, 1 when it failed — a refusal from the control plane, an invalid descriptor, no project selected — and 2 when the command line itself could not be parsed. A script can therefore tell a mistyped command from a failed apply. Errors are printed to standard error as error: <detail>.

A deployment script that must wait for a service to become ready polls the status:

until [ "$(ankka services get cart -o json | jq -r '.lifecycle + "/" + (.confirmed|tostring)')" = "Ready/true" ]; do
  sleep 5
done

See who changed a service¶

ankka services history cart

WHEN                      KIND              GEN  IMAGE   DIGEST        BY
2026-09-24T10:20:44.018Z  rolled-back to 1  3    cart:1  3f9a1c0be2d4  alice@example.com
2026-09-24T10:12:03.114Z  applied           2    cart:2  a41d77c09e15  alice@example.com
2026-09-24T09:58:41.902Z  exposed           1    -       -             alice@example.com
2026-09-24T09:57:10.337Z  applied           1    cart:1  3f9a1c0be2d4  bob@example.com (admin)

Each row is one change, newest first: applied, rolled-back, restarted, paused, resumed, exposed, unexposed, hostname added, hostname removed, hostname taken away, deleted, suspended, reinstated, storage-credential-reissued, storage-moved or storage-settings-reapplied. GEN is the generation the service had after the change, and BY is who asked, by display name or subject. (admin) marks a change that was allowed by the platform-admin role rather than by membership of the organization. A service keeps its last 50 changes. Reports from the cluster are not changes and do not appear.

Changes recorded before the platform began attributing them show - for who and when.

An apply and a rollback also show what they ran: IMAGE is the descriptor's image, and DIGEST the first twelve characters of a digest of the whole descriptor. Two rows share a digest exactly when their descriptors state the same things, so two generations with one image and a different environment are told apart; reordering labels or annotations is not a change, and reordering variables is. Every other row shows - in both. A rollback's row says which generation it rolled back to. An entry the control plane kept from before it recorded images may show - too. -o json prints the whole digest.

Read the descriptor of a generation¶

ankka services history cart --generation 1 > service.json
ankka services apply -f service.json

--generation prints the descriptor the service applied at that generation, as JSON that apply accepts, so you can compare it with your own file before rolling back, or change it and apply it. A service keeps the descriptors of its last 50 applies; for an older generation, or a restart's, it says which it has instead.

A past descriptor shows its variables' values as they were applied, to every member of the project's organization and to every platform administrator. A value that should not be read back belongs in a project secret, which a descriptor refers to by name and never holds.

See what a service is made of¶

ankka services topology <name> reads the service's topology from every running instance: its components by layer, the connections they declare, and the calls observed between their handlers in a recent window, with handled and unanswered counts in separate columns. It says how many instances answered and names any that did not; a partial answer still exits 0. -o json prints the merged document as the control plane returns it. See Observability for what observed calls are.