Contact UsGet started

Connecting external nodes to the cluster

Written by
Improved by
Updated at May 5, 2025

Note

Connecting external nodes to a Managed Service for Kubernetes cluster is at the Preview stage. You will not be charged for using them.

You can connect external servers to a Managed Service for Kubernetes cluster using special Kubernetes API resources. The definitions (CustomResourceDefinitions) of these resources are automatically pre-installed in a Managed Service for Kubernetes cluster.

Requirements for connecting external nodes to a cluster

For external nodes to connect to a Managed Service for Kubernetes cluster, both the cluster and the connecting servers must meet certain requirements.

Getting started

  1. Create a Managed Service for Kubernetes cluster with any suitable configuration.

  2. Install kubect and configure it to work with the new cluster.

  3. Create a node group object in the Managed Service for Kubernetes cluster's Kubernetes API.

    Once you have created a group object, you can add nodes to and delete nodes from the Managed Service for Kubernetes cluster.

    If you have connection issues, see the Troubleshooting section.

Creating a node group

Note

To create an external node group, make sure the Managed Service for Kubernetes cluster is running in tunnel mode. For more information, see Requirements for connecting external nodes to a cluster.

  1. On the Managed Service for Kubernetes cluster page, go to the Node manager tab.
  2. Click Create a node group and then External.
  3. Enter a name for the Managed Service for Kubernetes node group.
  4. Click Add.

  1. Save the specification of the NodeGroup type object for the Managed Service for Kubernetes group from the mks.yandex.cloud/v1alpha1 API in yandex-system namespace to a YAML file named ext-nodegroup.yaml:

    apiVersion: mks.yandex.cloud/v1alpha1
kind: NodeGroup
metadata:
  name: external-node-group
  namespace: yandex-system

  2. Create an external Managed Service for Kubernetes node group:

    kubectl apply -f ext-nodegroup.yaml

Adding nodes to a cluster

  1. On the Managed Service for Kubernetes cluster page, go to the Node manager tab.
  2. Select the required Managed Service for Kubernetes node group.
  3. Click Edit.
  4. Enter the IP address of the connecting server accessible from the Managed Service for Kubernetes cluster's cloud network.
  5. Click Add IP address to add more IP addresses if needed.
  6. Click Save.

In the Managed Service for Kubernetes node group object specification, list the IP addresses of the connecting servers accessible from the Managed Service for Kubernetes cluster's cloud network:

kubectl -n yandex-system edit nodegroup external-node-group

For example:

apiVersion: mks.yandex.cloud/v1alpha1
kind: NodeGroup
metadata:
 name: external-node-group
 namespace: yandex-system
spec:
 ips: # List the IP addresses of the connecting servers accessible from the Managed Service for Kubernetes cluster's cloud network.
 - 10.130.0.4
 - 10.130.1.5

Afterwards, you need to install system components on the connecting servers.

Once the system components have been installed, the servers will initiate Managed Service for Kubernetes cluster connections.

A node connection to a Managed Service for Kubernetes cluster is complete when new Ready nodes become available in the cluster:

  1. Go to the details of the relevant Managed Service for Kubernetes node group.
  2. Select the Node manager tab.
kubectl get node -o wide -w

Result:

NAME       STATUS  ROLES   AGE    VERSION  INTERNAL-IP  EXTERNAL-IP  OS-IMAGE            KERNEL-VERSION    CONTAINER-RUNTIME
...
ext-node2  Ready   <none>  4m03s  v1.20.6  10.130.0.4   <none>       Ubuntu 20.04.3 LTS  5.4.0-42-generic  docker://20.10.8
ext-node1  Ready   <none>  4m25s  v1.20.6  10.130.1.5   <none>       Ubuntu 20.04.3 LTS  5.4.0-42-generic  docker://20.10.8

Installing system components on connecting servers

You can install system components and add nodes to a Managed Service for Kubernetes cluster through:

Automated install

For an automated installation, create a secret with a private server connection SSH key in your Managed Service for Kubernetes cluster. Create a secret:

kubectl -n yandex-system create secret generic <secret_name> --from-file=ssh-privatekey=<SSH_key_file_path> --type=kubernetes.io/ssh-auth

In the NodeGroup resource specification, provide the name of the relevant secret:

  1. Go to the details of the relevant Managed Service for Kubernetes node group.
  2. Click Edit.
  3. Select the desired secret from the drop-down list.
  4. Click Save.
kubectl -n yandex-system edit nodegroup external-node-group

apiVersion: mks.yandex.cloud/v1alpha1
kind: NodeGroup
metadata:
  name: external-node-group
  namespace: yandex-system
spec:
  ips:
  ...
  provisionBySsh:
    sshKeySecret:
      name: <secret_name>
      namespace: yandex-system

All Managed Service for Kubernetes external nodes must allow root login access with the specified SSH key.

Semi-automated installation

For semi-automated installation, you need to install on all Managed Service for Kubernetes external nodes the basic component and the configuration required for subsequent installation of the system components.

  1. After you create a NodeGroup object, a secret becomes available in the Managed Service for Kubernetes cluster. The secret contains kubeconfig you will need on the servers you are going to connect. Get the secret using kubectl configured to communicate with the Managed Service for Kubernetes cluster and save it to a file:

    kubectl -n yandex-system get secret <NodeGroup_object_name>-maintainer-kube-config -o json | jq -r '.data."kube-config"' | base64 -d

  2. Save kubeconfig you just got on the server you are connecting:

    sudo mkdir -p /etc/yandex-maintainer
sudo vi /etc/yandex-maintainer/kube.config # Use this file to save the contents of `kubeconfig` you got in the previous step.

  3. Run the commands below on a connecting server:

    sudo mkdir -p /home/kubernetes/bin
sudo curl --output /home/kubernetes/bin/maintainer https://storage.yandexcloud.net/mk8s-maintainer/v1/maintainer
sudo chmod +x /home/kubernetes/bin/maintainer
sudo /home/kubernetes/bin/maintainer install

Deleting external nodes from a cluster

  1. Go to the details of the relevant Managed Service for Kubernetes node group.
  2. Click Edit.
  3. Delete the IP addresses of the appropriate Managed Service for Kubernetes nodes.
  4. Click Save.

To disconnect the Managed Service for Kubernetes nodes, delete their IP addresses from the spec.ips field of the NodeGroup resource:

kubectl -n yandex-system edit nodegroup

Troubleshooting

If there are any issues, review the events in the yandex-system namespace first:

  1. On the Managed Service for Kubernetes cluster page, go to the Events tab.
  2. Select the yandex-system namespace.
kubectl -n yandex-system get events

If there is not enough information, review the system component logs on the appropriate server:

journalctl -u yandex-maintainer
journalctl -u kubelet

Keep in mind the external Managed Service for Kubernetes node connection requirements.

Previous
Deleting a node group
Next
All tutorials