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

# Cluster Settings

> Configure agent connectivity, maintenance operations, and manage cluster lifecycle.

<Note>
  Cluster settings allow you to monitor connectivity, configure agent behaviour, perform maintenance operations, and manage the cluster lifecycle.
</Note>

## Accessing Cluster Settings

1. Navigate to your cluster from the sidebar.
2. Click **Settings** in the cluster navigation.
3. Select **General** to access connectivity, agent, and maintenance settings.

***

## Connectivity

Monitor the health of your cluster's connection to the Ankra platform.

### Agent Status

The Ankra Agent is a lightweight component deployed in your cluster that enables communication with the platform.

| Status           | Description                                           |
| ---------------- | ----------------------------------------------------- |
| **Connected**    | Agent is online and communicating normally            |
| **Disconnected** | Agent is not responding. Check your cluster's network |
| **Outdated**     | A newer agent version is available                    |
| **Error**        | Agent encountered an issue. Check logs for details    |

### Agent Version

View the currently installed agent version and check if updates are available.

<Steps>
  <Step title="Check Version">
    The **Connectivity** card shows your current agent version.
  </Step>

  <Step title="Upgrade if Available">
    If a newer version is available, click **Upgrade Agent** to update manually.
  </Step>
</Steps>

<Tip>
  Enable auto-upgrade to automatically keep your agent up-to-date. See [Agent Settings](#agent-settings) below.
</Tip>

### Kubernetes Watch Status

The Watch service monitors Kubernetes resources and syncs state to the platform. The status indicator shows:

| Status      | Description                        |
| ----------- | ---------------------------------- |
| **Synced**  | All resources are synchronized     |
| **Syncing** | Synchronization in progress        |
| **Error**   | Sync failed. Click to view details |

***

## Agent Settings

Configure how the agent behaves on this specific cluster.

### Auto-upgrade Agent

Control whether the agent automatically upgrades when new versions are released.

| Setting                       | Behavior                                                          |
| ----------------------------- | ----------------------------------------------------------------- |
| **Inherit from Organisation** | Uses the organisation's auto-upgrade setting                      |
| **Enabled**                   | Agent upgrades automatically (overrides organisation if disabled) |
| **Disabled**                  | Agent stays at current version (opt-out of organisation setting)  |

<Info>
  When auto-upgrade is enabled at the organisation level, individual clusters can opt-out. When disabled at the organisation level, clusters cannot enable it.
</Info>

**To configure auto-upgrade:**

1. Go to cluster **Settings** → **General**
2. Find the **Agent Settings** card
3. Toggle **Auto-upgrade Agent** as desired

***

## Maintenance

Perform maintenance operations on your cluster.

### Generate Import Token

Create a token for re-importing the cluster or connecting from a different location.

<Steps>
  <Step title="Access Maintenance">
    Go to cluster **Settings** → **General** and find the **Maintenance** card.
  </Step>

  <Step title="Generate Token">
    Click **Generate Import Token**.
  </Step>

  <Step title="Use the Token">
    Copy the token and use it with the installation command on your cluster.
  </Step>
</Steps>

<Warning>
  Import tokens are single-use and expire after a set period. Generate a new one if needed.
</Warning>

### Sync All Resources

Force a full synchronization of all Kubernetes resources from your cluster to the platform.

<Steps>
  <Step title="Access Maintenance">
    Go to cluster **Settings** → **General** and find the **Maintenance** card.
  </Step>

  <Step title="Trigger Sync">
    Click **Sync All Resources**.
  </Step>

  <Step title="Monitor Progress">
    Watch the Kubernetes Watch Status indicator for sync completion.
  </Step>
</Steps>

**When to sync manually:**

* After network issues that may have caused missed updates
* When resources appear out of sync in the platform
* After bulk changes to Kubernetes resources outside of Ankra

***

## Nodes Settings

The **Nodes** tab is available for cloud provider clusters (Hetzner, OVH, UpCloud) and lets you manage node groups.

### Node Groups

Each node group has its own instance type, node count, labels, and taints. From this tab you can:

* **View** all node groups with their current configuration
* **Add** new node groups with a specific instance type and count
* **Scale** individual groups up or down (0–100 nodes)
* **Upgrade** instance type (upgrade only downgrades require creating a new group)
* **Edit** Kubernetes labels and taints per group
* **Delete** a node group and all its servers

<Warning>
  Instance type upgrades are irreversible due to Hetzner disk resize limitations. To use a smaller instance type, create a new node group and delete the old one.
</Warning>

For API and CLI usage, see the provider-specific documentation:

* [Hetzner Node Groups](/guides/hetzner-clusters#node-groups)
* [OVH Node Groups](/guides/ovh-clusters#node-groups)
* [UpCloud Node Groups](/guides/upcloud-clusters#node-groups)

<Note>
  Node groups are only available for clusters provisioned through Ankra (Hetzner, OVH, UpCloud). Imported clusters do not support node group management.
</Note>

***

## GitOps Settings

Configure Git repository integration for GitOps workflows.

### Connecting a Repository

<Steps>
  <Step title="Navigate to GitOps">
    Go to cluster **Settings** → **GitOps**.
  </Step>

  <Step title="Select Credential">
    Choose a GitHub credential from your organisation's configured credentials.
  </Step>

  <Step title="Connect Repository">
    Enter your repository details and connect.
  </Step>
</Steps>

For detailed GitOps configuration, see [GitOps](/concepts/gitops).

### Webhook Status

Monitor webhook delivery status to ensure Git events trigger deployments:

| Status       | Description                                         |
| ------------ | --------------------------------------------------- |
| **Active**   | Webhook is configured and receiving events          |
| **Inactive** | Webhook needs configuration                         |
| **Error**    | Webhook delivery failing. Check repository settings |

***

## Metrics Settings

Configure metrics collection for observability features.

### Prometheus Data Source

Connect an external Prometheus instance to enable metrics visualization in Ankra.

<Steps>
  <Step title="Navigate to Metrics">
    Go to cluster **Settings** → **Metrics**.
  </Step>

  <Step title="Configure Data Source">
    Enter your Prometheus endpoint URL.
  </Step>

  <Step title="Test Connection">
    Verify the connection is successful.
  </Step>
</Steps>

For detailed Prometheus setup, see [Prometheus Integration](/integrations/prometheus).

***

## Encryption Settings

Configure SOPS decryption for encrypted stacks on this cluster.

### Enable SOPS Decryption

Allow this cluster to decrypt SOPS-encrypted values during deployment.

<Steps>
  <Step title="Navigate to Encryption">
    Go to cluster **Settings** → **Encryption**.
  </Step>

  <Step title="Enable Decryption">
    Toggle on **Enable SOPS Decryption**.
  </Step>

  <Step title="Wait for Configuration">
    Ankra configures ArgoCD with the decryption key.
  </Step>
</Steps>

<Warning>
  SOPS decryption requires ArgoCD. The toggle is disabled if ArgoCD is not installed.
</Warning>

For complete SOPS documentation, see [SOPS Encryption](/guides/sops).

***

## Kubernetes Settings

Monitor Kubernetes resource synchronization status in detail.

### Accessing Kubernetes Settings

1. Navigate to your cluster → **Settings** → **Kubernetes**
2. View the resource sync status table

### Resource Sync Status Table

The sync status table shows synchronization details for each Kubernetes resource type:

| Column             | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| **Resource Type**  | The Kubernetes resource kind (Deployments, Services, etc.) |
| **Status**         | Current sync state for this resource type                  |
| **Resource Count** | Number of resources of this type tracked                   |
| **Last Sync**      | When this resource type was last synchronized              |
| **Errors**         | Number of sync errors (if any)                             |

### Sync Status Values

| Status           | Description                                          |
| ---------------- | ---------------------------------------------------- |
| **Synced**       | All resources of this type are synchronized          |
| **Syncing**      | Synchronization is currently in progress             |
| **Stale**        | Resources may be out of date. Sync pending           |
| **Error**        | Sync failed for some resources. Check error messages |
| **Disconnected** | Cluster is offline. Sync unavailable                 |
| **Initializing** | First-time sync in progress                          |

### Table Features

* **Auto-refresh**: The table updates automatically every 10 seconds
* **Filtering**: Filter by resource type or status
* **Sorting**: Click column headers to sort
* **Error Details**: Expand error rows to see specific error messages

### Offline Cluster Warning

When a cluster is offline, a warning banner appears indicating that Kubernetes settings are unavailable until the cluster reconnects.

### Refreshing Sync Status

Click **Refresh** to manually trigger a status update. This fetches the latest synchronization state from the cluster.

***

## Variables Settings

Cluster variables apply to all stacks deployed to this cluster.

For complete variable documentation, see [Variables](/concepts/variables).

***

## Danger Zone

<Warning>
  Actions in the Danger Zone are destructive. Some operations cannot be undone.
</Warning>

### Disconnect Cluster

Remove the cluster from Ankra without affecting running workloads.

**What happens:**

* The cluster is removed from the Ankra platform
* Running workloads continue to run
* ArgoCD and other installed components remain
* GitOps synchronization stops

<Steps>
  <Step title="Access Danger Zone">
    Go to cluster **Settings** → **General** and scroll to **Danger Zone**.
  </Step>

  <Step title="Disconnect">
    Click **Disconnect Cluster**.
  </Step>

  <Step title="Confirm">
    Confirm the disconnection.
  </Step>
</Steps>

<Info>
  You can reconnect a disconnected cluster by importing it again with a new token.
</Info>

### Delete Kubernetes

Destroy all cloud infrastructure (servers, networks, SSH keys) while keeping the cluster registered in Ankra. The cluster moves to a **stopped** state.

**What happens:**

* All cloud provider servers are deleted (you stop being billed for infrastructure)
* Network and SSH keys are removed from the cloud provider
* The cluster record, credentials, stacks, and configuration history are preserved in Ankra
* The cluster can be brought back online by adding a new node group

**Scaling back up:**

When you add a node group to a stopped cluster, Ankra automatically:

1. Restores the control plane infrastructure (bastion, network, SSH keys, control plane servers)
2. Installs Kubernetes on the new control plane nodes
3. Creates the worker nodes from the new node group
4. Begins reconciling stacks and addons

The cluster gets fresh infrastructure with new servers and IPs. Previously running workloads are not preserved, but stacks and addons configured in Ankra will be redeployed automatically.

<Note>
  This is available for cloud provider clusters (Hetzner, OVH, UpCloud). See [Hetzner Clusters - Delete Kubernetes](/guides/hetzner-clusters#delete-kubernetes) for provider-specific details.
</Note>

### Terminate Cluster

Permanently remove the cluster and all its cloud resources from Ankra. The cluster cannot be recovered.

<Warning>
  This action cannot be undone. All cloud infrastructure will be destroyed and the cluster record will be permanently removed.
</Warning>

**Considerations before terminating:**

* Ensure no active operations are running
* Clean up cloud-provider-managed resources (Load Balancers, Volumes) that Ankra does not track
* Back up stack configurations if needed
* Inform team members who use this cluster

***

## Best Practices

<Tip>
  **Enable auto-upgrade**: Keep your agents up-to-date for the latest features and security patches.
</Tip>

<Tip>
  **Monitor connectivity**: Regularly check agent status, especially after network changes.
</Tip>

<Tip>
  **Use cluster variables**: Define environment-specific values at the cluster level to keep stacks reusable.
</Tip>

<Tip>
  **Configure metrics early**: Set up Prometheus integration to enable observability features from the start.
</Tip>

***

## Related

<CardGroup cols={2}>
  <Card title="Cluster Agent" icon="robot" href="/concepts/cluster-agent">
    Learn about the Ankra Agent.
  </Card>

  <Card title="Variables" icon="code" href="/concepts/variables">
    Configure cluster variables.
  </Card>

  <Card title="SOPS Encryption" icon="lock" href="/guides/sops">
    Set up encryption for this cluster.
  </Card>

  <Card title="Organisation Settings" icon="building" href="/platform/organisation-settings">
    Configure organisation-level settings.
  </Card>
</CardGroup>