> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Add workers

> Connect compute capacity to your managed cluster to run applications

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/akua-1dce587a/z0JWjmxNCPr4v1ee/images/heros/clusters-add-workers-light.svg?fit=max&auto=format&n=z0JWjmxNCPr4v1ee&q=85&s=a02960b1ec8aa3940109d8917e06cc92" alt="The control plane hands a bootstrap token to a new machine, which joins the cluster and fills its scheduling slots" width="1536" height="864" data-path="images/heros/clusters-add-workers-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/akua-1dce587a/z0JWjmxNCPr4v1ee/images/heros/clusters-add-workers-dark.svg?fit=max&auto=format&n=z0JWjmxNCPr4v1ee&q=85&s=4a749b793dddd68875f34f25800e5937" alt="The control plane hands a bootstrap token to a new machine, which joins the cluster and fills its scheduling slots" width="1536" height="864" data-path="images/heros/clusters-add-workers-dark.svg" />
</Frame>

After creating a managed cluster, you need to add <Tooltip headline="Worker Nodes" tip="Worker nodes are the machines that run your applications in a Kubernetes cluster. They provide compute capacity and storage, and need outbound networking access to communicate with the control plane. The control plane schedules workloads to run on these nodes.">worker nodes</Tooltip> where your applications will run. Akua handles all the Kubernetes setup and <Tooltip headline="Lifecycle Management" tip="Akua manages the ongoing operations of your workers including joining them to the cluster, configuring networking and security, and maintaining the connection. The connection between workers and the control plane is TLS-secured with automatic certificate rotation, ensuring secure communication without requiring firewall configuration.">lifecycle management</Tooltip> once you connect your machines.

<Note>
  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](/compute/overview).
</Note>

<Tip>
  **Don't want to manage servers?** Akua can [provision and manage machines](/compute/machines) for
  you. Add compute capacity from the dashboard without needing a separate cloud provider account.
</Tip>

<Tip>
  **Testing locally?** Use [Multipass](/clusters/local-testing) for free local testing before buying
  production servers. Akua's managed{' '}

  <Tooltip headline="Control Plane" tip="The control plane is the management layer of a Kubernetes cluster. It manages the cluster's state, schedules workloads, and handles API requests. Akua manages the control plane for you in managed clusters.">
    control plane
  </Tooltip>

  {' '}

  can communicate with local workers via tunneling without requiring public IP addresses.
</Tip>

## 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

<Steps>
  <Step title="Get worker setup command">
    In your [clusters dashboard](https://akua.dev/clusters), click on your cluster and find the **"Quick Actions"** section. Click **"Add a worker"** and copy the bootstrap command.

    The command looks like:

    ```bash Bootstrap command theme={null}
    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.
  </Step>

  <Step title="Connect and run setup command">
    SSH into your server:

    ```bash SSH to server theme={null}
    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.
  </Step>

  <Step title="Verify connection">
    Your worker will appear in the dashboard within 1–2 minutes as "Active". You can now start deploying applications to your cluster.
  </Step>
</Steps>

## 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.

<Steps>
  <Step title="Copy cloud-init config">
    In your cluster dashboard, click **"Add a worker"** and switch to the **"Cloud-init"** tab. Copy the configuration:

    ```yaml Cloud-init config theme={null}
    #cloud-config
    runcmd:
      - curl -fsSL "https://akua.dev/worker.sh?k0sVersion=v1.33.1-k0s.0" | bash -s -- -t "your-join-token"
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  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.
</Info>

## 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](/clusters/limits#bring-your-own-cloud-key) for full details.

## Supported operating systems

Workers support a wide range of Linux distributions. Windows workers are supported only on mixed operating system clusters; see [Windows workers](/clusters/windows-workers) before attaching a Windows machine.

* **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**: 2022 amd64, only on managed clusters created with **Linux and Windows workers** support

## Troubleshooting

<AccordionGroup>
  <Accordion title="Worker not appearing in dashboard">
    * 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
  </Accordion>

  <Accordion title="Setup command fails">
    * Check server meets minimum requirements (2 CPU, 4 GB RAM)
    * Ensure you're using a supported Linux distribution or the [Windows worker prerequisites](/clusters/windows-workers#prerequisites)
    * 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)
  </Accordion>

  <Accordion title="Worker behind firewall or NAT">
    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.
  </Accordion>
</AccordionGroup>

## API

Manage clusters and machines programmatically.

<CardGroup cols={2}>
  <Card title="Clusters API reference" icon="book" href="/api-reference/clusters/list-clusters">
    Cluster endpoints including worker bootstrap token generation.
  </Card>

  <Card title="Machines API reference" icon="server" href="/api-reference/machines/list-machines">
    Provision and manage Akua-managed compute machines.
  </Card>
</CardGroup>

## Related topics

<CardGroup cols={2}>
  <Card title="Machines" icon="server" href="/compute/machines">
    Let Akua provision and manage machines for you.
  </Card>

  <Card title="Local testing" icon="laptop" href="/clusters/local-testing">
    Test worker setup locally with Multipass before production.
  </Card>

  <Card title="Limits and pricing" icon="credit-card" href="/clusters/limits">
    Which limits apply and how BYOM bypasses quotas.
  </Card>

  <Card title="Storage" icon="database" href="/clusters/storage">
    Add persistent storage after your workers are connected.
  </Card>
</CardGroup>