Skip to main content
Closed beta. Test environments are built on Ankra Cloud, which is in closed beta. The workflow is stable but the surface may still change, and Ankra Cloud is enabled per organisation on request. Until it is, every leg ends as error without building a cluster. Contact support to have it turned on for your organisation.
A unit test proves your code. It does not prove your release runs on the Kubernetes and PostgreSQL versions your customers run. A 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 take plan. 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 error once the platform stops retrying. A leg whose cluster does not fit in your Ankra Cloud account’s quota yet waits with the message Waiting 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 as error at 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: passed or failed.
  • Tearing down deletes the cluster. The step concludes the moment the leg has a result, so publish does not wait for the teardown. A teardown is retried until it succeeds.
A leg ends with one of these results: 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.
Give an environment stage a timeout at least as long as its max_lifetime. A leg also runs under its stage’s timeout: the stage’s own, else the pipeline’s defaults.timeout, else 30 minutes. When a leg is still running past it, Ankra ends the leg, tears its cluster down without a step log and retries the leg on a new cluster, which is billed again and takes another of your six slots. The stage’s timeout is a protected section, approved with the rest.

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 validate with --application or --repository warns under pipeline_authority: that a run does not take the stage from the file, and prints the command that approves the definition.
Once the block is approved, a run still builds no cluster unless it runs under approved authority. A pull request that changes a protected section nobody has approved, and a push to the default branch whose protected sections nobody has approved yet, build none: each leg ends without a cluster, and its step log says the run’s protected sections are not approved. What is approved is the block as written, every field of it. The matrix is the stage’s logic, so changing its axes needs no approval: a field that reads ${{ 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 held cluster lasts until its max_lifetime, not longer.
A larger 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 example Test 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

  1. 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.
  2. Act on the result.
  3. 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 as publish. Legs that passed are not repeated, so the new run’s grid shows only the legs it repeated.
To debug a failing leg on its live cluster, set 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.