Skip to main content
The control plane hands a bootstrap token to a new machine, which joins the cluster and fills its scheduling slots
After creating a managed cluster, you need to add where your applications will run. Akua handles all the Kubernetes setup and once you connect your machines.
This page covers manually attached workers for managed clusters. Imported clusters keep worker management with the provider or cluster administrator. For Akua-managed machines and BYOM provisioning, see Managed machines.
Don’t want to manage servers? Akua can provision and manage machines for you. Add compute capacity from the dashboard without needing a separate cloud provider account.
Testing locally? Use Multipass for free local testing before buying production servers. Akua’s managed can communicate with local workers via tunneling without requiring public IP addresses.

​
Prerequisites

  • An active managed cluster (status shows “Active” in the dashboard)
  • A server or machine to connect (see supported operating systems below)
  • Server meets minimum requirements: 2 CPU, 4 GB RAM (4 CPU, 8 GB RAM recommended for production)

​
How to add workers

1

Get worker setup command

In your clusters dashboard, click on your cluster and find the “Quick Actions” section. Click “Add a worker” and copy the bootstrap command.The command looks like:
Bootstrap command
curl -fsSL "https://akua.dev/worker.sh?k0sVersion=..." | sudo bash -s -- -t "your-join-token"
Join token details: The token expires 30 minutes after generation and can be used multiple times to join multiple machines.
2

Connect and run setup command

SSH into your server:
SSH to server
ssh root@your-server-ip
Then execute the bootstrap command you copied from the dashboard. The script automatically installs Kubernetes components, joins the worker to your cluster, and configures networking and security.
3

Verify connection

Your worker will appear in the dashboard within 1–2 minutes as “Active”. You can now start deploying applications to your cluster.

​
Automated provisioning with cloud-init

For fully automated worker provisioning, use cloud-init when creating the server you plan to attach. The server will automatically join your cluster on first boot, so you don’t need to SSH in first.
1

Copy cloud-init config

In your cluster dashboard, click “Add a worker” and switch to the “Cloud-init” tab. Copy the configuration:
Cloud-init config
#cloud-config
runcmd:
  - curl -fsSL "https://akua.dev/worker.sh?k0sVersion=v1.33.1-k0s.0" | bash -s -- -t "your-join-token"
2

Create server with cloud-init

When creating a new server in your provider’s dashboard, paste the cloud-init into the provider’s user-data or startup-script field. Common names include:
  • Hetzner: “Cloud config” under “Additional features”
  • AWS EC2: “User data” under “Advanced details”
  • DigitalOcean: “User data” under “Advanced options”
  • Vultr: “Cloud-Init User-Data”
  • GCP: “Automation” → “Startup script”
The server will automatically join your cluster within minutes of booting.
Cloud-init’s runcmd executes once on first boot only. If you need to re-run the bootstrap (for example, after a reset), you’ll need to use the manual command method or recreate the server.

​
Revoke a bootstrap token

You can revoke an unused worker bootstrap token from the dashboard or with POST /v1/clusters/{id}/worker_bootstraps/{wbs_id}:revoke. Revocation starts a background operation: Akua records the token as revoked immediately, then invalidates the k0s join token when the managed control plane is reachable. If the cluster is suspended or temporarily unreachable, the operation waits until the cluster can process the invalidation. If you cancel the operation after the token is marked revoked, the dashboard keeps the bootstrap in the revoked state, but the bearer token may still join workers until it expires naturally. Bootstrap tokens expire within 24 hours.

​
Bring your own cloud key (BYOM)

If you have an account with a supported cloud provider, you can connect it to Akua so machines are provisioned in your account directly. This bypasses the machine, CPU, and memory resource quotas, and you pay the provider directly. To use your own cloud key:
  1. Navigate to Settings → Cloud providers in your workspace
  2. Add an API key for any provider shown as available in the dashboard. Hetzner Cloud is available today.
  3. When creating machines from the dashboard, select your cloud provider key
Your machines are created in your cloud account. Concurrency and rate limits still apply because they protect the cluster regardless of who pays for the compute. See limits and pricing for full details.

​
Supported operating systems

Workers support a wide range of Linux distributions and Windows Server:
  • Debian: 11 (Bullseye), 12 (Bookworm)
  • Ubuntu: 22.04 LTS or later
  • Red Hat Enterprise Linux: 7.9, 8.10, 9.5
  • CentOS Stream: 9, 10
  • Oracle Linux Server: 8.9, 9.3
  • Amazon Linux: 2023
  • Fedora: 41 (Cloud Edition)
  • Fedora CoreOS: Stable stream
  • Alpine Linux: 3.19, 3.22
  • Flatcar Container Linux
  • Windows Server: 2019 (experimental support)

​
Troubleshooting

  • Verify the server has internet connectivity
  • Check that the setup command was copied correctly
  • Ensure you’re running as root (with sudo)
  • Wait 2–3 minutes for the registration process
  • Check server meets minimum requirements (2 CPU, 4 GB RAM)
  • Ensure you’re using a supported Linux distribution (see supported operating systems)
  • Verify no conflicting Docker or Kubernetes installations
  • Verify server has outbound networking access to the control plane (outbound HTTPS connections are allowed by default, but check if behind a firewall)
Akua’s managed KaaS architecture is designed so workers don’t need public IP addresses. Workers automatically create outbound connectivity tunnels to the control plane, allowing the control plane to reach the kubelet securely. This works behind firewalls, NAT, and restrictive networks.

​
API

Manage clusters and machines programmatically.

Clusters API reference

Cluster endpoints including worker bootstrap token generation.

Machines API reference

Provision and manage Akua-managed compute machines.

Machines

Let Akua provision and manage machines for you.

Local testing

Test worker setup locally with Multipass before production.

Limits and pricing

Which limits apply and how BYOM bypasses quotas.

Storage

Add persistent storage after your workers are connected.