Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Creating a self-managed Kubernetes cluster using the Yandex Cloud provider for the Kubernetes Cluster API

Written by
Updated at November 21, 2025

Cluster-api-provider-yandex is a provider for deploying a self-managed Kubernetes cluster in Yandex Cloud infrastructure using the Kubernetes Cluster API.

The cluster is deployed based on Yandex Compute Cloud virtual machines and a Yandex Application Load Balancer.

Advantages of using the Yandex Cloud provider for creating clusters:

  • Integration with the Yandex Cloud API.
  • Declarative approach to cluster creation and management.
  • Describing a cluster as a custom resource, i.e., CustomResourceDefinition.
  • Numerous parameters for configuring cluster compute resources.
  • Custom OS images for the master and worker nodes.
  • Custom control plane.
  • Alternative to Terraform for CI pipelines.

Provider compatibility with the Kubernetes Cluster API

Provider version Cluster API version
v1alpha1 v1beta1 (v1.x)

To deploy a Kubernetes cluster in Yandex Cloud using the Cluster API:

  1. Get your cloud ready.
  2. Set up your environment.
  3. Prepare an OS image for cluster nodes.
  4. Get a Docker image with the Yandex Cloud provider.
  5. Install the Yandex Cloud provider and the Kubernetes Cluster API provider.
  6. Generate cluster manifests.
  7. Deploy a cluster.
  8. Connect to the cluster.
  9. Install a CCM.
  10. Install a CNI.
  11. Check the connection between the management cluster and the new cluster.

If you no longer need the resources you created, delete them.

Get your cloud ready

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

The infrastructure support costs include:

Optional costs

  • If intending to use a custom image for the new Kubernetes cluster nodes:
  • If intending to use a custom Docker image to deploy the Yandex Cloud provider in the management cluster, fee for storing the Docker image in the registry and outgoing traffic (see Yandex Container Registry pricing).

Set up your infrastructure

  1. Set up a Yandex Cloud service account:

    1. Create a service account you will use to create resources for the cluster.
    2. Assign the compute.editor and alb.editor roles for the folder to the service account.
    3. Create an authorized key for the service account in JSON format.

  2. If your folder does not have a Virtual Private Cloud network yet, create one. Create a subnet as well.

  3. The new cluster infrastructure will automatically be assigned the default security group which is created along with the network. Add the following rules for incoming traffic to this group:

    Protocol Port range Source type Source Description
    TCP 0-65535 Security group Balancer Health checks by an L7 load balancer
    Any 8443 CIDR 0.0.0.0/0 Access to the Kubernetes API

  4. The created cluster will be accessible within the cloud network via an internal IP address. To enable remote access to the cluster:

    1. Create an auxiliary VM with a public IP address and the default security group in the same network where your cluster will be deployed.
    2. Install kubectl on the auxiliary VM.

  5. Create a Managed Service for Kubernetes management cluster with a public IP address and a node group. You will need this cluster to deploy the new cluster using the Cluster API and to manage the cluster infrastructure.

    Tip

    You can also deploy the management cluster locally, e.g., using kind.

  6. To enable the new cluster to access the internet and pull Docker images, configure a NAT gateway for the subnet that will host the new cluster.

Set up your environment

Set up the environment locally.

  1. Install the following tools:

  2. Configure kubectl access to the Managed Service for Kubernetes management cluster.

    If you deployed the management cluster locally with kind, follow this guide to configure cluster access.

  3. Clone the cluster-api-provider-yandex repository and navigate to the project directory.

    git clone https://github.com/yandex-cloud/cluster-api-provider-yandex.git
cd cluster-api-provider-yandex

Set up an OS image for cluster nodes

The OS image to deploy on the nodes of the new cluster must be configured to support the Kubernetes Cluster API and compatible with Compute Cloud.

You can use a ready-made test image or build a custom one:

To use a test Ubuntu 24.04 image configured for Kubernetes 1.31.4, specify the fd8a3kknu25826s8hbq3 image ID in the YANDEX_CONTROL_PLANE_MACHINE_IMAGE_ID variable when generating the cluster manifest.

