Contact UsGet started

Connecting to a node via OS Login

Written by
Updated at December 4, 2024

OS Login is used instead of SSH keys to access Yandex Cloud virtual machines via SSH. With OS Login, you can connect to Managed Service for Kubernetes nodes.

Individual nodes in node groups are Yandex Compute Cloud virtual machines with automatically generated names. To configure nodes, follow the instructions below or other node group management guides.

Alert

Do not change node VM settings, including names, network interfaces, and SSH keys, using the Compute Cloud interfaces or SSH connections to the VM.

This can disrupt the operation of individual nodes, groups of nodes, and the whole Managed Service for Kubernetes cluster.

Configure your cluster node and then connect to it using one of the two methods:

Getting started

  1. If you do not have the Yandex Cloud command line interface yet, install and initialize it.

    The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

  2. Enable access via OS Login at the organization level.

  3. Enable access to nodes from the internet for the node group containing the node you need to connect to.

  4. Make sure the account you are using to connect to the node has one of these roles assigned:

    • compute.osLogin: To access the node without sudo permissions.
    • compute.osAdminLogin: To access the node with sudo permissions.

Configure the node

Set up your cluster node for connection:

  1. Make sure to enable external access for the node.

  2. Activate node access via OS Login by changing the method of connecting to nodes.

    Note

    After the connection method is changed, the node group status will temporarily change to Reconciling: all the group's nodes will be recreated for the changes to take effect.

    1. Open the Managed Service for Kubernetes section in the folder containing the Managed Service for Kubernetes cluster whose node you need access to.

    2. Click the name of the Managed Service for Kubernetes cluster.

    3. Go to the Node group tab.

    4. Select the required node group.

    5. Click Edit in the top-right corner.

    6. Select Access by OS Login.

      Warning

      If access via OS Login is enabled, access via SSH keys will be unavailable.

    7. Click Save.

    If you do not have the Yandex Cloud command line interface yet, install and initialize it.

    The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

    To enable OS Login for all nodes in a node group:

    1. View the description of the CLI command for adding and updating the Managed Service for Kubernetes node group metadata:

      yc managed-kubernetes node-group add-metadata --help

    2. Run this command:

      yc managed-kubernetes node-group add-metadata \
  --name <node_group_name> \
  --metadata enable-oslogin=true

      You can request the name of a node group with a list of node groups in the folder.

      Warning

      If access via OS Login is enabled, access via SSH keys will be unavailable.

    1. Open the current Terraform configuration file describing the Managed Service for Kubernetes node group.

      For more information about creating this file, see Creating a node group.

    2. Add the instance_template.metadata parameter to the node group description, or change it if it already exists.

      In this parameter, specify the enable-oslogin metadata key with the true value:

      resource "yandex_kubernetes_node_group" "<node_group_name>" {
  cluster_id = yandex_kubernetes_cluster.<cluster_name>.id
  ...
  instance_template {
    metadata = {
      "enable-oslogin" = "true"
      ...
    }
    ...
  }
  ...
}

      Warning

      If access via OS Login is enabled, access via SSH keys will be unavailable.

    3. Make sure the configuration files are correct.

      1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

      2. Run the command:

        terraform validate

        If there are errors in the configuration files, Terraform will point to them.

    4. Confirm updating the resources.

      1. Run the command to view planned changes:

        terraform plan

        If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

      2. If you are happy with the planned changes, apply them:

        1. Run the command:

          terraform apply

        2. Confirm the update of resources.

        3. Wait for the operation to complete.

    For more information, see the Terraform provider documentation.

    1. Get all the existing metadata for the node group using the get REST API method for the NodeGroup resource, and provide the node group ID in the nodeGroupId request parameter.

      You can request the name of a node group with a list of node groups in the folder.

      The metadata will be listed as key=value pairs in the nodeTemplate.metadata field of the response.

    2. Use the update API method and include the following in the request:

      • Node group ID in the nodeGroupId parameter.

      • updateMask parameter set to nodeTemplate.metadata.

        Warning

        The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the updateMask parameter as a single comma-separated string.

      • nodeTemplate.metadata parameter listing all existing node group metadata as key=value pairs without modification.

        For the enable-oslogin key, replace the current value with true. If there is no such key, add it.

        Warning

        If access via OS Login is enabled, access via SSH keys will be unavailable.

        Example of listing metadata in a parameter

        • Existing metadata keys in a node group:

          "nodeTemplate": {
    "metadata": {
        "enable-oslogin": "undefined",
        "<existing_key_1>": "<existing_value_1>",
        "<existing_key_2>": "<existing_value_2>"
    },
    ...
}

        • Metadata keys to provide in an API request:

          "nodeTemplate": {
    "metadata": {
        "enable-oslogin": "true",
        "<existing_key_1>": "<existing_value_1>",
        "<existing_key_2>": "<existing_value_2>"
    }
}

        Alert

        Any metadata not listed in the nodeTemplate.metadata parameter will be deleted.

        Then the node group status will temporarily change to Reconciling: all the nodes in the group will be recreated for the changes to apply.

