kind: environment stage tests that before you publish.
For each leg of the stage’s matrix, Ankra builds a fresh cluster with that leg’s Kubernetes version and PostgreSQL service, deploys the image this run built, runs your tests against it as a Job and records the leg’s result. Then it tears the cluster down, whatever the result, unless you ask to keep a failed leg’s cluster for debugging. A publish stage that needs the environment stage waits for every leg, and runs only when all of them pass.
Each leg is an ordinary Ankra Cloud cluster in your organisation, billed to your organisation’s Ankra Cloud account for as long as it exists and listed with your other clusters while it does. The
test_environment block is a protected section: the stage builds nothing until a person with pipelines.manage approves the definition that declares it.A Kubernetes x PostgreSQL grid
This pipeline builds once, scans and gates the image, and tests it on six clusters: Kubernetes 1.35, 1.36 and 1.37, each with PostgreSQL 16 and 17. It publishes only when the gate and all six legs pass:.ankra/pipeline.yaml
deploy: build-under-test deploys the image of the one build stage the environment stage needs, by its digest, as one replica in the ankra-test namespace with a ClusterIP Service on its port. The tests run as a Kubernetes Job in the same namespace: test.run runs once, with /bin/sh -c, in test.image. The Job gets no checkout of your repository, so the tests have to be inside test.image. They reach the deployment through these variables:
A variable in
deploy.env or test.env with one of these names is dropped: these describe the environment, which only Ankra knows. The deployment has no readiness probe, so it counts as ready as soon as its container runs. If your build takes a moment to listen, let the tests retry their first request.
The stage’s timeout of two hours matches the default max_lifetime. Keep it at least that long: see The lifecycle.
The test_environment block
The one expression the block resolves is
${{ matrix.<axis> }}, naming an axis of the stage’s own matrix. It works in kubernetes, services, plan, zone, disk_tier, control_plane_disk_tier, test.image, test.run, test.timeout and the values of deploy.env and test.env. Write every other value literally.
Validation refuses a block that names an axis the matrix does not declare, a Kubernetes version that is neither a minor nor a patch, a PostgreSQL major or a disk tier outside the lists above (checked for every value of a matrix axis too), more than one service, a deploy that names no build or publish stage this stage needs, a missing test.image or test.run, and a max_lifetime over 6h. ankra pipeline validate reports it before you push, and a run of such a file is refused before anything runs. A test.timeout that is not shorter than max_lifetime is a warning: the cluster is torn down at the lifetime, so the leg would end timed_out instead of with your tests’ verdict.
Leave both disk tiers out unless the zone has no room on its default tier. When Ankra Cloud refuses a leg’s disk for want of room there, the leg ends as error and its message suggests disk_tier: standard. Move the control plane too, with control_plane_disk_tier, only when that message says its disk was the refused one: etcd writes to that disk on every change, and runs markedly slower on the replicated Ankra Storage tiers (standard, maxiops, hdd).
What each leg builds
Each leg is a self-managed kubeadm cluster built with your organisation’s Ankra Cloud account: three servers (a bastion, one control plane and one worker), Cilium, IPv6-only networking with no public IPv4 address, and no networking or DNS stack, so the build under test is reached only inside the cluster. A leg with a service also gets the CloudNativePG operator and the PostgreSQL volume. The bastion takes the cheapest available plan; the control plane and the worker takeplan.
The cluster is named te-<id>-k<version>[-pg<major>], for example te-1a2b3c4d5e6f-k136-pg17, and its description is Ephemeral test environment for pipeline run <run-id> (<step-key>); deleted automatically. While it exists, it appears in your organisation’s cluster list, its cluster counts and its fleet cost estimate like any other cluster.
The lifecycle
Each leg moves through these phases:- Queued - the leg waits for the stages it needs, or for a free slot when your organisation already has six environment clusters.
- Provisioning builds the cluster. A cluster build step that fails is run again by the platform, and the leg waits while it is; the leg ends as
erroronce the platform stops retrying. A leg whose cluster does not fit in your Ankra Cloud account’s quota yet waits with the messageWaiting for Ankra Cloud quota: ...while other test environments of your organisation hold clusters that will be torn down. When the quota is held by your other clusters instead, the leg ends aserrorat once. - Deploying applies PostgreSQL, on a leg that has it, and the build under test, and waits for both. A build that is not available within 10 minutes fails the leg.
- Testing runs the test Job. Its exit code is the leg’s result:
passedorfailed. - Tearing down deletes the cluster. The step concludes the moment the leg has a result, so
publishdoes not wait for the teardown. A teardown is retried until it succeeds.
With
teardown: always, the default, the cluster is torn down whatever happens: when the leg passes, when it fails, when the run is cancelled and when the run dies. A cluster that reaches its max_lifetime is torn down whatever state its run is in. With teardown: on_success a failed leg’s cluster is kept as held for debugging, until its max_lifetime runs out and never longer. A leg that ends error or timed_out is torn down either way.
Limits
Approval and who can build one
test_environment is a protected section. It decides which clusters your organisation pays for, so it carries no authority until a person with pipelines.manage, signed in as themselves, approves the definition on the default branch. Approve it as in step 5 of Set up and run Ankra Pipelines: from Pipeline settings waiting for approval, from Review authority for approval on the run, with Approve authority on the GitHub check run, or with ankra pipeline definitions approve <definition-id>.
Until it is approved:
- Ankra leaves the environment stage out of the run. A run in which another stage, such as
publish, needs it is refused before anything runs, because a stage it needs is not in the run. ankra pipeline validatewith--applicationor--repositorywarns underpipeline_authority:that a run does not take the stage from the file, and prints the command that approves the definition.
${{ matrix.kubernetes }} is approved once, and a new Kubernetes version in the axis adds legs, and clusters, without another approval.
A run of a fork’s head never builds a test environment, because the clusters are billed to your organisation.
What it costs
Every leg’s cluster is billed to your organisation’s Ankra Cloud account like any other Ankra Cloud cluster, for the time it exists: the three servers at their plan prices, their root disks, the PostgreSQL volume and outbound transfer. It takes no public IPv4 address and no NAT router. See Cost for every line and Ankra Cloud Servers, Disks and Quota for plans, tiers and quota. A leg usually lives minutes, because its cluster is torn down as soon as the leg has a result. What bounds the bill:- At most six environment clusters at once, so a six-leg grid holds up to eighteen servers.
max_lifetime, two hours by default, enforced even when the run dies.- A
heldcluster lasts until itsmax_lifetime, not longer.
plan or a longer max_lifetime is a change to the protected block, approved with the rest. More matrix values are not: they mean more legs, built six at a time. The stage also runs on every event the pipeline triggers on, pull requests included, unless its when.events says otherwise; when.events: [push] keeps the clusters to pushes.
Read the results
On the run’s page in the portal, Test environments sits under the run’s steps once the run has environment legs. Its heading counts the legs, for exampleTest environments · 6 environments: 5 passed, 1 failed, and a badge gives the verdict: Running while a leg has no result, Passed when every leg passed, and Publish blocked when one did not. A matrix with two axes shows as a grid, with Kubernetes versions down the side; any other matrix shows as a list. Select a leg for how long it took, its attempt, whether its cluster is still up, its last message and Test log (last lines).
environments (alias envs) prints a two-axis matrix as a grid: with axes named kubernetes and postgres, Kubernetes versions down and PostgreSQL versions across. Each cell is passed 5m12s, FAILED, ERROR, TIMED OUT, the phase of a leg still in flight, or queued. Under the grid, one line counts the legs and says whether every cluster is torn down. Each leg that failed, errored or timed out follows with its message and the last ten lines of its test log; --logs prints the whole tail, and -o json prints the platform’s answer as sent. Any other matrix prints as a table. ankra pipeline get <run-id> and ankra pipeline tests <run-id> show the same grid under “Test environments”.
A leg Ankra refused before it built anything, in a run whose protected sections are not approved for example, reads queued with no result in the grid and in the CLI, and the portal’s verdict stays Running. Its step is concluded failed, and its step log says why.
When a leg fails
-
Read the leg’s step log. The message in the grid is one line. The step log has the rest:
ankra pipeline get <run-id>prints each leg’s step key. The log names the leg’s cluster, its result and why, and what the cluster build went through. For a leg that failed or timed out while its cluster stood, it adds what the cluster showed before it was torn down: the pods and their container states, the failing pod’s log, the database, events and node pressure. It ends with the tail of the test output. -
Act on the result.
-
Run the failed legs again. Use Re-run → Re-run failed steps on the run, or:
A re-run is a new run. It repeats each leg that did not pass on a new cluster, together with the stages those legs need, such as
build, and the stages that need them, such aspublish. Legs that passed are not repeated, so the new run’s grid shows only the legs it repeated.
teardown: on_success: a failed leg’s cluster is then kept as held until its max_lifetime, and holds one of your six slots until then.
Related
- Pipeline reference - every stage kind and its block
- Set up and run Ankra Pipelines - how a run is planned, and which authority it runs under
- Ankra Cloud Clusters - the clusters a test environment is built as
- Ankra Cloud Servers, Disks and Quota - the plans, zones, tiers and quota a test environment uses