Warning

This image is for demonstration purposes only, do not use it in production.

  1. Build a custom OS image using Image Builder.

    See also: Setting up a disk image for Compute Cloud.

  2. Upload the image to Compute Cloud and save its ID.

Get a Docker image with the Yandex Cloud provider

You can use a ready-made Docker image with the Yandex Cloud provider from a public Yandex Container Registry or build your own image from the source code.

  1. Authenticate in your Container Registry using the Docker credential helper.

  2. Add the path to the Docker image with the Yandex Cloud provider in the public registry to the IMG environment variable:

    export IMG=cr.yandex/crpsjg1coh47p81vh2lc/capy/cluster-api-provider-yandex:latest

  1. Create a Container Registry and save its ID.

  2. Authenticate in your Container Registry using the Docker credential helper.

  3. Add the path for storing the new Docker image in the registry to the IMG environment variable:

    export IMG=cr.yandex/<registry_ID>/cluster-api-provider-yandex:<tag>

  4. If you are building your Docker image on a non-AMD64 computer, edit the docker-build section in the Makefile:

    docker build --platform linux/amd64 -t ${IMG} .

  5. Run the Docker daemon.

  6. Build a Docker image and push it to the registry:

    make docker-build docker-push

Install the Yandex Cloud provider and the Kubernetes Cluster API provider

  1. Initialize the management cluster:

    clusterctl init

    The management cluster will include the core components of the Kubernetes Cluster API and cert-manager.

  2. Create a CustomResourceDefinitions resource (CRD) for the new cluster:

    make install

  3. Get the list of installed CRDs:

    kubectl get crd | grep cluster.x-k8s.io

    To get the manifest of a specific CRD, run the following command:

    kubectl get crd <CRD_name> \
  --output yaml

  4. Create a namespace for the Yandex Cloud provider:

    kubectl create namespace capy-system

  5. Create a secret with the authorized key for the Yandex Cloud service account:

    kubectl create secret generic yc-sa-key \
  --from-file=key=<path_to_file_with_authorized_key> \
  --namespace capy-system

  6. Install the Yandex Cloud provider:

    make deploy

Generate cluster manifests

  1. Get the IDs of the Yandex Cloud resources required to deploy the cluster:

  2. Add the IDs to these environment variables:

    export YANDEX_CONTROL_PLANE_MACHINE_IMAGE_ID=<image_ID>
export YANDEX_FOLDER_ID=<folder_ID>
export YANDEX_NETWORK_ID=<network_ID>
export YANDEX_SUBNET_ID=<subnet_ID>
export YANDEX_ZONE_ID=<availability_zone_ID>

    If you did not build a custom OS image, set the YANDEX_CONTROL_PLANE_MACHINE_IMAGE_ID variable to fd8a3kknu25826s8hbq3. This is the ID of a test Ubuntu 24.04 image compatible with Kubernetes 1.31.4.

  3. Generate cluster manifests:

    clusterctl generate cluster <name_of_new_cluster> \
  --from templates/cluster-template.yaml > /tmp/capy-cluster.yaml

    The capy-cluster.yaml manifest will describe the following:

    • Application Load Balancer with a dynamic internal IP address. You assign it a static IP address, if required.

      Warning

      Once the cluster is created, you will not be able to assign a static IP address to the L7 load balancer.

    • Three control plane nodes for the cluster.

  4. Optionally, to deploy worker nodes right away, add their description to the manifest.

    clusterctl generate cluster <name_of_new_cluster> \
    --worker-machine-count <number_of_worker_nodes> \
    --from templates/cluster-template.yaml > /tmp/capy-cluster.yaml

Optionally, configure the API server endpoint

Configure the L7 load balancer in the capy-cluster.yaml manifest:

  loadBalancer:
    listener:
      address: <static_IP_address_from_subnet_range>
      subnet:
        id: <subnet_ID>

Deploy the cluster

Run this command:

kubectl apply -f /tmp/capy-cluster.yaml