Connect to the node using the CLI

  1. View the description of the CLI command for connection to the node:

    yc compute ssh --help

  2. To find out the name of the node you need, get a list of cluster nodes.

    yc managed-kubernetes node-group list-nodes --name <node_group_name>

    Result example:

    +----------------------+-----------------+---------------------------+-------------+--------+
| CLOUD INSTANCE       | KUBERNETES NODE | RESOURCES                 | DISK        | STATUS |
+----------------------+-----------------+---------------------------+-------------+--------+
| fhmmh23ugigb******** | <node_name>      | 4 100% core(s), 8.0 GB of | 64.0 GB ssd | READY  |
| RUNNING_ACTUAL       |                 | memory                    |             |        |
+----------------------+-----------------+---------------------------+-------------+--------+

  3. Connect to the node:

    yc compute ssh --name <node_name>

Connect to the node using the SSH

  1. Export the OS Login certificate.

    Note

    The certificate is valid for one hour. After this time has elapsed, you will need to export a new certificate to connect to the node.

  2. Find out the public address of the node:

    1. Get the node group ID:

      yc managed-kubernetes node-group list

      Result:

      +------------------------------+----------------------+-----------+----------------------+---------------------+---------+------+
|          ID                  |      CLUSTER ID      |   NAME    |  INSTANCE GROUP ID   |     CREATED AT      | STATUS  | SIZE |
+------------------------------+----------------------+-----------+----------------------+---------------------+---------+------+
| <node_group_ID> | cato4gqs0ave******** | ng-name   | cl17a1c3mbau******** | 2024-02-08 04:25:06 | RUNNING |    1 |
+------------------------------+----------------------+-----------+----------------------+---------------------+---------+------+

      You will find the parameter you need in the ID column.

    2. View the list of Managed Service for Kubernetes nodes that belong to this group:

      yc compute instance-group list-instances <node_group_ID>

      Result:

      +----------------------+---------------------------+----------------+-------------+----------------------+----------------+
|     INSTANCE ID      |           NAME            |  EXTERNAL IP   | INTERNAL IP |        STATUS        | STATUS MESSAGE |
+----------------------+---------------------------+----------------+-------------+----------------------+----------------+
| fhm8nq5p7t0r******** | cl12kvrgj493rhrkimmb-**** | 84.201.156.211 | 10.128.0.36 | RUNNING_ACTUAL [25m] |                |
+----------------------+---------------------------+----------------+-------------+----------------------+----------------+

      The public IP address of the Managed Service for Kubernetes node is listed in the EXTERNAL IP column.

  3. Connect to the VM:

    ssh -i <certificate_file_path> <user_login>@<node_public_IP_address>

    Where:

    • <path_to_certificate_file>: Path to the previously saved Identity file of the certificate. For example, /home/user1/.ssh/yc-cloud-id-b1gia87mbaom********-orgusername.
    • <user_login>: User login as set in their OS Login profile. It is also appended to the name of the exported OS Login certificate. In the example above, it is orgusername.
    • <node_public_IP_address>: Public IP address of the node obtained earlier.

    If this is your first time connecting to the node, you will get an unknown host warning:

    The authenticity of host '158.160.**.** (158.160.**.**)' can't be established.
ECDSA key fingerprint is SHA256:PoaSwqxRc8g6iOXtiH7ayGHpSN0MXwUfWHk********.
Are you sure you want to continue connecting (yes/no)?

    Type yes in the terminal and press Enter.

Previous
Connecting to a node over SSH
Next
Updating Kubernetes