Connecting external nodes to the cluster

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 clusterRequirements 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 startedGetting started

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

2. Install kubectl and configure it to work with the created 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 groupCreating a node group

Adding nodes to a clusterAdding nodes to a cluster

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

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:

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

Installing system components on connecting serversInstalling system components on connecting servers

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

• Automated installation
• Semi-automated installation

Automated installAutomated 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:

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 installationSemi-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/maintainer
   sudo vi /etc/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 clusterDeleting external nodes from a cluster

kubectl -n yandex-system edit nodegroup

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 appropriate server:

journalctl -u maintainer
journalctl -u kubelet

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