========
Clusters
========

A **cluster** is a Kubernetes cluster managed through a cloud provider. Clusters
host the containers that run your deployments.

Creating a Cluster
==================

1. Navigate to **Clusters** in your project (``/_eyrie/clusters``).
2. Click **New Cluster**.
3. Fill in:

   - **Name** — a human-readable label (e.g. "us-east-dev").
   - **Cloud Provider** — select a previously configured provider.
   - **Node Groups** — define one or more node pools with a node type (e.g.
     Linode 4 GB), count, and availability zone.

4. Click **Create**.

.. image:: /static/img/cluster_list.png
   :alt: TODO — screenshot of the cluster list

.. image:: /static/img/create_cluster_form.png
   :alt: TODO — screenshot of the create cluster form

Manual Cluster Import
=====================

If you already have a Kubernetes cluster, select the **Manual** cloud provider
type and upload a kubeconfig file. Eyrie will connect to the cluster using the
provided credentials.

Cluster States
==============

A cluster moves through the following states:

- **Draft** — created but not yet provisioned.
- **Initializing** — cloud resources are being created and the cluster
  initialization Deployment Book is running.
- **Active** — ready to host deployments.
- **Transitioning** — a node pool change or upgrade is in progress.
- **Cancel** — marked for cancellation.
- **Delete** — being removed from the cloud provider.

Node Pools
==========

Each cluster has one or more **node pools**. A node pool defines a group of
identically sized nodes.

- **Adding** — click **Add Node Pool**, select a node type and count.
- **Recycling** — replace all nodes in a pool with fresh instances.
- **Deleting** — remove a pool (deployments must be migrated first).

.. image:: /static/img/cluster_detail_node_pools.png
   :alt: TODO — screenshot of cluster detail with node pools

Cluster Initialization
======================

When a cluster enters the **Initializing** state, Eyrie runs a Deployment Book
that installs required cluster-level components (ingress controllers,
certificate managers, storage drivers, etc.).

Kubernetes Version Upgrade
==========================

From the cluster detail page, trigger a Kubernetes version upgrade. The cluster
transitions to **Transitioning** while the upgrade is applied to the control
plane and node pools.