You can monitor the cluster creation progress in the Yandex Cloud management console and the capy-controller-manager pod logs:

kubectl logs <capy-controller-manager_pod_name> \
  --namespace capy-system \
  --follow

Connect to the cluster

The credentials for accessing the new cluster will be stored in the <name_of_new_cluster>-kubeconfig secret in the management cluster.

  1. Get the data from the secret:

    kubectl get secret <name_of_new_cluster>-kubeconfig \
  --output yaml | yq -r '.data.value' | base64 \
  --decode > capy-cluster-config

  2. Send the kubectl configuration file to the auxiliary VM:

    scp <path_to_capy-cluster-config_file_on_local_computer> \
<username>@<VM_public_IP_address>:/home/<username>/.kube/config

  3. Connect to the auxiliary VM over SSH.

  4. Make sure the new cluster is accessible:

    kubectl cluster-info

Install a CCM in the new cluster

For connection between the cluster resources and Yandex Cloud resources, install a cloud controller manager in the new cluster, e.g., the Kubernetes Cloud Controller Manager for Yandex Cloud.

Note

If you want to use the Kubernetes Cloud Controller Manager for Yandex Cloud, add the current version of the Docker image and the YANDEX_CLUSTER_NAME environment variable with the new cluster's name to the yandex-cloud-controller-manager.yaml manifest example for DaemonSet.

Install a CNI in the new cluster

To provide networking for pods in the new cluster, install a container network interface, such as Cilium or Calico.

For more information, see these docs:

Check the connection between the management cluster and the new cluster

  1. Connect to the auxiliary VM and make sure all pods with the required system components have been deployed in the cluster:

    kubectl get pods --all-namespaces

    Here is an example of the command output:

    NAMESPACE     NAME                                                       READY   STATUS    RESTARTS   AGE
kube-system   calico-kube-controllers-695bcfd99c-rcc42                   1/1     Running   0          3h55m
kube-system   calico-node-9qhxj                                          1/1     Running   0          3h55m
kube-system   coredns-7c65d6cfc9-52tvn                                   1/1     Running   0          4h50m
kube-system   coredns-7c65d6cfc9-dpgvg                                   1/1     Running   0          4h50m
kube-system   etcd-capy-cluster-control-plane-p646q                      1/1     Running   0          4h50m
kube-system   kube-apiserver-capy-cluster-control-plane-p646q            1/1     Running   0          4h50m
kube-system   kube-controller-manager-capy-cluster-control-plane-p646q   1/1     Running   0          4h50m
kube-system   kube-proxy-wb7jr                                           1/1     Running   0          4h50m
kube-system   kube-scheduler-capy-cluster-control-plane-p646q            1/1     Running   0          4h50m
kube-system   yandex-cloud-controller-manager-nwhwv                      1/1     Running   0          26s

  2. Use your local computer to check the connection between the management cluster and the new cluster:

    clusterctl describe cluster <name_of_new_cluster>

    Result:

    NAME                                                             READY  SEVERITY  REASON  SINCE  MESSAGE                                  
Cluster/capy-cluster                                             True                     10s
├─ClusterInfrastructure - YandexCluster/capy-cluster                                   
└─ControlPlane - KubeadmControlPlane/capy-cluster-control-plane  True                     10s                                                                                       
  └─3 Machines...                                                True                     3m9s   See capy-cluster-control-plane-cf72l, capy-cluster-control-plane-g9jw7, ...

Delete the resources you created

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

  1. Delete the Kubernetes cluster created using the Cluster API:

    kubectl delete -f /tmp/capy-cluster.yaml

  2. Delete the CRD from the Managed Service for Kubernetes management cluster:

    make uninstall

  3. Delete the Yandex Cloud provider controller from the management cluster:

    make undeploy

  4. Delete the auxiliary Yandex Cloud resources if you created them:

Previous
Encrypting secrets in Managed Service for Kubernetes
Next
Accessing the Yandex Cloud API from a Managed Service for Kubernetes cluster using a workload identity federation