Connecting external nodes to a cluster

You can connect external servers as nodes 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.

Getting startedGetting started

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

   To create an external node group, the Managed Service for Kubernetes cluster must operate in tunnel mode. You can only enable this mode when creating the cluster.

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

Creating a node groupCreating a node group

Updating a node groupUpdating a node group

If required, you can edit the node group, e.g., add more IP addresses.

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

Installing system componentsInstalling system components

To connect servers to a Managed Service for Kubernetes cluster, you need to install their system components.

You can install system components using one of the following methods:

• Automated installation
• Semi-automated installation

Automated installationAutomated installation

With automated installation, the Managed Service for Kubernetes cluster connects to the server over SSH and installs all required system components all by itself.

To run an automated installation:

1. In your Managed Service for Kubernetes cluster, create a secret with a private SSH key for connection to the server:

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

2. Specify the name of the secret in the node group specification:

   Management console

   CLI

   1. On the Managed Service for Kubernetes cluster page, go to the Node manager tab.
   2. Select the new Managed Service for Kubernetes node group from the list.
   3. In the top-right corner, click Edit.
   4. In the Secret with private SSH key field, select the new secret from the drop-down list.
   5. Click Save.

   1. Run this command:

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

   2. Edit the specification:

      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
      

Semi-automated installationSemi-automated installation

With semi-automated installation, you prepare the server manually by installing the maintainer component and setting up access for the Managed Service for Kubernetes cluster. With that done, the maintainer component will automatically download and install the remaining system components.

To run a semi-automated installation:

1. Use kubectl to get a secret containing kubeconfig for the server you are connecting and save it to a file:

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

   This secret becomes available after the node group is created in the Managed Service for Kubernetes cluster.

2. Move the kube.config file to the server:

   scp kube.config root@<server_public_IP_address>:/
   

3. Connect to the server:

   ssh root@<server_public_IP_address>
   

4. Create a folder named /etc/yandex-maintainer and move the kube.config file into it:

   sudo mkdir -p /etc/yandex-maintainer
   sudo mv /kube.config /etc/yandex-maintainer/
   

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

External node status checksExternal node status checks

Once the system components have been installed, the servers will initiate Managed Service for Kubernetes cluster connections. Once the connection is complete, the new cluster nodes will get the Ready status.

To check the node status:

kubectl get node -o wide -w

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

Disabling external nodesDisabling external nodes

TroubleshootingTroubleshooting

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

kubectl -n yandex-system get events

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

journalctl -u yandex-maintainer
journalctl -u kubelet

Consider the external Managed Service for Kubernetes node connection requirements.

See alsoSee also

• Configuring WireGuard gateways to connect external nodes
• Configuring IPSec gateways to connect external nodes