Skip to main content
This guide creates a short-lived Talos Kubernetes cluster on a GitHub Actions runner, for example to run end-to-end tests against real Talos nodes in CI. It uses talosctl-cluster-action, a GitHub Action that wraps talosctl cluster create. The action creates the cluster from a declarative configuration file, exports KUBECONFIG and TALOSCONFIG to later steps in the job, and destroys the cluster when the job ends.
talosctl-cluster-action is a community project maintained by home-operations, not by Sidero Labs. Report problems with the action in its repository.

​
Requirements

The runner and the cluster must meet the following requirements:
  • An x86_64 Linux runner. GitHub-hosted ubuntu-24.04 runners meet the requirements of both providers described below.
  • talosctl v1.14 or later on the runner’s PATH.
  • Talos v1.14 or later on the cluster nodes.
The action rejects earlier versions of both talosctl and Talos.

​
Create a cluster

To create a cluster, choose a provider, then add a cluster configuration file and a workflow to the repository. The action supports two providers, which map to talosctl cluster create docker and the QEMU provisioner. The provider is set with spec.provider in the cluster configuration file, and the providers differ as follows: Use docker when a test only needs a Kubernetes API. Use qemu when a test needs real kernels, disks, or Talos upgrades.
The Docker provider runs each node as a container on the runner, and the cluster boots in seconds.
  1. Save the cluster configuration to .talos-cluster.yaml in the repository: The Docker provider always creates exactly one control plane node, so the configuration sets only the number of workers.
  2. Add a workflow, for example .github/workflows/e2e.yaml: Without the br_netfilter module, the pod network never becomes ready and cluster creation times out.
  3. Commit both files and open a pull request.
Both workflows create the cluster on every pull request and destroy it when the job ends, including when a step fails.

​
Use the cluster in later steps

After the action runs, kubectl and talosctl in later steps use the new cluster, because the action exports KUBECONFIG and TALOSCONFIG. The action also sets outputs, such as the address of the first control plane node. To use an output, give the action step an id:
The action’s README lists every output, including the control plane and worker addresses.

​
Default settings for short-lived clusters

By default, the action applies an ephemeral profile that tunes the cluster for a single CI run. For example, it disables etcd fsync, image garbage collection, pod eviction, and the public discovery service. These settings are not suitable for a long-lived cluster. To create the cluster without these settings, set spec.profile: none in the cluster configuration file.

​
More options

The talosctl-cluster-action README describes the rest of the configuration, including:
  • Every field of the cluster configuration file and the talosctl flag it maps to.
  • Image Factory schematics, extra disks, and configuration patches.
  • Caching boot assets between runs with the cache input.
  • Running several cluster shapes in a job matrix.
  • Booting nodes in maintenance mode without applying a machine configuration.