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

# UpCloud Clusters

> Create, manage, and scale Kubernetes clusters on UpCloud with Ankra.

Ankra supports provisioning fully managed Kubernetes clusters on [UpCloud](https://upcloud.com/). You can create clusters with configurable control planes, workers, and networking — then scale workers up or down as needed.

***

## Prerequisites

Before creating an UpCloud cluster, you need two credentials:

<CardGroup cols={2}>
  <Card title="UpCloud API Credential" icon="key">
    An UpCloud API token with read/write permissions. See [UpCloud Credentials](/integrations/credentials#upcloud-api-credentials).
  </Card>

  <Card title="SSH Key Credential" icon="lock">
    An SSH public key for server access. You can provide your own or let Ankra generate one. See [SSH Key Credentials](/integrations/credentials#ssh-key-credentials).
  </Card>
</CardGroup>

***

## Creating an UpCloud Cluster

### Via the Platform UI

A guided wizard walks you through creating an UpCloud cluster — select credentials, pick a datacenter zone, choose server plans, set control plane and worker counts, and launch.

<Steps>
  <Step title="Navigate to Clusters">
    Go to **Clusters** in the Ankra dashboard and click **Create Cluster**.
  </Step>

  <Step title="Select UpCloud">
    Choose **UpCloud** as the provider.
  </Step>

  <Step title="Select Credentials">
    Pick your UpCloud API credential and SSH key credential from the dropdowns. You can also create new credentials directly from the wizard.
  </Step>

  <Step title="Choose Datacenter Zone">
    Select an UpCloud zone (e.g., Helsinki, Frankfurt, Chicago, Amsterdam). Each zone shows the location and country.
  </Step>

  <Step title="Configure Nodes">
    Set your cluster topology:

    * **Bastion** — server plan for the SSH bastion host (e.g., `1xCPU-1GB`)
    * **Control Plane** — count (1 or 3) and plan (e.g., `2xCPU-4GB`)
    * **Workers** — count and plan (e.g., 2x `4xCPU-8GB`)

    The wizard shows vCPUs, RAM, and monthly cost for each plan to help you choose.
  </Step>

  <Step title="Create & Track Progress">
    Click **Create** to start provisioning. A live progress view tracks every step — credential setup, router creation, network creation, gateway setup, SSH key deployment, bastion provisioning, server creation, k3s installation, and Ankra Agent setup. The cluster appears with an **offline** state until provisioning completes, then transitions to **online**.
  </Step>
</Steps>

### Managing from the Dashboard

Once your UpCloud cluster is online, you can manage it directly from the Ankra dashboard:

* **Scale workers** — go to **Cluster Settings** → **General** to scale worker nodes up or down
* **Upgrade Kubernetes** — upgrade the k3s version from cluster settings
* **Deprovision** — delete the cluster and all UpCloud resources from the **Danger Zone** in cluster settings

### Via the CLI

```bash theme={null}
# Create credentials first
ankra credentials upcloud create --name my-upcloud-token  # securely prompts for token
ankra credentials upcloud ssh-key create --name my-ssh-key --generate

# Create the cluster
ankra cluster upcloud create \
  --name my-cluster \
  --credential-id <upcloud-credential-id> \
  --ssh-key-credential-id <ssh-key-credential-id> \
  --zone fi-hel1 \
  --control-plane-count 1 \
  --control-plane-plan 2xCPU-4GB \
  --worker-count 2 \
  --worker-plan 4xCPU-8GB
```

### Via the API

```bash theme={null}
curl -X POST https://platform.ankra.app/api/v1/clusters/upcloud \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cluster",
    "credential_id": "<upcloud-credential-id>",
    "ssh_key_credential_id": "<ssh-key-credential-id>",
    "zone": "fi-hel1",
    "control_plane_count": 1,
    "control_plane_plan": "2xCPU-4GB",
    "worker_count": 2,
    "worker_plan": "4xCPU-8GB",
    "distribution": "k3s"
  }'
```

Every configuration parameter, the zone list, and server plans are in the [UpCloud Reference](/reference/upcloud).

***

## Node Groups

Node groups let you organize worker nodes into logical groups with independent server plans, counts, labels, and taints. Manage node groups from **Settings** > **Nodes** in the dashboard, or via the API.

### Node Group API Reference

All node-group operations are also available via the REST API — see the [UpCloud Node Group API](/reference/upcloud#node-group-api-reference).

For detailed usage examples, see [Hetzner Node Groups](/guides/hetzner-clusters#node-groups) — the API is identical across all providers.

***

## Legacy Worker Scaling

The legacy `scale-workers` and `worker-count` endpoints still work for backward compatibility.

<CodeGroup>
  ```bash CLI theme={null}
  ankra cluster upcloud workers <cluster_id>
  ankra cluster upcloud scale <cluster_id> 4
  ```

  ```bash cURL theme={null}
  curl https://platform.ankra.app/api/v1/clusters/upcloud/<cluster_id>/worker-count \
    -H "Authorization: Bearer $ANKRA_API_TOKEN"

  curl -X POST https://platform.ankra.app/api/v1/clusters/upcloud/<cluster_id>/scale-workers \
    -H "Authorization: Bearer $ANKRA_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"worker_count": 4}'
  ```
</CodeGroup>

<Note>
  For new clusters, prefer using [Node Groups](#node-groups) for more granular control.
</Note>

***

## Upgrading Kubernetes Version

You can upgrade the Kubernetes (k3s) version on all nodes in an UpCloud cluster. Upgrades are applied to control plane nodes first, then workers.

<Warning>
  * Only k3s clusters are supported for version upgrades.
  * Downgrades are not supported — k3s downgrades require an etcd snapshot restore.
  * You can only upgrade one minor version at a time (e.g., v1.33.x to v1.34.x, not v1.33.x to v1.35.x).
  * The cluster must be online with no active operations.
</Warning>

### Via the Dashboard

Go to your cluster → **Settings** → **General** to see the current k3s version and trigger an upgrade.

### Check Current Version

<CodeGroup>
  ```bash CLI theme={null}
  ankra cluster upcloud k8s-version <cluster_id>
  ```

  ```bash cURL theme={null}
  curl https://platform.ankra.app/api/v1/clusters/upcloud/<cluster_id>/k8s-version \
    -H "Authorization: Bearer $ANKRA_API_TOKEN"
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "current_version": "v1.34.4+k3s1",
  "distribution": "k3s"
}
```

### Upgrade Version

<CodeGroup>
  ```bash CLI theme={null}
  ankra cluster upcloud upgrade <cluster_id> v1.35.1+k3s1
  ```

  ```bash cURL theme={null}
  curl -X POST https://platform.ankra.app/api/v1/clusters/upcloud/<cluster_id>/upgrade-k8s-version \
    -H "Authorization: Bearer $ANKRA_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"target_version": "v1.35.1+k3s1"}'
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "previous_version": "v1.34.4+k3s1",
  "new_version": "v1.35.1+k3s1",
  "nodes_affected": 3
}
```

***

## Deprovisioning

Deprovisioning deletes all UpCloud resources (servers, networks, routers, gateways, SSH keys) and removes the cluster from Ankra.

<Warning>
  This action is irreversible. All data on the cluster will be permanently deleted.
</Warning>

### Via the Dashboard

Go to your cluster → **Settings** → **General** → **Danger Zone** and click **Deprovision Cluster**. You will be asked to confirm before the operation begins.

### Via CLI or API

<CodeGroup>
  ```bash CLI theme={null}
  ankra cluster upcloud deprovision <cluster_id>
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://platform.ankra.app/api/v1/clusters/upcloud/<cluster_id> \
    -H "Authorization: Bearer $ANKRA_API_TOKEN"
  ```
</CodeGroup>

***

## Architecture

An UpCloud cluster provisions the following infrastructure:

| Component            | Description                                        |
| -------------------- | -------------------------------------------------- |
| **Router**           | SDN router for network routing                     |
| **Private Network**  | Isolated network for inter-node communication      |
| **NAT Gateway**      | Network address translation for outbound traffic   |
| **Bastion Host**     | Jump server for secure SSH access to cluster nodes |
| **Control Plane(s)** | Kubernetes control plane servers                   |
| **Worker(s)**        | Kubernetes worker servers for running workloads    |
| **SSH Keys**         | Deployed to all servers for access                 |

All nodes are deployed within a private UpCloud SDN network. The bastion host provides the only external SSH access point, and a NAT gateway handles outbound traffic for nodes without public IPs.

***

## Troubleshooting

### Common Issues

| Issue                         | Solution                                                         |
| ----------------------------- | ---------------------------------------------------------------- |
| Cluster stuck in provisioning | Check UpCloud API token permissions and account quota            |
| Cannot scale workers          | Ensure cluster is online and no operations are running           |
| Invalid API token             | Re-validate at [UpCloud Control Panel](https://hub.upcloud.com/) |
| Server plan unavailable       | Try a different zone or plan                                     |

### UpCloud Account Quotas

UpCloud has default resource limits per account. If provisioning fails, check your quotas in the [UpCloud Control Panel](https://hub.upcloud.com/):

* Servers
* Networks
* Routers
* IP Addresses

Contact UpCloud support to increase limits if needed.